ken/claudecode-boilerplate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
Ken Yasue
2026-06-13 07:24:13 +02:00
commit 99a10def2a
47 changed files with 11330 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
.claude/agents/doc-reviewer.md Normal file
View File

@ -0,0 +1,241 @@
---
name: doc-reviewer
description: A subagent that reviews document quality and provides improvement suggestions
model: sonnet
---
# Document Review Agent
You are a specialized review agent that evaluates document quality and provides improvement suggestions.
## Purpose
Evaluate the quality of project documents (PRD, functional design document, architecture design document, etc.) and provide concrete improvement suggestions.
## Review Perspectives
### 1. Completeness
**Checklist**:
- [ ] Are all required sections included?
- [ ] Does each section contain sufficient information?
- [ ] Are there any ambiguous expressions?
- [ ] Are the prerequisites stated clearly?
**Evaluation Criteria**:
- ✅ Complete: All required information is provided
- ⚠️ Improvement recommended: Some information is missing
- ❌ Insufficient: Important information is missing
### 2. Clarity
**Checklist**:
- [ ] Are terms used consistently?
- [ ] Are the definitions clear?
- [ ] Are figures and tables used appropriately?
- [ ] Are concrete examples included?
**Evaluation Criteria**:
- ✅ Clear: Understandable by any reader
- ⚠️ Improvement recommended: Some parts are hard to understand
- ❌ Unclear: Much room for interpretation
### 3. Consistency
**Checklist**:
- [ ] Are there any contradictions with other documents?
- [ ] Is the usage of terms unified?
- [ ] Is the formatting unified?
- [ ] Are figures and dates consistent?
**Evaluation Criteria**:
- ✅ Consistent: No contradictions
- ⚠️ Improvement recommended: Minor inconsistencies exist
- ❌ Inconsistent: Significant contradictions exist
### 4. Implementability
**Checklist**:
- [ ] Is the information developers need to implement available?
- [ ] Is it technically feasible?
- [ ] Are the resource estimates reasonable?
- [ ] Are the dependencies clear?
**Evaluation Criteria**:
- ✅ Implementable: Can start implementation right away
- ⚠️ Improvement recommended: Additional information would help
- ❌ Insufficient: Information needed for implementation is missing
### 5. Measurability
**Checklist**:
- [ ] Are the success criteria measurable?
- [ ] Do the performance requirements have concrete numbers?
- [ ] Are the testing methods clear?
- [ ] Are the acceptance criteria defined?
**Evaluation Criteria**:
- ✅ Measurable: Clear metrics exist
- ⚠️ Improvement recommended: Some criteria are ambiguous
- ❌ Unclear: The measurement method is unknown
## Review Process
### Step 1: Read the Document
Read the specified document and identify its type:
- Product Requirements Document (PRD)
- Functional Design Document
- Architecture Design Document
- Repository Structure Document
- Development Guidelines
- Glossary
### Step 2: Check the Structure
Check whether the document's structure follows the appropriate template.
### Step 3: Evaluate the Content
Evaluate the document from the five perspectives above (completeness, clarity, consistency, implementability, measurability).
### Step 4: Create Improvement Suggestions
Provide concrete improvement suggestions in the following format:
```markdown
## Review Results: [document name]
### Overall Evaluation
| Perspective | Rating | Score |
|-----|------|--------|
| Completeness | [✅/⚠️/❌] | [1-5] |
| Clarity | [✅/⚠️/❌] | [1-5] |
| Consistency | [✅/⚠️/❌] | [1-5] |
| Implementability | [✅/⚠️/❌] | [1-5] |
| Measurability | [✅/⚠️/❌] | [1-5] |
**Overall Score**: [average score]/5
### Strengths
- [Specific strength 1]
- [Specific strength 2]
- [Specific strength 3]
### Areas That Need Improvement
#### [Required] Critical Issues
**Issue 1**: [description of the issue]
- **Location**: [section name or line number]
- **Reason**: [why it is a problem]
- **Suggested fix**: [specific way to improve]
- **Example**:
```
[before]
[after]
```
#### [Recommended] Improvements Recommended
**Issue 2**: [description of the issue]
- **Location**: [section name]
- **Reason**: [why it should be improved]
- **Suggested fix**: [specific way to improve]
#### [Suggestion] Further Improvements
**Suggestion 1**: [content of the suggestion]
- **Benefit**: [benefit of this improvement]
- **How to implement**: [how to improve]
### References
- [Related documents]
- [Best practices]
### Next Steps
1. [What to address with top priority]
2. [What to address next]
3. [What to address if there is time]
```
## Special Perspectives by Document Type
### Product Requirements Document (PRD)
Additional checklist:
- [ ] Is the target user clear?
- [ ] Is the problem being solved concrete?
- [ ] Are success metrics (KPIs) defined?
- [ ] Are priorities (P0/P1/P2) set?
- [ ] Is what is out of scope stated explicitly?
### Functional Design Document
Additional checklist:
- [ ] Is there a system configuration diagram?
- [ ] Is the data model defined?
- [ ] Are use cases shown with sequence diagrams?
- [ ] Is error handling considered?
- [ ] Is the API design concrete (where applicable)?
### Architecture Design Document
Additional checklist:
- [ ] Is there a rationale for the technology choices?
- [ ] Is the layered architecture clear?
- [ ] Are the performance requirements measurable?
- [ ] Are there security considerations?
- [ ] Is scalability considered?
### Repository Structure Document
Additional checklist:
- [ ] Is the directory structure visualized?
- [ ] Is the role of each directory explained?
- [ ] Are the naming conventions clear?
- [ ] Are the dependency rules defined?
- [ ] Is there a scaling strategy?
### Development Guidelines
Additional checklist:
- [ ] Do the coding standards include concrete examples?
- [ ] Are the Git workflow rules clear?
- [ ] Is the testing strategy defined?
- [ ] Is there a code review process?
- [ ] Are the environment setup steps documented?
### Glossary
Additional checklist:
- [ ] Are the terms classified appropriately?
- [ ] Does each term have a clear definition?
- [ ] Are concrete examples included?
- [ ] Are related terms linked?
- [ ] Is the index organized?
## Output Format
Always output the review results in the following structure:
1. **Overall Evaluation**: Scores and the evaluation matrix
2. **Strengths**: Positive feedback (at least 3)
3. **Areas That Need Improvement**: Organized by priority
- [Required] Critical issues
- [Recommended] Improvements recommended
- [Suggestion] Further improvements
4. **References**: Helpful resources
5. **Next Steps**: Concrete action items
## Review Attitude
- **Constructive**: Offer suggestions for improvement rather than criticism
- **Specific**: Instead of "hard to understand," state "where," "why," and "how to improve"
- **Balanced**: Point out not only the weaknesses but also the strengths
- **Practical**: Present improvement suggestions that can actually be carried out
- **Grounded**: Always provide a reason for each improvement suggestion

353
.claude/agents/implementation-validator.md Normal file
View File

@ -0,0 +1,353 @@
---
name: implementation-validator
description: A subagent that validates implementation code quality and confirms consistency with the spec
model: sonnet
---
# Implementation Validation Agent
You are a specialized validation agent that verifies the quality of implementation code and confirms its consistency with the spec.
## Purpose
Verify that the implemented code meets the following criteria:
1. Consistency with the spec (PRD, functional design document, architecture design document)
2. Code quality (coding standards, best practices)
3. Test coverage
4. Security
5. Performance
## Validation Perspectives
### 1. Spec Compliance
**Checklist**:
- [ ] Are the features defined in the PRD implemented?
- [ ] Does it match the data model in the functional design document?
- [ ] Does it follow the layer structure of the architecture design?
- [ ] Does it match the required API specification?
**Evaluation Criteria**:
- ✅ Compliant: Implemented as specified
- ⚠️ Some differences: Minor differences exist
- ❌ Inconsistent: Significant differences exist
### 2. Code Quality
**Checklist**:
- [ ] Does it follow the coding standards?
- [ ] Is the naming appropriate?
- [ ] Does each function have a single responsibility?
- [ ] Is there any duplicated code?
- [ ] Are there appropriate comments?
**Evaluation Criteria**:
- ✅ High quality: Fully compliant with the coding standards
- ⚠️ Improvement recommended: Some room for improvement
- ❌ Low quality: Significant problems exist
### 3. Test Coverage
**Checklist**:
- [ ] Are unit tests written?
- [ ] Is the coverage target met?
- [ ] Are edge cases tested?
- [ ] Are the tests named appropriately?
**Evaluation Criteria**:
- ✅ Sufficient: Coverage of 80% or more, covering the main cases
- ⚠️ Improvement recommended: Coverage of 60-80%
- ❌ Insufficient: Coverage below 60%
### 4. Security
**Checklist**:
- [ ] Is input validation implemented?
- [ ] Is any sensitive information hardcoded?
- [ ] Do error messages contain sensitive information?
- [ ] Are file permissions appropriate (where applicable)?
- [ ] Are authentication and authorization implemented appropriately (where applicable)?
**Evaluation Criteria**:
- ✅ Safe: Security measures are appropriate
- ⚠️ Caution needed: Some improvement is required
- ❌ Dangerous: A significant vulnerability exists
### 5. Performance
**Checklist**:
- [ ] Are the performance requirements met?
- [ ] Are appropriate data structures used?
- [ ] Are there any unnecessary computations?
- [ ] Are loops optimized?
- [ ] Is there any possibility of a memory leak?
**Evaluation Criteria**:
- ✅ Optimal: Meets the performance requirements
- ⚠️ Improvement recommended: Room for optimization
- ❌ Problematic: Performance requirements not met
## Validation Process
### Step 1: Understand the Spec
Read the relevant spec documents:
- `docs/product-requirements.md`
- `docs/functional-design.md`
- `docs/architecture.md`
- `docs/development-guidelines.md`
### Step 2: Analyze the Implementation Code
Read the implemented code and understand its structure:
- Review the directory structure
- Identify the main classes and functions
- Understand the data flow
### Step 3: Validate from Each Perspective
Validate from the five perspectives above (spec compliance, code quality, test coverage, security, performance).
### Step 4: Report the Validation Results
Report concrete validation results in the following format:
```markdown
## Implementation Validation Results
### Target
- **Implementation content**: [feature name or change description]
- **Target files**: [file list]
- **Related spec**: [spec document]
### Overall Evaluation
| Perspective | Rating | Score |
|-----|------|--------|
| Spec compliance | [✅/⚠️/❌] | [1-5] |
| Code quality | [✅/⚠️/❌] | [1-5] |
| Test coverage | [✅/⚠️/❌] | [1-5] |
| Security | [✅/⚠️/❌] | [1-5] |
| Performance | [✅/⚠️/❌] | [1-5] |
**Overall Score**: [average score]/5
### Good Implementation
- [Specific strength 1]
- [Specific strength 2]
- [Specific strength 3]
### Issues Detected
#### [Required] Critical Issues
**Issue 1**: [description of the issue]
- **File**: `[file path]:[line number]`
- **Problematic code**:
```typescript
[problematic code]
```
- **Reason**: [why it is a problem]
- **Suggested fix**:
```typescript
[corrected code]
```
#### [Recommended] Improvements Recommended
**Issue 2**: [description of the issue]
- **File**: `[file path]`
- **Reason**: [why it should be improved]
- **Suggested fix**: [specific way to improve]
#### [Suggestion] Further Improvements
**Suggestion 1**: [content of the suggestion]
- **Benefit**: [benefit of this improvement]
- **How to implement**: [how to improve]
### Test Results
**Tests run**:
- Unit tests: [pass/fail count]
- Integration tests: [pass/fail count]
- Coverage: [%]
**Areas with insufficient testing**:
- [Area 1]
- [Area 2]
### Differences from the Spec
**Difference 1**: [description of the difference]
- **Spec**: [what the spec states]
- **Implementation**: [the actual implementation]
- **Impact**: [the impact of this difference]
- **Recommendation**: [what should be done]
### Next Steps
1. [What to address with top priority]
2. [What to address next]
3. [What to address if there is time]
```
## Running Validation Tools
During validation, run the following tools:
### Lint Check
```bash
npm run lint
```
### Type Check
```bash
npm run typecheck
```
### Run Tests
```bash
npm test
npm run test:coverage
```
### Build Check
```bash
npm run build
```
## Detailed Code Quality Checks
### Naming Conventions
**Variables and functions**:
```typescript
// ✅ Good example
const userProfileData = fetchUserProfile();
function calculateTotalPrice(items: CartItem[]): number { }
// ❌ Bad example
const data = fetch();
function calc(arr: any[]): number { }
```
**Classes and interfaces**:
```typescript
// ✅ Good example
class TaskService { }
interface TaskRepository { }
// ❌ Bad example
class Manager { } // ambiguous
interface IData { } // meaningless
```
### Function Design
**Single responsibility principle**:
```typescript
// ✅ Good example: a single responsibility
function calculateTotal(items: CartItem[]): number { }
function formatPrice(amount: number): string { }
// ❌ Bad example: multiple responsibilities
function calculateAndFormatPrice(items: CartItem[]): string { }
```
**Function length**:
- Recommended: within 20 lines
- Acceptable: within 50 lines
- 100 lines or more: refactoring is recommended
### Error Handling
**Appropriate error handling**:
```typescript
// ✅ Good example
try {
const task = await taskService.create(data);
return task;
} catch (error) {
if (error instanceof ValidationError) {
logger.warn(`Validation error: ${error.message}`);
throw error;
}
throw new DatabaseError('Failed to create the task', error);
}
// ❌ Bad example: ignoring the error
try {
return await taskService.create(data);
} catch (error) {
return null; // error information is lost
}
```
## Security Checklist
### Input Validation
```typescript
// ✅ Good example
function validateEmail(email: string): void {
if (!email || typeof email !== 'string') {
throw new ValidationError('Email address is required', 'email', email);
}
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
throw new ValidationError('Email address format is invalid', 'email', email);
}
}
// ❌ Bad example: no validation
function validateEmail(email: string): void { }
```
### Sensitive Information Management
```typescript
// ✅ Good example
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('The API_KEY environment variable is not set');
}
// ❌ Bad example
const apiKey = 'sk-1234567890abcdef'; // hardcoding is forbidden
```
## Performance Checklist
### Choosing Data Structures
```typescript
// ✅ Good example: O(1) access
const taskMap = new Map(tasks.map(t => [t.id, t]));
const task = taskMap.get(taskId);
// ❌ Bad example: O(n) search
const task = tasks.find(t => t.id === taskId);
```
### Loop Optimization
```typescript
// ✅ Good example
for (const item of items) {
process(item);
}
// ❌ Bad example: computing length every iteration
for (let i = 0; i < items.length; i++) {
process(items[i]);
}
```
## Validation Attitude
- **Objective**: Evaluate based on facts
- **Specific**: Clearly indicate the problem locations
- **Constructive**: Always present improvement suggestions
- **Balanced**: Point out the strengths as well
- **Practical**: Provide fixes that can actually be carried out

131
.claude/commands/add-feature.md Normal file
View File

@ -0,0 +1,131 @@
---
description: Implement a new feature following existing patterns, fully autonomously without stopping
---
# Adding a New Feature (Fully Autonomous Execution Mode)
**Important:** This workflow is designed to run fully automatically from start to finish without user intervention. After completing each step, immediately move on to the next step. Do not ask the user for confirmation mid-thought or interrupt the work.
**Argument:** feature name (e.g. `/add-feature User profile editing`)
---
## Step 1: Preparation and Context Setup
1. Establish the current task context:
- Feature name: `[the feature name given as an argument]`
- Date: `[get the current date in YYYYMMDD format]`
- Steering directory path: `.steering/[date]-[feature name]/`
2. Create the steering directory above.
3. Create the following three empty files:
- `[steering directory path]/requirements.md`
- `[steering directory path]/design.md`
- `[steering directory path]/tasklist.md`
## Step 2: Understand the Project
1. Read `CLAUDE.md` to grasp the overall picture of the project.
2. Review the persistent documents in the `docs/` directory to understand the relevant design philosophy and architecture.
## Step 3: Investigate Existing Patterns
1. Use the Grep tool to search the source code (`src/`) for keywords related to the feature name.
```bash
Grep('[keyword related to the feature]', 'src/')
```
2. Analyze the search results to identify existing implementation patterns, naming conventions, and how components are used.
## Step 4: Planning Phase (Automatic Generation of Steering Files)
1. Run `Skill('steering')` in **planning mode** to generate the contents of the three files created in Step 1 (`requirements.md`, `design.md`, `tasklist.md`).
2. **Once this step completes successfully, never stop; immediately proceed to Step 5.**
## Step 5: Implementation Loop (Fully Working Through tasklist.md)
**This step is a loop that repeats automatically until all tasks in `tasklist.md` are `[x]`.**
**Once this step completes successfully, never stop; immediately proceed to Step 6.**
**Loop start:**
1. Read the task list:
- Read the `[steering directory path]/tasklist.md` file.
2. Check progress:
- Check whether any incomplete tasks (`[ ]`) exist in the file.
- **If no incomplete tasks exist:** consider this implementation loop complete and immediately proceed to **Step 6**.
- **If incomplete tasks exist:** proceed to the next step (3. Execute the task).
3. Execute the task:
- Identify one **incomplete task at the top** of `tasklist.md`.
- Carry out the implementation work needed to complete that task.
- Use `Skill('steering')` in **implementation mode**.
- Always follow the coding standards in `Skill('development-guidelines')`.
4. Update the task list:
- Once the executed task is complete, use the `Edit` tool to update `tasklist.md`, changing the task from `[ ]` to `[x]`.
5. Continue the loop:
- **Return to the top of Step 5 (1. Read the task list) and repeat the process.**
---
### * Exception-Handling Rules Within the Implementation Loop *
If any of the following situations occur while the implementation loop is running, handle them autonomously according to these rules and continue the loop.
- **Rule A: When a task is too large**
- **Handling:** Break the current task into multiple smaller subtasks. Use the `Edit` tool to delete the original task and insert the new subtasks (with `[ ]`) in its place. Then continue the loop.
- **Rule B: When a task becomes unnecessary for technical reasons**
- **Condition:** Apply only when there is a clear technical reason, such as a change in implementation approach, architecture, or dependencies.
- **Handling:** Use the `Edit` tool to update the task in the format `[x] ~~task name~~ (Reason: [briefly describe the specific technical reason])`. Then continue the loop.
- **❌ Strictly Forbidden Actions:**
- Intentionally skipping an incomplete task for reasons such as "do it later" or "make it a separate task."
- Leaving incomplete tasks unaddressed and ending the loop without reason.
- Asking the user to make a decision.
---
## Step 6: Implementation Validation (Launch a Subagent)
1. Do a final check that all tasks in `tasklist.md` are complete.
2. Use the `Task` tool to launch the `implementation-validator` subagent to validate quality.
- `subagent_type`: "implementation-validator"
- `description`: "Implementation quality validation"
- `prompt`: "Please validate the quality of all the changes related to the `[feature name]` implemented this time. The target files are `[list of paths of the implemented files]`. Focus on coding standards, error handling, testability, and consistency with existing patterns."
**Once this step completes successfully, never stop; immediately proceed to Step 7.**
## Step 7: Run Automated Tests
1. Run the following commands in order and confirm that all tests pass.
```bash
Bash('npm test')
Bash('npm run lint')
Bash('npm run typecheck')
```
2. If any command produces an error, analyze the problem, generate and apply a fix, and then run this step again.
**Once this step completes successfully, never stop; immediately proceed to Step 8.**
## Step 8: Retrospective and Document Updates
1. Run `Skill('steering')` in **retrospective mode** and record handover notes in `tasklist.md`.
- Implementation completion date
- Differences between plan and actual
- Lessons learned
- Improvement suggestions for next time
2. Determine whether this change affects the project's fundamental design or architecture.
3. If there is an impact, use the `Edit` tool to update the relevant persistent documents in `docs/`.
## Completion Criteria
This workflow completes automatically once all of the following conditions are met.
- Step 5: All tasks in `tasklist.md` are complete (`[x]` or skipped for a valid reason).
- Step 6: The `implementation-validator` subagent's validation passes.
- Step 7: The `test`, `lint`, and `typecheck` commands all succeed without errors.
- Step 8: Handover notes are recorded in `tasklist.md`.
Until these completion criteria are met, continue to think autonomously, solve problems, and carry on the work.

63
.claude/commands/review-docs.md Normal file
View File

@ -0,0 +1,63 @@
---
description: Run a detailed document review using a subagent
---
# Document Review
Argument: document path (e.g. `/review-docs docs/product-requirements.md`)
## How to Run
```bash
claude
> /review-docs docs/product-requirements.md
```
## Procedure
### Step 1: Verify the Document Exists
Check whether the specified document exists.
### Step 2: Launch the doc-reviewer Subagent
Launch the doc-reviewer subagent to run the review:
Use the Task tool to launch the doc-reviewer subagent:
- subagent_type: "doc-reviewer"
- description: "Document detailed review"
- prompt: "Please review [document path] in detail.\n\nEvaluate it from the following perspectives:\n1. Completeness: Are all required items included?\n2. Specificity: Are there any ambiguous expressions?\n3. Consistency: Is it consistent with other documents?\n4. Measurability: Are success metrics measurable? (for a PRD)\n\nPlease produce a review report."
### Step 3: Summarize the Review Results
Extract the key points from the review report produced by the subagent and report them to the user.
## Output Format
```markdown
# Document Review Results
## Document: [file name]
### Key Improvements
1. [Improvement 1] (Priority: High/Medium/Low)
2. [Improvement 2] (Priority: High/Medium/Low)
3. [Improvement 3] (Priority: High/Medium/Low)
### Overall Rating
[1-5]/5
### Next Actions
- [Recommended action 1]
- [Recommended action 2]
For the full report, refer to the subagent's output.
```
## Notes
- The review involves detailed analysis and may take a few minutes.
- The subagent runs in an independent context, so it does not consume the main agent's context.

110
.claude/commands/setup-project.md Normal file
View File

@ -0,0 +1,110 @@
---
description: "Initial setup: interactively create the six persistent documents"
---
# Initial Project Setup
This command interactively creates the project's six persistent documents.
## How to Run
```bash
claude
> /setup-project
```
## Pre-Run Check
Check the files in the `docs/ideas/` directory.
```bash
# Check
ls docs/ideas/
# If files exist
✅ Found docs/ideas/initial-requirements.md
The PRD will be created based on its contents
# If no files exist
⚠️ No files found in docs/ideas/
The PRD will be created interactively
```
## Procedure
### Step 0: Read the Inputs
1. Read all markdown files in `docs/ideas/`
2. Understand their contents and use them as reference for creating the PRD
### Step 1: Create the Product Requirements Document
1. Load the **prd-writing skill**
2. Create `docs/product-requirements.md` based on the contents of `docs/ideas/`
3. Flesh out the ideas raised during brainstorming:
- Detailed user stories
- Acceptance criteria
- Non-functional requirements
- Success metrics
4. Ask the user for confirmation and **wait until approved**
**The subsequent steps are based on the Product Requirements Document, so they are created automatically**
### Step 2: Create the Functional Design Document
1. Load the **functional-design skill**
1. Read `docs/product-requirements.md`
3. Create `docs/functional-design.md` following the skill's template and guide
### Step 3: Create the Architecture Design Document
1. Load the **architecture-design skill**
2. Read the existing documents
3. Create `docs/architecture.md` following the skill's template and guide
### Step 4: Create the Repository Structure Document
1. Load the **repository-structure skill**
2. Read the existing documents
3. Create `docs/repository-structure.md` following the skill's template
### Step 5: Create the Development Guidelines
1. Load the **development-guidelines skill**
2. Read the existing documents
3. Create `docs/development-guidelines.md` following the skill's template
### Step 6: Create the Glossary
1. Load the **glossary-creation skill**
2. Read the existing documents
3. Create `docs/glossary.md` following the skill's template
## Completion Criteria
- All six persistent documents have been created
Completion message:
```
"Initial setup is complete!
Documents created:
✅ docs/product-requirements.md
✅ docs/functional-design.md
✅ docs/architecture.md
✅ docs/repository-structure.md
✅ docs/development-guidelines.md
✅ docs/glossary.md
You are now ready to start development.
How to use going forward:
- Editing documents: just ask in normal conversation
Examples: 'Add a new feature to the PRD', 'Review architecture.md'
- Adding features: run /add-feature [feature name]
Example: /add-feature User authentication
- Document review: run /review-docs [path]
Example: /review-docs docs/product-requirements.md
"
```

15
.claude/settings.json Normal file
View File

@ -0,0 +1,15 @@
{
"permissions": {
"allow": [
"Skill(prd-writing)",
"Skill(functional-design)",
"Skill(architecture-design)",
"Skill(repository-structure)",
"Skill(development-guidelines)",
"Skill(glossary-creation)"
],
"deny": [],
"ask": []
},
"hooks": {}
}

51
.claude/skills/architecture-design/SKILL.md Normal file
View File

@ -0,0 +1,51 @@
---
name: architecture-design
description: A detailed guide and template for creating architecture design documents. Use only when designing architecture.
allowed-tools: Read, Write
---
# Architecture Design Skill
This skill is a detailed guide for creating high-quality architecture design documents.
## Prerequisites
Before starting architecture design, check the following:
### Required Documents
1. `docs/product-requirements.md` (PRD)
2. `docs/functional-design.md` (functional design document)
Architecture design defines the system structure and technology stack
needed to technically realize the PRD's requirements and functional design.
## Priority of Existing Documents
**Important**: If an existing architecture design document is present at `docs/architecture.md`,
follow this priority order:
1. **The existing architecture design document (`docs/architecture.md`)** - highest priority
- It documents project-specific technology choices and design
- It takes precedence over this skill's guide
2. **This skill's guide** - reference material
- General-purpose templates and examples
- Use when there is no existing design document, or as a supplement
**When creating new**: Refer to this skill's template and guide
**When updating**: Update while preserving the structure and content of the existing design document
## Output Destination
Save the architecture design document you create to:
```
docs/architecture.md
```
## Referencing the Template
When creating an architecture design document, use the template while referring to the following guide:
- Guide: ./guide.md
- Template: ./template.md

186
.claude/skills/architecture-design/guide.md Normal file
View File

@ -0,0 +1,186 @@
# Architecture Design Guide
## Basic Principles
### 1. State the Rationale for Technology Choices
**Bad example**:
```
- Node.js
- TypeScript
```
**Good example**:
```
- Node.js v24.11.0 (LTS)
- Long-term support guaranteed until April 2026, ensuring stable operation in production
- Excellent at asynchronous I/O, delivering high performance as an API server
- Rich npm ecosystem makes the required libraries easy to obtain
- TypeScript 5.x
- Static typing catches bugs at compile time, improving maintainability
- Powerful IDE autocompletion boosts development efficiency
- Shared type definitions in team development ensure code readability and quality
- npm 11.x
- Bundled with Node.js v24.11.0, so no separate installation is required
- Supports monorepo configurations via the workspaces feature
- Enables strict dependency management through package-lock.json
```
### 2. The Principle of Layer Separation
Clarify the responsibilities of each layer and keep dependencies unidirectional:
```
UI → Service → Data (OK)
UI ← Service (NG)
UI → Data (NG)
```
### 3. Measurable Requirements
Describe all performance requirements in a measurable form.
## Designing a Layered Architecture
### Responsibilities of Each Layer
**UI layer**:
```typescript
// Responsibility: Accepting and validating user input
class CLI {
// OK: Call the service layer
async addTask(title: string) {
const task = await this.taskService.create({ title });
console.log(`Created: ${task.id}`);
}
// NG: Call the data layer directly
async addTask(title: string) {
const task = await this.repository.save({ title }); // ❌
}
}
```
**Service layer**:
```typescript
// Responsibility: Implementing business logic
class TaskService {
// Business logic: Automatic priority estimation
async create(data: CreateTaskData): Promise<Task> {
const task = {
...data,
estimatedPriority: this.estimatePriority(data),
};
return this.repository.save(task);
}
}
```
**Data layer**:
```typescript
// Responsibility: Data persistence
class TaskRepository {
async save(task: Task): Promise<void> {
await this.storage.write(task);
}
}
```
## Setting Performance Requirements
### Concrete Numeric Targets
```
Command execution time: within 100ms (on an average PC environment)
└─ Measurement method: measure from CLI startup to result display with console.time
└─ Measurement environment: CPU equivalent to Core i5, 8GB RAM, SSD
Task list display: within 1 second for up to 1000 items
└─ Measurement method: measure with 1000 dummy data items
└─ Acceptable range: 100ms for 100 items, 1 second for 1000 items, 10 seconds for 10000 items
```
## Security Design
### The Three Principles of Data Protection
1. **Principle of least privilege**
```bash
# File permissions
chmod 600 ~/.devtask/tasks.json # Read/write for owner only
```
2. **Input validation**
```typescript
function validateTitle(title: string): void {
if (!title || title.length === 0) {
throw new ValidationError('Title is required');
}
if (title.length > 200) {
throw new ValidationError('Title must be 200 characters or fewer');
}
}
```
3. **Managing sensitive information**
```bash
# Manage via environment variables
export DEVTASK_API_KEY="xxxxx" # Do not hardcode in the code
```
## Scalability Design
### Handling Data Growth
**Expected data volume**: [e.g., 10,000 tasks]
**Countermeasures**:
- Data pagination
- Archiving old data
- Index optimization
```typescript
// Example archive feature: move old tasks to a separate file
class ArchiveService {
async archiveCompletedTasks(olderThan: Date): Promise<void> {
const oldTasks = await this.repository.findCompleted(olderThan);
await this.archiveStorage.save(oldTasks);
await this.repository.deleteMany(oldTasks.map(t => t.id));
}
}
```
## Dependency Management
### Version Management Policy
```json
{
"dependencies": {
"commander": "^11.0.0", // Minor version upgrades are automatic
"chalk": "5.3.0" // Pin when there is a risk of breaking changes
},
"devDependencies": {
"typescript": "~5.3.0", // Patch versions only are automatic
"eslint": "^9.0.0"
}
}
```
**Policy**:
- Pin stable versions (allow up to minor versions with ^)
- Pin completely when there is a risk of breaking changes
- For devDependencies, automate patch versions only (~)
## Checklist
- [ ] Every technology choice has a stated rationale
- [ ] The layered architecture is clearly defined
- [ ] Performance requirements are measurable
- [ ] Security considerations are documented
- [ ] Scalability is taken into account
- [ ] A backup strategy is defined
- [ ] The dependency management policy is clear
- [ ] A test strategy is defined

153
.claude/skills/architecture-design/template.md Normal file
View File

@ -0,0 +1,153 @@
# Architecture Design Document
## Technology Stack
### Languages and Runtimes
| Technology | Version |
|------|-----------|
| Node.js | v24.11.0 |
| TypeScript | 5.x |
| npm | 11.x |
### Frameworks and Libraries
| Technology | Version | Purpose | Rationale |
|------|-----------|------|----------|
| [name] | [version] | [purpose] | [rationale] |
| [name] | [version] | [purpose] | [rationale] |
### Development Tools
| Technology | Version | Purpose | Rationale |
|------|-----------|------|----------|
| [name] | [version] | [purpose] | [rationale] |
| [name] | [version] | [purpose] | [rationale] |
## Architecture Pattern
### Layered Architecture
```
┌─────────────────────────┐
│ UI layer │ ← Accepts and displays user input
├─────────────────────────┤
│ Service layer │ ← Business logic
├─────────────────────────┤
│ Data layer │ ← Data persistence
└─────────────────────────┘
```
#### UI Layer
- **Responsibility**: Accepting user input, validation, displaying results
- **Permitted operations**: Calling the service layer
- **Prohibited operations**: Direct access to the data layer
#### Service Layer
- **Responsibility**: Implementing business logic, data transformation
- **Permitted operations**: Calling the data layer
- **Prohibited operations**: Depending on the UI layer
#### Data Layer
- **Responsibility**: Data persistence and retrieval
- **Permitted operations**: Access to the file system and databases
- **Prohibited operations**: Implementing business logic
## Data Persistence Strategy
### Storage Method
| Data type | Storage | Format | Rationale |
|-----------|----------|-------------|------|
| [data 1] | [method] | [format] | [rationale] |
| [data 2] | [method] | [format] | [rationale] |
### Backup Strategy
- **Frequency**: [e.g., every hour]
- **Destination**: [e.g., `.backup/` directory]
- **Generation management**: [e.g., retain the latest 5 generations]
- **Restoration method**: [procedure]
## Performance Requirements
### Response Time
| Operation | Target time | Measurement environment |
|------|---------|---------|
| [operation 1] | [time] | [environment] |
| [operation 2] | [time] | [environment] |
### Resource Usage
| Resource | Limit | Rationale |
|---------|------|------|
| Memory | [MB] | [rationale] |
| CPU | [%] | [rationale] |
| Disk | [MB] | [rationale] |
## Security Architecture
### Data Protection
- **Encryption**: [target data and method]
- **Access control**: [file permissions, etc.]
- **Sensitive information management**: [environment variables, config files, etc.]
### Input Validation
- **Validation**: [validation items]
- **Sanitization**: [target and method]
- **Error handling**: [secure error display]
## Scalability Design
### Handling Data Growth
- **Expected data volume**: [e.g., 10,000 tasks]
- **Performance degradation countermeasures**: [method]
- **Archive strategy**: [handling of old data]
### Extensibility
- **Plugin system**: [presence/absence and design]
- **Configuration customization**: [scope of what is possible]
- **API extensibility**: [methods for future extension]
## Test Strategy
### Unit Tests
- **Framework**: [framework name]
- **Target**: [description of test target]
- **Coverage target**: [%]
### Integration Tests
- **Method**: [test method]
- **Target**: [description of test target]
### E2E Tests
- **Tool**: [tool name]
- **Scenarios**: [test scenarios]
## Technical Constraints
### Environment Requirements
- **OS**: [supported OS]
- **Minimum memory**: [MB]
- **Required disk space**: [MB]
- **Required external dependencies**: [list]
### Performance Constraints
- [constraint 1]
- [constraint 2]
### Security Constraints
- [constraint 1]
- [constraint 2]
## Dependency Management
| Library | Purpose | Version management policy |
|-----------|------|-------------------|
| [name] | [purpose] | [pinned/range] |
| [name] | [purpose] | [pinned/range] |

108
.claude/skills/development-guidelines/SKILL.md Normal file
View File

@ -0,0 +1,108 @@
---
name: development-guidelines
description: A comprehensive guide and template for establishing a unified development process and coding conventions across the team. Use when creating development guidelines and when implementing code.
allowed-tools: Read, Write, Edit
---
# Development Guidelines Skill
Covers the two elements needed for team development:
1. Coding conventions for implementation (implementation-guide.md)
2. Standardization of the development process (process-guide.md)
## Prerequisites
Before starting to create development guidelines, check the following:
### Recommended Documents
1. `docs/architecture.md` (architecture design document) - confirm the technology stack
2. `docs/repository-structure.md` (repository structure) - confirm the directory structure
The development guidelines define concrete coding conventions and a development process
based on the project's technology stack and directory structure.
## Priority of Existing Documents
**Important**: If existing development guidelines are present at `docs/development-guidelines.md`,
follow this priority order:
1. **The existing development guidelines (`docs/development-guidelines.md`)** - highest priority
- They document project-specific conventions and processes
- They take precedence over this skill's guide
2. **This skill's guide** - reference material
- ./guides/implementation.md: general-purpose coding conventions
- ./guides/process.md: general-purpose development process
- Use when there are no existing guidelines, or as a supplement
**When creating new**: Refer to this skill's guides and template
**When updating**: Update while preserving the structure and content of the existing guidelines
## Output Destination
Save the development guidelines you create to:
```
docs/development-guidelines.md
```
## Quick Reference
### When Implementing Code
Rules and conventions for code implementation: ./guides/implementation.md
Contents:
- TypeScript/JavaScript conventions
- Type definitions and naming conventions
- Function design and error handling
- Comment conventions
- Security and performance
- Test code implementation
- Refactoring techniques
### When Referencing/Defining the Development Process
Git workflow, test strategy, code review: ./guides/process.md
Contents:
- Basic principles (the importance of concrete examples, explaining rationale)
- Git workflow rules (Git Flow branching strategy)
- Commit messages and the PR process
- Test strategy (pyramid and coverage)
- The code review process
- Quality automation
### Template
When creating development guidelines: ./template.md
## Guide by Use Case
### When Developing New Code
1. Confirm naming conventions and coding standards in ./guides/implementation.md
2. Confirm the branching strategy and PR handling in ./guides/process.md
3. Write tests first (TDD)
### During Code Review
- Refer to "The Code Review Process" in ./guides/process.md
- Check for convention violations against ./guides/implementation.md
### When Designing Tests
- "Test Strategy" in ./guides/process.md (pyramid, coverage)
- "Test Code" in ./guides/implementation.md (implementation patterns)
### When Preparing a Release
- "Git Workflow Rules" in ./guides/process.md (policy for merging into main)
- Confirm that commit messages follow Conventional Commits
## Checklist
- [ ] Coding conventions are defined with concrete examples
- [ ] Naming conventions are clear (per language and project-specific)
- [ ] An error handling policy is defined
- [ ] A branching strategy is decided (Git Flow recommended)
- [ ] Commit message conventions are clear
- [ ] A PR template is prepared
- [ ] Test types and coverage targets are set
- [ ] A code review process is defined
- [ ] A CI/CD pipeline is established

627
.claude/skills/development-guidelines/guides/implementation.md Normal file
View File

@ -0,0 +1,627 @@
# Implementation Guide
## TypeScript/JavaScript Conventions
### Type Definitions
**Using built-in types**:
```typescript
// ✅ Good: Use built-in types
function processItems(items: string[]): Record<string, number> {
return items.reduce((acc, item) => {
acc[item] = (acc[item] || 0) + 1;
return acc;
}, {} as Record<string, number>);
}
// ❌ Bad: Importing from the typing module
import { List, Dict } from 'typing';
function processItems(items: List[str]): Dict[str, int] { }
```
**Type annotation principles**:
```typescript
// ✅ Good: Explicit type annotations
function calculateTotal(prices: number[]): number {
return prices.reduce((sum, price) => sum + price, 0);
}
// ❌ Bad: Over-relying on type inference
function calculateTotal(prices) { // becomes the any type
return prices.reduce((sum, price) => sum + price, 0);
}
```
**Interface vs. type alias**:
```typescript
// Interface: extensible object types
interface Task {
id: string;
title: string;
completed: boolean;
}
// Extension
interface ExtendedTask extends Task {
priority: string;
}
// Type alias: union types, primitive types, etc.
type TaskStatus = 'todo' | 'in_progress' | 'completed';
type TaskId = string;
type Nullable<T> = T | null;
```
### Naming Conventions
**Variables and functions**:
```typescript
// Variables: camelCase, nouns
const userName = 'John';
const taskList = [];
const isCompleted = true;
// Functions: camelCase, start with a verb
function fetchUserData() { }
function validateEmail(email: string) { }
function calculateTotalPrice(items: Item[]) { }
// Boolean: start with is, has, should, or can
const isValid = true;
const hasPermission = false;
const shouldRetry = true;
const canDelete = false;
```
**Classes and interfaces**:
```typescript
// Classes: PascalCase, nouns
class TaskManager { }
class UserAuthenticationService { }
// Interfaces: PascalCase
interface TaskRepository { }
interface UserProfile { }
// Type aliases: PascalCase
type TaskStatus = 'todo' | 'in_progress' | 'completed';
```
**Constants**:
```typescript
// UPPER_SNAKE_CASE
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';
const DEFAULT_TIMEOUT = 5000;
// For configuration objects
const CONFIG = {
maxRetryCount: 3,
apiBaseUrl: 'https://api.example.com',
defaultTimeout: 5000,
} as const;
```
**File names**:
```typescript
// Class files: PascalCase
// TaskService.ts
// UserRepository.ts
// Functions and utilities: camelCase
// formatDate.ts
// validateEmail.ts
// Components (React, etc.): PascalCase
// TaskList.tsx
// UserProfile.tsx
// Constants: kebab-case or UPPER_SNAKE_CASE
// api-endpoints.ts
// ERROR_MESSAGES.ts
```
### Function Design
**Single responsibility principle**:
```typescript
// ✅ Good: A single responsibility
function calculateTotalPrice(items: CartItem[]): number {
return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
function formatPrice(amount: number): string {
return `¥${amount.toLocaleString()}`;
}
// ❌ Bad: Multiple responsibilities
function calculateAndFormatPrice(items: CartItem[]): string {
const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
return `¥${total.toLocaleString()}`;
}
```
**Function length**:
- Target: within 20 lines
- Recommended: within 50 lines
- 100 lines or more: consider refactoring
**Number of parameters**:
```typescript
// ✅ Good: Group into an object
interface CreateTaskOptions {
title: string;
description?: string;
priority?: 'high' | 'medium' | 'low';
dueDate?: Date;
}
function createTask(options: CreateTaskOptions): Task {
// implementation
}
// ❌ Bad: Too many parameters
function createTask(
title: string,
description: string,
priority: string,
dueDate: Date,
tags: string[],
assignee: string
): Task {
// implementation
}
```
### Error Handling
**Custom error classes**:
```typescript
// Defining error classes
class ValidationError extends Error {
constructor(
message: string,
public field: string,
public value: unknown
) {
super(message);
this.name = 'ValidationError';
}
}
class NotFoundError extends Error {
constructor(
public resource: string,
public id: string
) {
super(`${resource} not found: ${id}`);
this.name = 'NotFoundError';
}
}
class DatabaseError extends Error {
constructor(message: string, public cause?: Error) {
super(message);
this.name = 'DatabaseError';
this.cause = cause;
}
}
```
**Error handling patterns**:
```typescript
// ✅ Good: Proper error handling
async function getTask(id: string): Promise<Task> {
try {
const task = await repository.findById(id);
if (!task) {
throw new NotFoundError('Task', id);
}
return task;
} catch (error) {
if (error instanceof NotFoundError) {
// Expected error: handle appropriately
logger.warn(`Task not found: ${id}`);
throw error;
}
// Unexpected error: wrap and propagate upward
throw new DatabaseError('Failed to retrieve the task', error as Error);
}
}
// ❌ Bad: Ignoring the error
async function getTask(id: string): Promise<Task | null> {
try {
return await repository.findById(id);
} catch (error) {
return null; // error information is lost
}
}
```
**Error messages**:
```typescript
// ✅ Good: Specific and suggests a solution
throw new ValidationError(
'Title must be 1-200 characters. Current length: 250',
'title',
title
);
// ❌ Bad: Vague and unhelpful
throw new Error('Invalid input');
```
### Asynchronous Processing
**Using async/await**:
```typescript
// ✅ Good: async/await
async function fetchUserTasks(userId: string): Promise<Task[]> {
try {
const user = await userRepository.findById(userId);
const tasks = await taskRepository.findByUserId(user.id);
return tasks;
} catch (error) {
logger.error('Failed to retrieve tasks', error);
throw error;
}
}
// ❌ Bad: Promise chains
function fetchUserTasks(userId: string): Promise<Task[]> {
return userRepository.findById(userId)
.then(user => taskRepository.findByUserId(user.id))
.then(tasks => tasks)
.catch(error => {
logger.error('Failed to retrieve tasks', error);
throw error;
});
}
```
**Parallel processing**:
```typescript
// ✅ Good: Run in parallel with Promise.all
async function fetchMultipleUsers(ids: string[]): Promise<User[]> {
const promises = ids.map(id => userRepository.findById(id));
return Promise.all(promises);
}
// ❌ Bad: Sequential execution
async function fetchMultipleUsers(ids: string[]): Promise<User[]> {
const users: User[] = [];
for (const id of ids) {
const user = await userRepository.findById(id); // slow
users.push(user);
}
return users;
}
```
## Comment Conventions
### Documentation Comments
**TSDoc format**:
```typescript
/**
* Creates a task
*
* @param data - Data for the task to create
* @returns The created task
* @throws {ValidationError} When the data is invalid
* @throws {DatabaseError} When a database error occurs
*
* @example
* ```typescript
* const task = await createTask({
* title: 'New task',
* priority: 'high'
* });
* ```
*/
async function createTask(data: CreateTaskData): Promise<Task> {
// implementation
}
```
### Inline Comments
**Good comments**:
```typescript
// ✅ Explain the reason
// Invalidate the cache to fetch the latest data
cache.clear();
// ✅ Explain complex logic
// Compute the maximum subarray sum using Kadane's algorithm
// Time complexity: O(n)
let maxSoFar = arr[0];
let maxEndingHere = arr[0];
// ✅ Make use of TODO and FIXME
// TODO: Implement caching (Issue #123)
// FIXME: Performance degrades with large datasets (Issue #456)
// HACK: Temporary workaround, needs refactoring later
```
**Bad comments**:
```typescript
// ❌ Merely restating the code
// Increment i by 1
i++;
// ❌ Stale information
// This code was added in 2020 (unnecessary information)
// ❌ Commented-out code
// const oldImplementation = () => { ... }; // should be deleted
```
## Security
### Input Validation
```typescript
// ✅ Good: Strict validation
function validateEmail(email: string): void {
if (!email || typeof email !== 'string') {
throw new ValidationError('Email address is required', 'email', email);
}
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(email)) {
throw new ValidationError('Email address format is invalid', 'email', email);
}
if (email.length > 254) {
throw new ValidationError('Email address is too long', 'email', email);
}
}
// ❌ Bad: No validation
function validateEmail(email: string): void {
// no validation
}
```
### Managing Sensitive Information
```typescript
// ✅ Good: Load from environment variables
import { config } from './config';
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('The API_KEY environment variable is not set');
}
// ❌ Bad: Hardcoding
const apiKey = 'sk-1234567890abcdef'; // never do this!
```
## Performance
### Choosing Data Structures
```typescript
// ✅ Good: O(1) access with a Map
const userMap = new Map(users.map(u => [u.id, u]));
const user = userMap.get(userId); // O(1)
// ❌ Bad: O(n) search with an array
const user = users.find(u => u.id === userId); // O(n)
```
### Loop Optimization
```typescript
// ✅ Good: Move unnecessary computation outside the loop
const length = items.length;
for (let i = 0; i < length; i++) {
process(items[i]);
}
// ❌ Bad: Recomputing length every iteration
for (let i = 0; i < items.length; i++) {
process(items[i]);
}
// ✅ Better: Use for...of
for (const item of items) {
process(item);
}
```
### Memoization
```typescript
// Caching computation results
const cache = new Map<string, Result>();
function expensiveCalculation(input: string): Result {
if (cache.has(input)) {
return cache.get(input)!;
}
const result = /* heavy computation */;
cache.set(input, result);
return result;
}
```
## Test Code
### Test Structure (Given-When-Then)
```typescript
describe('TaskService', () => {
describe('create', () => {
it('can create a task with valid data', async () => {
// Given: setup
const service = new TaskService(mockRepository);
const taskData = {
title: 'Test task',
description: 'Description for testing',
};
// When: execute
const result = await service.create(taskData);
// Then: verify
expect(result).toBeDefined();
expect(result.id).toBeDefined();
expect(result.title).toBe('Test task');
expect(result.description).toBe('Description for testing');
expect(result.createdAt).toBeInstanceOf(Date);
});
it('throws a ValidationError when the title is empty', async () => {
// Given: setup
const service = new TaskService(mockRepository);
const invalidData = { title: '' };
// When/Then: execute and verify
await expect(
service.create(invalidData)
).rejects.toThrow(ValidationError);
});
});
});
```
### Creating Mocks
```typescript
// ✅ Good: Mocks based on an interface
const mockRepository: TaskRepository = {
save: jest.fn(),
findById: jest.fn(),
findAll: jest.fn(),
delete: jest.fn(),
};
// Configure behavior per test
beforeEach(() => {
mockRepository.findById = jest.fn((id) => {
if (id === 'existing-id') {
return Promise.resolve(mockTask);
}
return Promise.resolve(null);
});
});
```
## Refactoring
### Eliminating Magic Numbers
```typescript
// ✅ Good: Define constants
const MAX_RETRY_COUNT = 3;
const RETRY_DELAY_MS = 1000;
for (let i = 0; i < MAX_RETRY_COUNT; i++) {
try {
return await fetchData();
} catch (error) {
if (i < MAX_RETRY_COUNT - 1) {
await sleep(RETRY_DELAY_MS);
}
}
}
// ❌ Bad: Magic numbers
for (let i = 0; i < 3; i++) {
try {
return await fetchData();
} catch (error) {
if (i < 2) {
await sleep(1000);
}
}
}
```
### Extracting Functions
```typescript
// ✅ Good: Extract functions
function processOrder(order: Order): void {
validateOrder(order);
calculateTotal(order);
applyDiscounts(order);
saveOrder(order);
}
function validateOrder(order: Order): void {
if (!order.items || order.items.length === 0) {
throw new ValidationError('No items selected', 'items', order.items);
}
}
function calculateTotal(order: Order): void {
order.total = order.items.reduce(
(sum, item) => sum + item.price * item.quantity,
0
);
}
// ❌ Bad: A long function
function processOrder(order: Order): void {
if (!order.items || order.items.length === 0) {
throw new ValidationError('No items selected', 'items', order.items);
}
order.total = order.items.reduce(
(sum, item) => sum + item.price * item.quantity,
0
);
if (order.coupon) {
order.total -= order.total * order.coupon.discountRate;
}
repository.save(order);
}
```
## Checklist
Confirm before completing implementation:
### Code Quality
- [ ] Naming is clear and consistent
- [ ] Functions have a single responsibility
- [ ] No magic numbers
- [ ] Type annotations are written appropriately
- [ ] Error handling is implemented
### Security
- [ ] Input validation is implemented
- [ ] No sensitive information is hardcoded
- [ ] SQL injection countermeasures are in place
### Performance
- [ ] Appropriate data structures are used
- [ ] Unnecessary computation is avoided
- [ ] Loops are optimized
### Testing
- [ ] Unit tests are written
- [ ] Tests pass
- [ ] Edge cases are covered
### Documentation
- [ ] Functions and classes have TSDoc comments
- [ ] Complex logic has comments
- [ ] TODOs and FIXMEs are noted (where applicable)
### Tooling
- [ ] No lint errors
- [ ] Type checking passes
- [ ] Formatting is consistent

421
.claude/skills/development-guidelines/guides/process.md Normal file
View File

@ -0,0 +1,421 @@
# Process Guide
## Basic Principles
### 1. Include Plenty of Concrete Examples
Present concrete code examples, not just abstract rules.
**Bad example**:
```
Make variable names easy to understand
```
**Good example**:
```typescript
// ✅ Good: The role is clear
const userAuthentication = new UserAuthenticationService();
const taskRepository = new TaskRepository();
// ❌ Bad: Ambiguous
const auth = new Service();
const repo = new Repository();
```
### 2. Explain the Reasoning
Make clear "why we do it this way."
**Example**:
```
## Don't Ignore Errors
Reason: Ignoring errors makes it difficult to identify the cause of a problem.
Handle expected errors appropriately, and propagate unexpected errors upward
so they can be recorded in the logs.
```
### 3. Set Measurable Criteria
Avoid vague expressions and provide concrete numbers.
**Bad example**:
```
Keep code coverage high
```
**Good example**:
```
Code coverage targets:
- Unit tests: 80% or higher
- Integration tests: 60% or higher
- E2E tests: 100% of the main flows
```
## Git Operation Rules
### Branching Strategy (Adopting Git Flow)
**What is Git Flow**:
A branching model proposed by Vincent Driessen that systematically manages feature development, releases, and hotfixes. With clearly divided roles, it enables parallel work and stable releases in team development.
**Branch structure**:
```
main (production environment)
└── develop (development/integration environment)
├── feature/* (new feature development)
├── fix/* (bug fixes)
└── release/* (release preparation) *as needed
```
**Operation rules**:
- **main**: Holds only stable code already released to production. Versioned with tags
- **develop**: Integrates the latest development code for the next release. Automated tests run in CI
- **feature/\*, fix/\***: Branch from develop, and merge into develop via a PR after the work is complete
- **No direct commits**: Require PR review on all branches to ensure code quality
- **Merge policy**: Recommend squash merge for feature→develop, and a merge commit for develop→main
**Benefits of Git Flow**:
- Branch roles are clear, making parallel development by multiple people easier
- The production environment (main) is always kept clean
- During emergencies, hotfix branches enable rapid response (introduce as needed)
### Commit Message Conventions
**Conventional Commits is recommended**:
```
<type>(<scope>): <subject>
<body>
<footer>
```
**List of types**:
```
feat: New feature (minor version up)
fix: Bug fix (patch version up)
docs: Documentation
style: Formatting (no effect on code behavior)
refactor: Refactoring
perf: Performance improvement
test: Adding or fixing tests
build: Build system
ci: CI/CD configuration
chore: Other (dependency updates, etc.)
BREAKING CHANGE: Breaking change (major version up)
```
**Example of a good commit message**:
```
feat(task): Add priority-setting feature
Users can now set a priority (high/medium/low) on tasks.
Implementation details:
- Added a priority field to the Task model
- Added a --priority option to the CLI
- Implemented sorting by priority
Breaking changes:
- The structure of the Task type has changed
- Existing task data requires migration
Closes #123
BREAKING CHANGE: Added a required priority field to the Task type
```
### Pull Request Template
**An effective PR template**:
```markdown
## Type of Change
- [ ] New feature (feat)
- [ ] Bug fix (fix)
- [ ] Refactoring (refactor)
- [ ] Documentation (docs)
- [ ] Other (chore)
## Changes
### What was changed
[Brief description]
### Why it was changed
[Background and reasoning]
### How it was changed
- [Change 1]
- [Change 2]
## Testing
### Tests performed
- [ ] Added unit tests
- [ ] Added integration tests
- [ ] Performed manual testing
### Test results
[Description of the test results]
## Related Issues
Closes #[number]
Refs #[number]
## Review Points
[Points you especially want reviewers to look at]
```
## Test Strategy
### Test Pyramid
```
/\
/E2E\ Few (slow, high cost)
/------\
/ Integ. \ Medium
/----------\
/ Unit \ Many (fast, low cost)
/--------------\
```
**Target ratio**:
- Unit tests: 70%
- Integration tests: 20%
- E2E tests: 10%
### How to Write Tests
**Given-When-Then pattern**:
```typescript
describe('TaskService', () => {
describe('task creation', () => {
it('can create a task with valid data', async () => {
// Given: setup
const service = new TaskService(mockRepository);
const validData = { title: 'Test' };
// When: execute
const result = await service.create(validData);
// Then: verify
expect(result.id).toBeDefined();
expect(result.title).toBe('Test');
});
it('throws a ValidationError when the title is empty', async () => {
// Given: setup
const service = new TaskService(mockRepository);
const invalidData = { title: '' };
// When/Then: execute and verify
await expect(
service.create(invalidData)
).rejects.toThrow(ValidationError);
});
});
});
```
### Coverage Targets
**Measurable targets**:
```json
// jest.config.js
{
"coverageThreshold": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
},
"./src/services/": {
"branches": 90,
"functions": 90,
"lines": 90,
"statements": 90
}
}
}
```
**Reasoning**:
- Critical business logic (services/) requires high coverage
- The UI layer is acceptable at a lower level
- Don't aim for 100% (balance cost and benefit)
## Code Review Process
### Purpose of Review
1. **Quality assurance**: Early detection of bugs
2. **Knowledge sharing**: Understanding the codebase across the whole team
3. **Learning opportunity**: Sharing best practices
### Points for Effective Reviews
**For reviewers**:
1. **Constructive feedback**
```markdown
## ❌ Bad example
This code is no good.
## ✅ Good example
This implementation results in O(n²) time complexity.
Using a Map can improve it to O(n):
```typescript
const taskMap = new Map(tasks.map(t => [t.id, t]));
const result = ids.map(id => taskMap.get(id));
```
```
2. **State the priority explicitly**
```markdown
[Required] Security: A password is being output to the logs
[Recommended] Performance: Avoid DB calls inside a loop
[Suggestion] Readability: Could this function name be made clearer?
[Question] Could you explain the intent of this processing?
```
3. **Positive feedback too**
```markdown
✨ This implementation is easy to understand!
👍 Edge cases are thoroughly considered
💡 This pattern looks reusable elsewhere
```
**For reviewees**:
1. **Perform a self-review**
- Review your own code before creating the PR
- Add comments where explanation is needed
2. **Aim for small PRs**
- 1 PR = 1 feature
- Number of changed files: 10 or fewer recommended
- Number of changed lines: 300 or fewer recommended
3. **Explain carefully**
- Why you chose this implementation
- Alternatives you considered
- Points you especially want reviewed
### Review Time Guidelines
- Small PR (100 lines or fewer): 15 minutes
- Medium PR (100-300 lines): 30 minutes
- Large PR (300 lines or more): 1 hour or more
**Principle**: Avoid large PRs; split them up
## Promoting Automation (Where Applicable)
### Automating Quality Checks
**Automation items and the tools adopted**:
1. **Lint checks**
- **ESLint 9.x** + **@typescript-eslint**
- Unifies coding conventions with a TypeScript-specific rule set
- Automatically detects potential bugs and deprecated patterns
- Configuration file: `eslint.config.js` (Flat Config format)
2. **Code formatting**
- **Prettier 3.x**
- Automatically formats code style, reducing debate during review
- Used together with ESLint, avoiding conflicts via `eslint-config-prettier`
- Configuration file: `.prettierrc`
3. **Type checking**
- **TypeScript Compiler (tsc) 5.x**
- Checks only type errors with `tsc --noEmit`
- Verifies type safety independently of the build
- Configuration file: `tsconfig.json`
4. **Running tests**
- **Vitest 2.x**
- Fast startup and execution based on Vite
- Natively supports TypeScript/ESM and works with zero configuration
- Coverage measurement (@vitest/coverage-v8) is built in as standard
- Modern development experience with HMR support
5. **Build verification**
- **TypeScript Compiler (tsc)**
- Guarantees a type-checked build with the standard compiler
- Simple configuration with no additional tools required
- Centralizes output settings in `tsconfig.json`
**Implementation methods**:
**1. CI/CD (GitHub Actions)**
```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '24'
- run: npm ci
- run: npm run lint
- run: npm run typecheck
- run: npm run test
- run: npm run build
```
**2. Pre-commit hooks (Husky 9.x + lint-staged)**
```json
// package.json
{
"scripts": {
"prepare": "husky",
"lint": "eslint .",
"format": "prettier --write .",
"typecheck": "tsc --noEmit",
"test": "vitest run",
"build": "tsc"
},
"lint-staged": {
"*.{ts,tsx}": [
"eslint --fix",
"prettier --write"
]
}
}
```
```bash
# .husky/pre-commit
npm run lint-staged
npm run typecheck
```
**Effects of adoption**:
- Automated checks run before committing, preventing defective code from being introduced
- CI runs automatically when a PR is created, ensuring quality before merging
- Early detection reduces fix costs by up to 80% (compared to when bugs are found after production)
**Why this configuration was chosen**:
- A standard and modern configuration in the TypeScript ecosystem as of 2025
- High compatibility between tools, with few configuration conflicts
- An excellent balance between development experience and execution speed
## Checklist
- [ ] A branching strategy is decided
- [ ] Commit message conventions are clear
- [ ] A PR template is prepared
- [ ] Test types and coverage targets are set
- [ ] A code review process is defined
- [ ] A CI/CD pipeline is built

410
.claude/skills/development-guidelines/template.md Normal file
View File

@ -0,0 +1,410 @@
# Development Guidelines
## Coding Conventions
### Naming Conventions
#### Variables and Functions
**TypeScript/JavaScript**:
```typescript
// ✅ Good example
const userProfileData = fetchUserProfile();
function calculateTotalPrice(items: CartItem[]): number { }
// ❌ Bad example
const data = fetch();
function calc(arr: any[]): number { }
```
**Principles**:
- Variables: camelCase, noun or noun phrase
- Functions: camelCase, start with a verb
- Constants: UPPER_SNAKE_CASE
- Boolean: start with `is`, `has`, or `should`
#### Classes and Interfaces
```typescript
// Class: PascalCase, noun
class TaskManager { }
class UserAuthenticationService { }
// Interface: PascalCase, with or without the I prefix
interface ITaskRepository { }
interface Task { }
// Type alias: PascalCase
type TaskStatus = 'todo' | 'in_progress' | 'completed';
```
### Code Formatting
**Indentation**: [2 spaces / 4 spaces / tabs]
**Line length**: maximum [80/100/120] characters
**Example**:
```typescript
// [language] code formatting example
[code example]
```
### Comment Conventions
**Function and class documentation**:
```typescript
/**
* Calculate the total number of tasks
*
* @param tasks - Array of tasks to count
* @param filter - Filter condition (optional)
* @returns Total number of tasks
* @throws {ValidationError} When the task array is invalid
*/
function countTasks(
tasks: Task[],
filter?: TaskFilter
): number {
// Implementation
}
```
**Inline comments**:
```typescript
// ✅ Good example: explain why you do it
// Invalidate the cache to fetch the latest data
cache.clear();
// ❌ Bad example: what you are doing (obvious from the code)
// Clear the cache
cache.clear();
```
### Error Handling
**Principles**:
- Expected errors: define an appropriate error class
- Unexpected errors: propagate upward
- Do not ignore errors
**Example**:
```typescript
// Error class definition
class ValidationError extends Error {
constructor(
message: string,
public field: string,
public value: unknown
) {
super(message);
this.name = 'ValidationError';
}
}
// Error handling
try {
const task = await taskService.create(data);
} catch (error) {
if (error instanceof ValidationError) {
console.error(`Validation error [${error.field}]: ${error.message}`);
// Provide feedback to the user
} else {
console.error('Unexpected error:', error);
throw error; // Propagate upward
}
}
```
## Git Workflow Rules
### Branching Strategy
**Branch types**:
- `main`: ready to deploy to production
- `develop`: latest development state
- `feature/[feature-name]`: new feature development
- `fix/[fix-description]`: bug fixes
- `refactor/[target]`: refactoring
**Flow**:
```
main
└─ develop
├─ feature/task-management
├─ feature/user-auth
└─ fix/task-validation
```
### Commit Message Conventions
**Format**:
```
<type>(<scope>): <subject>
<body>
<footer>
```
**Type**:
- `feat`: new feature
- `fix`: bug fix
- `docs`: documentation
- `style`: code formatting
- `refactor`: refactoring
- `test`: adding or fixing tests
- `chore`: build, supporting tools, etc.
**Example**:
```
feat(task): add a task priority setting feature
Allowed users to set a priority (high/medium/low) on tasks.
- Added a priority field to the Task model
- Added a --priority option to the CLI
- Implemented sorting by priority
Closes #123
```
### Pull Request Process
**Checks before creating**:
- [ ] All tests pass
- [ ] No lint errors
- [ ] Type checking passes
- [ ] Conflicts are resolved
**PR template**:
```markdown
## Overview
[A brief description of the changes]
## Reason for Change
[Why this change is necessary]
## Changes
- [change 1]
- [change 2]
## Testing
- [ ] Unit tests added
- [ ] Manual testing performed
## Screenshots (if applicable)
[image]
## Related Issue
Closes #[issue number]
```
**Review process**:
1. Self-review
2. Run automated tests
3. Assign reviewers
4. Address review feedback
5. Merge after approval
## Test Strategy
### Test Types
#### Unit Tests
**Target**: individual functions and classes
**Coverage target**: [80/90/100]%
**Example**:
```typescript
describe('TaskService', () => {
describe('create', () => {
it('can create a task with valid data', async () => {
const service = new TaskService(mockRepository);
const task = await service.create({
title: 'Test task',
description: 'Description',
});
expect(task.id).toBeDefined();
expect(task.title).toBe('Test task');
});
it('throws ValidationError when the title is empty', async () => {
const service = new TaskService(mockRepository);
await expect(
service.create({ title: '' })
).rejects.toThrow(ValidationError);
});
});
});
```
#### Integration Tests
**Target**: coordination of multiple components
**Example**:
```typescript
describe('Task CRUD', () => {
it('can create, read, update, and delete a task', async () => {
// Create
const created = await taskService.create({ title: 'Test' });
// Read
const found = await taskService.findById(created.id);
expect(found?.title).toBe('Test');
// Update
await taskService.update(created.id, { title: 'Updated' });
const updated = await taskService.findById(created.id);
expect(updated?.title).toBe('Updated');
// Delete
await taskService.delete(created.id);
const deleted = await taskService.findById(created.id);
expect(deleted).toBeNull();
});
});
```
#### E2E Tests
**Target**: the entire user scenario
**Example**:
```typescript
describe('Task management flow', () => {
it('a user can add and complete a task', async () => {
// Add a task
await cli.run(['add', 'New task']);
expect(output).toContain('Task added');
// Display the task list
await cli.run(['list']);
expect(output).toContain('New task');
// Complete the task
await cli.run(['complete', '1']);
expect(output).toContain('Task completed');
});
});
```
### Test Naming Conventions
**Pattern**: `[target]_[condition]_[expectedResult]`
**Example**:
```typescript
// ✅ Good example
it('create_emptyTitle_throwsValidationError', () => { });
it('findById_existingId_returnsTask', () => { });
it('delete_nonExistentId_throwsNotFoundError', () => { });
// ❌ Bad example
it('test1', () => { });
it('works', () => { });
it('should work correctly', () => { });
```
### Using Mocks and Stubs
**Principles**:
- Mock external dependencies (API, DB, file system)
- Use the real implementation for business logic
**Example**:
```typescript
// Mock the repository
const mockRepository: ITaskRepository = {
save: jest.fn(),
findById: jest.fn(),
findAll: jest.fn(),
delete: jest.fn(),
};
// The service uses the real implementation
const service = new TaskService(mockRepository);
```
## Code Review Criteria
### Review Points
**Functionality**:
- [ ] Does it meet the requirements?
- [ ] Are edge cases considered?
- [ ] Is error handling appropriate?
**Readability**:
- [ ] Is the naming clear?
- [ ] Are the comments appropriate?
- [ ] Is complex logic explained?
**Maintainability**:
- [ ] Is there any duplicate code?
- [ ] Are responsibilities clearly separated?
- [ ] Is the impact scope of changes limited?
**Performance**:
- [ ] Are there any unnecessary computations?
- [ ] Is there any possibility of a memory leak?
- [ ] Are database queries optimized?
**Security**:
- [ ] Is input validation appropriate?
- [ ] Is any sensitive information hardcoded?
- [ ] Are permission checks implemented?
### How to Write Review Comments
**Constructive feedback**:
```markdown
## ✅ Good example
With this implementation, performance may degrade as the number of tasks grows.
How about considering a search that uses an index instead?
## ❌ Bad example
This way of writing it is not good.
```
**Indicate priority**:
- `[required]`: must be fixed
- `[recommended]`: fix recommended
- `[suggestion]`: please consider
- `[question]`: a question for understanding
## Development Environment Setup
### Required Tools
| Tool | Version | Installation method |
|--------|-----------|-----------------|
| [tool 1] | [version] | [command] |
| [tool 2] | [version] | [command] |
### Setup Procedure
```bash
# 1. Clone the repository
git clone [URL]
cd [project-name]
# 2. Install dependencies
[install command]
# 3. Set environment variables
cp .env.example .env
# Edit the .env file
# 4. Start the development server
[start command]
```
### Recommended Development Tools (if applicable)
- [tool 1]: [description]
- [tool 2]: [description]

53
.claude/skills/functional-design/SKILL.md Normal file
View File

@ -0,0 +1,53 @@
---
name: functional-design
description: Detailed guide and template for creating a functional design document. Use only when creating a functional design document.
allowed-tools: Read, Write
---
# Functional Design Document Creation Skill
This skill is a detailed guide for creating high-quality functional design documents.
## Prerequisites
Before starting to create a functional design document, confirm the following:
### docs/product-requirements.md has been created
**Required**: The PRD must exist at the following location:
**File path**: `docs/product-requirements.md`
The functional design document details how to technically realize the requirements defined in the PRD.
## Priority of Existing Documents
**Important**: If an existing functional design document is present at `docs/functional-design.md`,
follow the priority order below:
1. **Existing functional design document (`docs/functional-design.md`)** - Highest priority
- Contains project-specific design
- Takes precedence over this skill's guide
2. **This skill's guide** - Reference material
- Generic templates and examples
- Use when no existing design document exists, or as a supplement
**When creating new**: Refer to this skill's template and guide
**When updating**: Update while maintaining the structure and content of the existing design document
## Output Destination
Save the created functional design document to the following location:
```
docs/functional-design.md
```
## Template Reference
When creating a functional design document, use the following template: ./template.md
## Detailed Guide
For a more detailed creation guide, refer to the following file: ./guide.md

470
.claude/skills/functional-design/guide.md Normal file
View File

@ -0,0 +1,470 @@
# Functional Design Document Creation Guide
This guide provides practical guidance for creating a functional design document based on a Product Requirements Document (PRD).
## Purpose of the Functional Design Document
The functional design document translates the "what to build" defined in the PRD into "how to realize it".
**Main Content**:
- System architecture diagram
- Data model
- Component design
- Algorithm design (if applicable)
- UI design
- Error handling
## Basic Creation Flow
### Step 1: Review the PRD
Before creating the functional design document, always review the PRD.
```
Example prompt for having Claude Code create a functional design document from the PRD:
Create a functional design document based on the content of the PRD.
In particular, focus on the priority P0 (MVP) features.
```
### Step 2: Create the System Architecture Diagram
#### Using Mermaid Notation
Write the system architecture diagram using Mermaid notation.
**Example of a basic 3-tier architecture**:
```mermaid
graph TB
User[User]
CLI[CLI Layer]
Service[Service Layer]
Data[Data Layer]
User --> CLI
CLI --> Service
Service --> Data
```
**A more detailed example**:
```mermaid
graph TB
User[User]
CLI[CLI Interface]
Commander[Commander.js]
TaskManager[TaskManager]
PriorityEstimator[PriorityEstimator]
FileStorage[FileStorage]
JSON[(tasks.json)]
User --> CLI
CLI --> Commander
Commander --> TaskManager
TaskManager --> PriorityEstimator
TaskManager --> FileStorage
FileStorage --> JSON
```
### Step 3: Define the Data Model
#### Define Clearly with TypeScript Type Definitions
Define the data model using TypeScript interfaces.
**Example of a basic Task type**:
```typescript
interface Task {
id: string; // UUID v4
title: string; // 1-200 characters
description?: string; // Optional, Markdown format
status: TaskStatus; // 'todo' | 'in_progress' | 'completed'
priority: TaskPriority; // 'high' | 'medium' | 'low'
estimatedPriority?: TaskPriority; // Automatically estimated priority
dueDate?: Date; // Due date
createdAt: Date; // Creation timestamp
updatedAt: Date; // Update timestamp
statusHistory?: StatusChange[]; // Status change history
}
type TaskStatus = 'todo' | 'in_progress' | 'completed';
type TaskPriority = 'high' | 'medium' | 'low';
interface StatusChange {
from: TaskStatus;
to: TaskStatus;
changedAt: Date;
}
```
**Key Points**:
- Add a comment explaining each field
- Clearly note constraints (character count, format, etc.)
- Add `?` to optional fields
- Improve readability with type aliases
#### Creating an ER Diagram
When there are multiple entities, show the relationships with an ER diagram.
```mermaid
erDiagram
TASK ||--o{ SUBTASK : has
TASK ||--o{ TAG : has
USER ||--o{ TASK : creates
TASK {
string id PK
string title
string status
datetime createdAt
}
SUBTASK {
string id PK
string taskId FK
string title
}
```
### Step 4: Component Design
Clarify the responsibilities of each layer.
#### CLI Layer
**Responsibility**: Accept user input, validation, display results
```typescript
// CommandLineInterface
class CLI {
// Accept user input
parseArguments(): Command;
// Display results
displayResult(result: Result): void;
// Display errors
displayError(error: Error): void;
}
```
#### Service Layer
**Responsibility**: Implement business logic
```typescript
// TaskManager
class TaskManager {
// Create a task
createTask(data: CreateTaskData): Task;
// Get the task list
listTasks(filter?: FilterOptions): Task[];
// Update a task
updateTask(id: string, data: UpdateTaskData): Task;
// Delete a task
deleteTask(id: string): void;
}
```
#### Data Layer
**Responsibility**: Data persistence and retrieval
```typescript
// FileStorage
class FileStorage {
// Save data
save(data: any): void;
// Load data
load(): any;
// Check whether the file exists
exists(): boolean;
}
```
### Step 5: Algorithm Design (if applicable)
Design complex logic (e.g., automatic priority estimation) in detail.
#### Example of an Automatic Priority Estimation Algorithm
**Purpose**: Automatically estimate priority from a task's due date, creation timestamp, and status
**Calculation Logic**:
##### Step 1: Deadline Score Calculation (0-100 points)
```
- Overdue: 100 points (highest)
- 0-3 days until due: 90 points
- 4-7 days until due: 70 points
- 8-14 days until due: 50 points
- 14 or more days until due: 30 points
- No due date set: 20 points
```
**Formula**:
```typescript
function calculateDeadlineScore(dueDate?: Date): number {
if (!dueDate) return 20;
const now = new Date();
const daysRemaining = Math.floor((dueDate.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
if (daysRemaining < 0) return 100; // Overdue
if (daysRemaining <= 3) return 90;
if (daysRemaining <= 7) return 70;
if (daysRemaining <= 14) return 50;
return 30;
}
```
##### Step 2: Elapsed Time Score Calculation (0-100 points)
```
- 30 or more days since creation: 100 points (highest)
- 21-30 days since creation: 80 points
- 14-21 days since creation: 60 points
- 7-14 days since creation: 40 points
- Less than 7 days since creation: 20 points
```
**Formula**:
```typescript
function calculateAgeScore(createdAt: Date): number {
const now = new Date();
const daysOld = Math.floor((now.getTime() - createdAt.getTime()) / (1000 * 60 * 60 * 24));
if (daysOld >= 30) return 100;
if (daysOld >= 21) return 80;
if (daysOld >= 14) return 60;
if (daysOld >= 7) return 40;
return 20;
}
```
##### Step 3: Status Score Calculation (0-100 points)
```
- In progress (in_progress): 100 points (highest priority)
- Not started (todo): 50 points
- Completed (completed): 0 points
```
**Formula**:
```typescript
function calculateStatusScore(status: TaskStatus): number {
if (status === 'in_progress') return 100;
if (status === 'todo') return 50;
return 0; // completed
}
```
##### Step 4: Total Score Calculation
**Weighted Average**:
```
Total Score = (Deadline Score × 50%) + (Elapsed Time Score × 20%) + (Status Score × 30%)
```
**Formula**:
```typescript
function calculateTotalScore(task: Task): number {
const deadlineScore = calculateDeadlineScore(task.dueDate);
const ageScore = calculateAgeScore(task.createdAt);
const statusScore = calculateStatusScore(task.status);
return (deadlineScore * 0.5) + (ageScore * 0.2) + (statusScore * 0.3);
}
```
##### Step 5: Priority Classification
**Classification by Threshold**:
```
- 70 points or more: high (high priority)
- 40-70 points: medium (medium priority)
- Less than 40 points: low (low priority)
```
**Formula**:
```typescript
function estimatePriority(task: Task): TaskPriority {
const score = calculateTotalScore(task);
if (score >= 70) return 'high';
if (score >= 40) return 'medium';
return 'low';
}
```
**Complete Implementation Example**:
```typescript
class PriorityEstimator {
estimate(task: Task): TaskPriority {
const deadlineScore = this.calculateDeadlineScore(task.dueDate);
const ageScore = this.calculateAgeScore(task.createdAt);
const statusScore = this.calculateStatusScore(task.status);
const totalScore = (deadlineScore * 0.5) + (ageScore * 0.2) + (statusScore * 0.3);
if (totalScore >= 70) return 'high';
if (totalScore >= 40) return 'medium';
return 'low';
}
private calculateDeadlineScore(dueDate?: Date): number {
if (!dueDate) return 20;
const now = new Date();
const daysRemaining = Math.floor((dueDate.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
if (daysRemaining < 0) return 100;
if (daysRemaining <= 3) return 90;
if (daysRemaining <= 7) return 70;
if (daysRemaining <= 14) return 50;
return 30;
}
private calculateAgeScore(createdAt: Date): number {
const now = new Date();
const daysOld = Math.floor((now.getTime() - createdAt.getTime()) / (1000 * 60 * 60 * 24));
if (daysOld >= 30) return 100;
if (daysOld >= 21) return 80;
if (daysOld >= 14) return 60;
if (daysOld >= 7) return 40;
return 20;
}
private calculateStatusScore(status: TaskStatus): number {
if (status === 'in_progress') return 100;
if (status === 'todo') return 50;
return 0;
}
}
```
### Step 6: Use Case Diagram
Express the main use cases with sequence diagrams.
**Task Addition Flow**:
```mermaid
sequenceDiagram
participant User
participant CLI
participant TaskManager
participant PriorityEstimator
participant FileStorage
User->>CLI: devtask add "task"
CLI->>CLI: Validate input
CLI->>TaskManager: createTask(data)
TaskManager->>TaskManager: Create task object
TaskManager->>PriorityEstimator: estimate(task)
PriorityEstimator-->>TaskManager: Estimated priority
TaskManager->>FileStorage: save(task)
FileStorage-->>TaskManager: Success
TaskManager-->>CLI: Created task
CLI-->>User: "Task created (ID: xxx)"
```
### Step 7: UI Design (if applicable)
For CLI tools, define table display and color coding.
#### Table Display
```
┌──────────┬──────────────────┬────────────┬──────────┬───────────────┐
│ ID │ Title │ Status │ Priority │ Due Date │
├──────────┼──────────────────┼────────────┼──────────┼───────────────┤
│ 7a5c6ff0 │ Buy milk on the │ Not started│ High │ 2025-11-05 │
│ │ way home. │ │ │ (1 day left) │
└──────────┴──────────────────┴────────────┴──────────┴───────────────┘
```
#### Color Coding
**Status Color Coding**:
- Completed (completed): green
- In progress (in_progress): yellow
- Not started (todo): white
**Priority Color Coding**:
- High (high): red
- Medium (medium): yellow
- Low (low): blue
### Step 8: File Structure (if applicable)
Define the data storage format.
**Example: Data storage for a CLI tool**:
```
.devtask/
├── tasks.json # Task data
└── config.json # Configuration data
```
**Example of tasks.json**:
```json
{
"tasks": [
{
"id": "7a5c6ff0-5f55-474e-baf7-ea13624d73a4",
"title": "Buy milk on the way home",
"description": "",
"status": "todo",
"priority": "high",
"estimatedPriority": "medium",
"dueDate": "2025-11-05T00:00:00.000Z",
"createdAt": "2025-11-04T10:00:00.000Z",
"updatedAt": "2025-11-04T10:00:00.000Z"
}
]
}
```
### Step 9: Error Handling
Define the types of errors and how to handle them.
| Error Category | Handling | Display to User |
|-----------|------|-----------------|
| Input validation error | Abort processing, display error message | "Please enter a title of 1-200 characters" |
| File read error | Continue with empty initial data | "Data file not found. Creating a new one" |
| Task not found | Abort processing, display error message | "Task not found (ID: xxx)" |
## Reviewing the Functional Design Document
### Review Perspectives
Request a review from Claude Code:
```
Please evaluate this functional design document. Check it from the following perspectives:
1. Does it satisfy the requirements of the PRD?
2. Is the data model concrete?
3. Are the responsibilities of the components clear?
4. Is the algorithm detailed to an implementable level?
5. Is error handling comprehensive?
```
### Implementing Improvements
Make improvements based on Claude Code's feedback.
## Summary
Keys to successfully creating a functional design document:
1. **Consistency with the PRD**: Accurately reflect the requirements defined in the PRD
2. **Leverage Mermaid notation**: Express things visually with diagrams
3. **TypeScript type definitions**: Make the data model clear
4. **Detailed algorithm design**: Be concrete about complex logic
5. **Layer separation**: Clarify the responsibilities of each component
6. **Implementable level**: A level of detail that lets developers implement without confusion

262
.claude/skills/functional-design/template.md Normal file
View File

@ -0,0 +1,262 @@
# Functional Design Document
## System Architecture Diagram
```mermaid
graph TB
User[User]
CLI[CLI Layer]
Service[Service Layer]
Data[Data Layer]
User --> CLI
CLI --> Service
Service --> Data
```
## Technology Stack
| Category | Technology | Selection Rationale |
|------|------|----------|
| Language | [Language name] | [Rationale] |
| Framework | [Name] | [Rationale] |
| Database | [Name] | [Rationale] |
| Tools | [Name] | [Rationale] |
## Data Model Definition
### Entity: [Entity Name]
```typescript
interface [EntityName] {
id: string; // UUID
[field1]: [type]; // [description]
[field2]: [type]; // [description]
createdAt: Date; // Creation timestamp
updatedAt: Date; // Update timestamp
}
```
**Constraints**:
- [Constraint 1]
- [Constraint 2]
### ER Diagram
```mermaid
erDiagram
ENTITY1 ||--o{ ENTITY2 : has
ENTITY1 {
string id PK
string field1
datetime createdAt
}
ENTITY2 {
string id PK
string entity1Id FK
string field1
}
```
## Component Design
### [Component 1]
**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]
**Interface**:
```typescript
class [ComponentName] {
[method1]([params]): [return];
[method2]([params]): [return];
}
```
**Dependencies**:
- [Dependency 1]
- [Dependency 2]
## Use Case Diagram
### [Use Case 1]
```mermaid
sequenceDiagram
participant User
participant CLI
participant Service
participant Data
User->>CLI: [action1]
CLI->>Service: [action2]
Service->>Data: [action3]
Data-->>Service: [response]
Service-->>CLI: [response]
CLI-->>User: [result]
```
**Flow Description**:
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Screen Transition Diagram (if applicable)
```mermaid
stateDiagram-v2
[*] --> State1
State1 --> State2: [action]
State2 --> State3: [action]
State3 --> [*]
```
## API Design (if applicable)
### [Endpoint 1]
```
POST /api/[resource]
```
**Request**:
```json
{
"[field]": "[value]"
}
```
**Response**:
```json
{
"id": "uuid",
"[field]": "[value]"
}
```
**Error Responses**:
- 400 Bad Request: [Condition]
- 404 Not Found: [Condition]
- 500 Internal Server Error: [Condition]
## Algorithm Design (if applicable)
### [Algorithm Name]
**Purpose**: [Description]
**Calculation Logic**:
#### Step 1: [Step Name]
- [Detailed description]
- Formula: `[formula]`
- Score range: 0-100 points
#### Step 2: [Step Name]
- [Detailed description]
- Formula: `[formula]`
- Score range: 0-100 points
#### Step 3: Total Score Calculation
- Weighted average: `Total Score = (Step 1 × Weight 1) + (Step 2 × Weight 2)`
- Weight allocation:
- Step 1: [%]
- Step 2: [%]
#### Step 4: Classification
- [Classification 1]: Score >= [threshold]
- [Classification 2]: [threshold] <= Score < [threshold]
- [Classification 3]: Score < [threshold]
**Implementation Example**:
```typescript
function [algorithmName]([params]): [return] {
// Step 1
const score1 = [calculation];
// Step 2
const score2 = [calculation];
// Total score
const totalScore = (score1 * weight1) + (score2 * weight2);
// Classification
if (totalScore >= threshold1) return '[classification1]';
if (totalScore >= threshold2) return '[classification2]';
return '[classification3]';
}
```
## UI Design (if applicable)
### Table Display
**Display Items**:
| Item | Description | Format |
|------|------|-------------|
| [Item 1] | [Description] | [Format] |
| [Item 2] | [Description] | [Format] |
### Color Coding
**Color Usage**:
- [Color 1]: [Use] (e.g., green = completed)
- [Color 2]: [Use] (e.g., yellow = in progress)
- [Color 3]: [Use] (e.g., red = not started)
### Interactive Mode (if applicable)
**Operation Flow**:
1. [Operation 1]
2. [Operation 2]
3. [Operation 3]
## File Structure (if applicable)
**Data Storage Format**:
```
[directory]/
├── [file1].json # [description]
└── [file2].json # [description]
```
**File Content Example**:
```json
{
"[field]": "[value]"
}
```
## Performance Optimization
- [Optimization 1]: [Description]
- [Optimization 2]: [Description]
## Security Considerations
- [Consideration 1]: [Countermeasure]
- [Consideration 2]: [Countermeasure]
## Error Handling
### Error Classification
| Error Category | Handling | Display to User |
|-----------|------|-----------------|
| [Category 1] | [Handling details] | [Message] |
| [Category 2] | [Handling details] | [Message] |
## Testing Strategy
### Unit Tests
- [Target 1]
- [Target 2]
### Integration Tests
- [Scenario 1]
- [Scenario 2]
### E2E Tests
- [Scenario 1]
- [Scenario 2]

56
.claude/skills/glossary-creation/SKILL.md Normal file
View File

@ -0,0 +1,56 @@
---
name: glossary-creation
description: Detailed guide and template for creating a glossary. Use only when creating a glossary.
allowed-tools: Read, Write
---
# Glossary Creation Skill
This skill is a detailed guide for systematically defining project-specific terms and technical terms.
## Prerequisites
Before starting to create a glossary, confirm the following:
### Recommended Documents
1. **docs/product-requirements.md** (PRD)
2. **docs/functional-design.md** (Functional Design Document)
3. **docs/architecture.md** (Architecture Design Document)
4. **docs/repository-structure.md** (Repository Structure)
5. **docs/development-guidelines.md** (Development Guidelines)
The glossary defines the terms used across all documents in a unified way.
Extract terms from each document and organize them systematically.
## Priority of Existing Documents
**Important**: If an existing glossary is present at `docs/glossary.md`,
follow the priority order below:
1. **Existing glossary (`docs/glossary.md`)** - Highest priority
- Contains project-specific term definitions
- Takes precedence over this skill's guide
2. **This skill's guide** - Reference material
- Generic templates and examples
- Use when no existing glossary exists, or as a supplement
**When creating new**: Refer to this skill's template and guide
**When updating**: Update while maintaining the structure and content of the existing glossary
## Output Destination
Save the created glossary to the following location:
```
docs/glossary.md
```
## Template Reference
When creating a glossary, use the following template: ./template.md
## Detailed Guide
For a more detailed creation guide, refer to the following file: ./guide.md

509
.claude/skills/glossary-creation/guide.md Normal file
View File

@ -0,0 +1,509 @@
# Glossary Creation Guide
## Basic principles
### 1. Clear and consistent definitions
Term definitions should eliminate ambiguity so that everyone who reads them arrives at the same understanding.
**Bad example**:
```markdown
## Task
What the user should do
```
**Good example**:
```markdown
## Task (Task)
**Definition**: A unit of work that the user must complete. It has a title, description, due date,
and status (not started / in progress / completed).
**Related terms**: Subtask, Task group
**Usage examples**:
- "Add a task": Register a new task in the system
- "Complete a task": Change the task's status to completed
**Data model**: `src/types/Task.ts`
```
### 2. Include concrete examples
Show concrete usage examples, not just abstract definitions.
**Example**:
```markdown
## Priority (Priority)
**Definition**: A three-level indicator showing a task's importance and urgency
**Value definitions**:
- `high`: Urgent and important. Requires immediate response
- `medium`: Important but not urgent. Handle in a planned manner
- `low`: Low in both importance and urgency. Handle if there is time
**Decision criteria**:
- high: Due within 24 hours, or blocking other tasks
- medium: Due within one week
- low: Due more than one week out, or no due date
**Usage example**:
```typescript
const task: Task = {
title: 'Fix security vulnerability',
priority: 'high', // Requires urgent response
};
```
```
### 3. Link related terms
Make the relationships between terms clear.
**Example**:
```markdown
## Task (Task)
**Definition**: [Definition]
**Related terms**:
- [Subtask](#subtask): A task broken down into smaller parts
- [Task group](#task-group): Multiple tasks grouped together
- [Status](#task-status): The progress state of a task
**Parent-child relationship**:
- Parent: Task group
- Child: Subtask
```
## How to classify terms
### Defining domain terms
**Target**: Project-specific business concepts
**Items to define**:
```markdown
## [Term]
**Definition**: [A concise definition in 1-2 sentences]
**Description**: [Detailed explanation, background, constraints]
**Related terms**: [Other related terms]
**Usage examples**: [Specific usage scenarios]
**Data model**: [The relevant file path]
**English notation**: [English term] (when there is global expansion)
```
**Example**:
```markdown
## Steering File (Steering File)
**Definition**: A temporary document created for short-term task management
**Description**:
A steering file is placed in the `.steering/[YYYYMMDD]-[task-name]/` directory
and is deleted 1-2 weeks after the task is completed. It contains the task specification,
implementation notes, review records, and so on.
**Related terms**:
- [Persistent document](#persistent-document): A document stored for the long term
- [Task mode](#task-mode): The development mode that uses steering files
**Usage examples**:
- "Create a steering file for adding a feature"
- "After the task is completed, delete or archive the steering file"
**Directory structure**:
```
.steering/
└── 20250101-add-priority-feature/
├── requirements.md # The requirements for this task
├── design.md # The design of the changes
└── tasklist.md # The task list
```
**English notation**: Steering File
```
### Defining technical terms
**Target**: The technologies, frameworks, and tools in use
**Items to define**:
```markdown
## [Technology name]
**Definition**: [A concise description of the technology]
**Official site**: [URL]
**Use in this project**: [How it is used]
**Version**: [Version in use]
**Reason for selection**: [Why this technology was chosen]
**Alternative technologies**: [Other options that were considered]
**Related documents**: [Links to internal documents]
**Configuration file**: [Path to the configuration file]
```
**Example**:
```markdown
## TypeScript
**Definition**: A programming language that adds static typing to JavaScript
**Official site**: https://www.typescriptlang.org/
**Use in this project**:
All source code is written in TypeScript to ensure type safety.
**Version**: 5.3.x
**Reason for selection**:
- Improved maintainability in large-scale development
- Improved development efficiency through editor completion
- Error detection at compile time
**Alternative technologies**:
- JavaScript ESM: Cannot benefit from type checking
- Flow: Inferior to TypeScript in ecosystem maturity
**Related documents**:
- [Architecture Design Document](./architecture.md#technology-stack)
- [Development Guidelines](./development-guidelines.md#typescript-conventions)
**Configuration file**: `tsconfig.json`
```
### Defining abbreviations and acronyms
**Principles**:
- State the full name clearly
- On first appearance, write both the abbreviation and the full name
- Avoid project-specific abbreviations (use only common abbreviations)
**Example**:
```markdown
## CLI
**Full name**: Command Line Interface
**Meaning**: An interface operated from the command line
**Use in this project**:
Used as the main interface of the Devtask tool. Users operate tasks with commands like
`devtask add "task"`.
**Implementation**: `src/cli/` directory
**Alternative interface**: A GUI version is under consideration as a future extension
## TDD
**Full name**: Test-Driven Development
**Meaning**: A development method in which tests are written first and then the implementation follows
**Application in this project**:
TDD is adopted for all new feature development.
**Procedure**:
1. Write a test
2. Run the test → confirm it fails
3. Write the implementation
4. Run the test → confirm it succeeds
5. Refactor
**Reference**: [Development Guidelines](./development-guidelines.md#tdd)
```
### Defining architecture terms
**Target**: Concepts related to system design and patterns
**Items to define**:
```markdown
## [Concept]
**Definition**: [Explanation of the architecture concept]
**Application in this project**: [The specific implementation method]
**Advantages**: [Reasons for adoption]
**Disadvantages**: [Constraints and trade-offs]
**Related components**: [Related components]
**Diagram**: [Structure diagram]
**References**: [References or URLs]
```
**Example**:
```markdown
## Layered Architecture (Layered Architecture)
**Definition**: A design pattern that divides a system into multiple layers by role,
with a one-directional dependency from upper layers to lower layers
**Application in this project**:
A three-layer architecture is adopted:
```
UI layer (cli/)
↓
Service layer (services/)
↓
Data layer (repositories/)
```
**Responsibilities of each layer**:
- UI layer: Accepting and displaying user input
- Service layer: Implementing business logic
- Data layer: Persisting and retrieving data
**Advantages**:
- Improved maintainability through separation of concerns
- Easy to test (each layer can be tested independently)
- A limited scope of impact from changes
**Disadvantages**:
- May be over-engineering for small-scale projects
- Overhead in data conversion between layers
**Dependency rules**:
- ✅ UI layer → Service layer
- ✅ Service layer → Data layer
- ❌ Data layer → Service layer
- ❌ Data layer → UI layer
**Implementation location**: Reflected in the structure of the `src/` directory
**References**:
- [Architecture Design Document](./architecture.md)
- [Repository Structure Definition Document](./repository-structure.md)
```
## Defining state transitions
**Target**: The statuses or states of an entity
**Definition method**:
1. **Enumerate in table form**
2. **State the transition conditions clearly**
3. **Visualize with a Mermaid diagram**
**Example**:
```markdown
## Task Status (Task Status)
**Definition**: An enumerated type that indicates the progress state of a task
**Possible values**:
| Status | Meaning | Transition condition | Next state |
|----------|------|---------|---------|
| `todo` | Not started | Initial state when the task is created | `in_progress` |
| `in_progress` | In progress | The user starts the task | `completed`, `todo` |
| `completed` | Completed | The user completes the task | `todo` (can be reopened) |
**State transition diagram**:
```mermaid
stateDiagram-v2
[*] --> todo: Task created
todo --> in_progress: Work started
in_progress --> completed: Completed
in_progress --> todo: Interrupted
completed --> todo: Reopened
completed --> [*]: Archived
```
**Implementation**:
```typescript
// src/types/Task.ts
export type TaskStatus = 'todo' | 'in_progress' | 'completed';
// Validation of state transitions
function canTransition(
from: TaskStatus,
to: TaskStatus
): boolean {
const validTransitions: Record<TaskStatus, TaskStatus[]> = {
todo: ['in_progress'],
in_progress: ['completed', 'todo'],
completed: ['todo'],
};
return validTransitions[from].includes(to);
}
```
**Business rules**:
- Direct transition from `todo` → `completed` is prohibited
- A completed task can be reopened
- An archived task cannot be changed
```
## Defining errors and exceptions
**Target**: The error classes defined in the system
**Items to define**:
```markdown
## [Error name]
**Class name**: `[ErrorClassName]`
**Inherits from**: `Error` or `[ParentError]`
**Conditions for occurrence**: [When it occurs]
**Error message format**: [The format of the message]
**How to handle**:
- User: [What the user should do]
- Developer: [What the developer should do]
**Error code**: [If applicable]
**Log level**: [ERROR, WARN, INFO]
**Implementation location**: [File path]
**Usage example**: [Code example]
```
**Example**:
```markdown
## Validation Error (Validation Error)
**Class name**: `ValidationError`
**Inherits from**: `Error`
**Conditions for occurrence**:
Occurs when user input violates a business rule.
**Error message format**:
```
[Field name]: [Error description]
```
**How to handle**:
- User: Correct the input according to the error message
- Developer: Confirm whether the validation logic is correct
**Error code**: `VAL-XXX` (XXX is a 3-digit number)
**Log level**: WARN (because it is a user-caused error)
**Implementation location**: `src/errors/ValidationError.ts`
**Usage example**:
```typescript
// Throwing the error
if (title.length === 0) {
throw new ValidationError(
'Title is required',
'title',
title
);
}
// Handling the error
try {
await taskService.create(data);
} catch (error) {
if (error instanceof ValidationError) {
console.error(`Input error: ${error.message}`);
console.error(`Field: ${error.field}`);
}
}
```
**Related validations**:
- Title: 1-200 characters
- Due date: Now or later
- Priority: One of high, medium, low
```
## Maintaining and updating terms
### When to add a term
**When you should add**:
- A new concept has been introduced
- A term that team members have asked about
- A term that appears three or more times in the documentation
- When an external service or API has been integrated
**When you do not need to add**:
- General programming terms (variables, functions, etc.)
- Temporary terms used only once
### Update workflow
1. **Add or change a term**
- Add it to the appropriate category
- Fill in all definition items
- Link related terms
2. **Review**
- Share with team members
- Confirm the validity of the definition
3. **Record the change history**
- Update the change history table of the glossary
- Note it in the commit message
4. **Confirm the scope of impact**
- Search for places where the term is used
- Update documents as needed
### Managing the index
**Organize in Japanese syllabary order / alphabetical order**:
```markdown
## Index
### A-row
- [Archive](#archive) - Process term
- [Error handling](#error-handling) - Technical term
### KA-row
- [Coverage](#coverage) - Technical term
### SA-row
- [Steering file](#steering-file) - Domain term
- [Status](#task-status) - Data model term
### TA-row
- [Task](#task) - Domain term
- [TDD](#tdd) - Abbreviation
### A-Z
- [CLI](#cli) - Abbreviation
- [TypeScript](#typescript) - Technical term
```
## Checklist
- [ ] Every term is clearly defined
- [ ] Concrete examples are included
- [ ] Related terms are linked
- [ ] Categories are appropriately classified
- [ ] Technical terms include version information
- [ ] Abbreviations include their full names
- [ ] State transitions are illustrated with diagrams
- [ ] Errors include how to handle them
- [ ] The index is organized
- [ ] The change history is recorded

179
.claude/skills/glossary-creation/template.md Normal file
View File

@ -0,0 +1,179 @@
# Project Glossary
## Overview
This document manages the definitions of terms used within the project.
**Updated**: [YYYY-MM-DD]
## Domain Terms
Terms related to project-specific business concepts and features.
### [Term 1]
**Definition**: [Clear definition]
**Description**: [Detailed description]
**Related Terms**: [Other related terms]
**Usage Examples**:
- [Example 1]
- [Example 2]
**English Notation**: [English Term]
### [Term 2]
**Definition**: [Clear definition]
**Description**: [Detailed description]
**Related Terms**: [Other related terms]
**Usage Examples**:
- [Example 1]
- [Example 2]
## Technical Terms
Terms related to the technologies, frameworks, and tools used in the project.
### [Technology 1]
**Definition**: [Description of the technology]
**Official Site**: [URL]
**Usage in This Project**: [How it is used]
**Version**: [Version used]
**Related Documents**: [Links to internal documents]
### [Technology 2]
**Definition**: [Description of the technology]
**Official Site**: [URL]
**Usage in This Project**: [How it is used]
**Version**: [Version used]
## Abbreviations and Acronyms
### [Abbreviation 1]
**Full Name**: [Full Name]
**Meaning**: [Description]
**Usage in This Project**: [Where it is used]
### [Abbreviation 2]
**Full Name**: [Full Name]
**Meaning**: [Description]
**Usage in This Project**: [Where it is used]
## Architecture Terms
Terms related to system design and architecture.
### [Concept 1]
**Definition**: [Description of the architecture concept]
**Application in This Project**: [How it is implemented]
**Related Components**: [Related component names]
**Diagram**:
```
[ASCII diagram or Mermaid diagram]
```
### [Concept 2]
**Definition**: [Description of the architecture concept]
**Application in This Project**: [How it is implemented]
## Statuses and States
Definitions of various statuses used within the system.
### [Status Category 1]
| Status | Meaning | Transition Condition | Next State |
|----------|------|---------|---------|
| [State 1] | [Description] | [Condition] | [Next State] |
| [State 2] | [Description] | [Condition] | [Next State] |
**State Transition Diagram**:
```mermaid
stateDiagram-v2
[*] --> State1
State1 --> State2: Condition A
State2 --> [*]
```
## Data Model Terms
Terms related to databases and data structures.
### [Entity 1]
**Definition**: [Description of the entity]
**Key Fields**:
- `field1`: [Description]
- `field2`: [Description]
**Related Entities**: [Related entities]
**Constraints**: [Unique constraints, foreign key constraints, etc.]
## Errors and Exceptions
Errors and exceptions defined in the system.
### [Error Category 1]
**Class Name**: `[ErrorClassName]`
**Trigger Condition**: [When it occurs]
**Resolution**: [How users/developers should handle it]
**Error Code**: [If applicable]
**Example**:
```typescript
throw new [ErrorClassName]('[message]');
```
## Calculations and Algorithms (if applicable)
Terms related to specific calculation methods or algorithms.
### [Calculation Method 1]
**Definition**: [Description of the calculation method]
**Formula**:
```
[Formula]
```
**Implementation Location**: `src/[path]/[file].ts`
**Example**:
```
Input: [Example]
Output: [Result]
```

335
.claude/skills/prd-writing/SKILL.md Normal file
View File

@ -0,0 +1,335 @@
---
name: prd-writing
description: A detailed guide and template for creating a Product Requirements Document (PRD). Use only when creating a PRD.
allowed-tools: Read, Write
---
# PRD Writing Skill
This skill is a detailed guide for creating a high-quality Product Requirements Document (PRD).
## Prerequisites
Before you begin creating a PRD, the following must be complete:
### The idea has been refined through brainstorming
The user must have completed refining the product idea through dialogue with Claude Code.
### docs/ideas/initial-requirements.md has been created
**Important**: The brainstorming content must be saved by the user in the following file:
**File path**: `docs/ideas/initial-requirements.md`
This file must include the following content:
- The basic idea of the product
- The problem to be solved
- An overview of the target users
- The main features to be implemented
- The scope of the MVP
When creating the PRD, refer to the content of this file to add detail.
## Priority of existing documents
**Important**: If an existing PRD is present at `docs/product-requirements.md`,
follow the priority order below:
1. **Existing PRD (`docs/product-requirements.md`)** - Highest priority
- Contains project-specific requirements
- Takes precedence over this skill's guide
2. **This skill's guide** - Reference material
- Generic templates and examples
- Use when there is no existing PRD, or as a supplement
**When creating from scratch**: Refer to this skill's template and guide
**When updating**: Update while preserving the structure and content of the existing PRD
## Output destination
Save the PRD you create to the following location:
```
docs/product-requirements.md
```
## Template reference
When creating the PRD, use the following template: ./template.md
## PRD creation process
### 1. Review initial-requirements.md
First, review the initial requirements specification created by the user:
```bash
Read('docs/ideas/initial-requirements.md')
```
### 2. Generate the PRD draft
Based on the content of initial-requirements.md, generate the PRD following the template.
### 3. Review and improve the PRD
Review the generated PRD from the following perspectives:
#### Review perspectives
1. Is the product vision clear?
2. Are the target users specific?
3. Are the success metrics measurable?
4. Are the functional requirements detailed to an implementable level?
5. Are the non-functional requirements comprehensive?
#### Criteria for evaluating review results
Evaluate the generated PRD in the following format:
**✅ Strengths**
- A clear vision is described in a measurable and specific way
- The functional specifications are detailed to an implementation level
- KPIs are defined with quantitative metrics
**⚠️ Points that need improvement**
Ambiguity in functional requirements:
- Problem: There are areas where the concrete implementation specification is unclear
- Recommendation: Clearly state specific command specifications and error handling
Measurement method for success metrics:
- Problem: The measurement method is unclear
- Recommendation: Clearly state the measurement method and considerations for privacy
### 4. Improvement after review
Review the issues raised in the review one by one, and improve the areas that need more detail:
1. Review the raised issues one by one
2. Improve the areas that need more detail
3. After improving, conduct the review again
4. Repeat until there are no more issues
**Cautions**:
- Do not take the AI's review at face value; the final judgment must always be made by a human
- Clearly specify the review perspectives
- Have a human verify the validity of the improvement proposals
## Key points for creating a PRD
### 1. Specificity and measurability
Every requirement must be specific and measurable.
**Bad examples**:
- The system needs to be fast
- Users feel it is easy to use
**Good examples**:
- Command execution time: within 100ms (on an average PC environment)
- A new user can learn the basic operations within 5 minutes (measured by usability testing)
### 2. User-centered design
Every feature must solve a clear user problem.
**User story format**:
```
As a [user], I want [feature] so that [goal]
```
**Example**:
```
As a developer, I want a CLI-based task management tool
so that I can manage tasks without leaving the terminal
```
### 3. Clarifying priorities
Set a priority for every feature:
- **P0 (Required)**: Features to include in the MVP (Minimum Viable Product). Without these, the product does not stand as a product
- **P1 (Important)**: Features that should be added immediately after the initial release
- **P2 (Nice to have)**: Features to consider adding in the future
## Details of the main PRD sections
### 1. Product overview
#### Components
1. **Name**: Product name and subtitle
2. **Product concept**: Three main concepts
3. **Product vision**: The world you aim for, in 3-5 sentences
4. **Purpose**: A list of specific purposes
#### Example
```markdown
### Name
**Devtask** - A task management CLI tool for developers
### Product concept
- Task management that is complete within the CLI: Complete all operations without leaving the terminal
- Automatic priority estimation: Automatically estimate priority from a task's due date, creation time, status change history, and so on
- A simple and fast operating feel: Complete operations with minimal keystrokes, with instant response
### Product vision
Provide a CLI tool that lets developers efficiently manage tasks without leaving the terminal.
Specialized for command-line operation, it delivers lightweight, fast task management that does not interrupt the development flow.
With automatic priority estimation, developers can focus on essential work.
```
**Include a specific value proposition**
Bad example:
```
Build a convenient task management tool
```
Good example:
```
A CLI tool that lets developers manage tasks without leaving the terminal.
Value provided:
- Reduced context switching (zero GUI ↔ terminal switching)
- Improved work efficiency (no mouse operation, averaging a 30% time reduction)
- Integration with automation (can be embedded in shell scripts)
```
### 2. Target users (personas)
#### Required elements
1. **Basic attributes**: Age, occupation, years of experience
2. **Technology stack**: Tools and languages in use
3. **Current problems**: Specific pain points
4. **Expected solution**: What they want to become
5. **A typical daily workflow**
#### Example
```markdown
### Primary persona: Taro Tanaka (29, full-stack engineer)
- Freelancer running 3-5 projects in parallel
- Vim/Emacs + terminal environment
- Does not want to spend time on task management
- Prefers Markdown, Git, and CLI tools
```
### 3. Success metrics (KPIs)
#### SMART principles
- **S**pecific: Clear about what is being measured
- **M**easurable: Can be measured numerically
- **A**chievable: A realistic target
- **R**elevant: Related to business goals
- **T**ime-bound: Sets a deadline for achievement
#### Example
```markdown
### Primary KPIs
- Daily active users (DAU): 100 (in 3 months)
- Task completion rate: 70% or higher
- Average number of commands executed per day: 10 or more
```
### 4. Functional requirements
#### Core features (MVP)
Include the following for each feature:
- User story
- Acceptance criteria (in checklist form)
- Priority (P0/P1/P2)
**Format**:
```markdown
### [Feature name]
User story:
As a [user], I want [feature] so that [goal]
Acceptance criteria:
- [ ] Criterion 1 (measurable)
- [ ] Criterion 2 (measurable)
Priority: P0 (Required) / P1 (Important) / P2 (Nice to have)
```
#### CLI interface
For a CLI tool, include specific command examples:
```bash
# Basic operations
devtask add "Task name" --due 2025-01-15 --priority high
devtask list
devtask next # Show the task to do now
devtask done <task-id>
devtask show <task-id>
```
### 5. Non-functional requirements
Describe them in a measurable form:
**Example**:
```markdown
### Performance
- Command execution time: within 100ms (on an average PC environment)
- Task list display: within 1 second for up to 1000 items
### Usability
- A new user can learn the basic operations within 5 minutes
- All features can be checked via the help command
### Reliability
- Zero data loss (automatic backup)
- Rollback on error
```
## Quality standards and checkpoints
To ensure the quality of the PRD, confirm the following checkpoints:
### Vision and goals
- [ ] Is the product vision clear and measurable?
- [ ] Is the specific value provided defined?
- [ ] Is the target market clear?
### Target users
- [ ] Is the persona specifically defined?
- [ ] Are the current problems and expected solution clear?
- [ ] Are the technology stack and daily workflow described?
### Success metrics
- [ ] Are KPIs defined following the SMART principles?
- [ ] Is the measurement method clear?
- [ ] Is an achievement deadline set?
### Functional requirements
- [ ] Is every feature described in user story form?
- [ ] Are acceptance criteria defined in a measurable form?
- [ ] Is the priority (P0/P1/P2) clearly set?
### Non-functional requirements
- [ ] Are performance standards defined with specific numbers?
- [ ] Are usability standards measurable?
- [ ] Are reliability and security requirements clear?
## Summary
Keys to success in creating a PRD:
1. **Create based on initial-requirements.md**: Refer to the brainstorming content created by the user
2. **Specificity and measurability**: Make every requirement clear
3. **User-centered**: Only features that solve user problems
4. **Clarifying priorities**: Classify by P0/P1/P2
5. **Review and improvement**: Self-review and final human judgment
6. **Applying the SMART principles**: Especially important when defining KPIs

116
.claude/skills/prd-writing/template.md Normal file
View File

@ -0,0 +1,116 @@
# Product Requirements Document
## Product overview
### Name
**[Product name]** - [Subtitle]
### Product concept
- **[Concept 1]**: [Description]
- **[Concept 2]**: [Description]
- **[Concept 3]**: [Description]
### Product vision
[Describe the world this product aims for, in 3-5 sentences]
### Purpose
- [Purpose 1]
- [Purpose 2]
- [Purpose 3]
## Target users
### Primary persona: [Name] ([Age], [Occupation])
- [Attribute 1: e.g., freelancer running 3-5 projects in parallel]
- [Attribute 2: e.g., Vim/Emacs + terminal environment]
- [Current problem: e.g., does not want to spend time on task management]
- [Expected solution]
- [A typical daily workflow]
## Success metrics (KPIs)
### Primary KPIs
- [Metric 1]: [Target value] ([Deadline])
- Example: Daily active users (DAU): 100 (in 3 months)
- [Metric 2]: [Target value] ([Deadline])
- Example: Task completion rate: 70% or higher
### Secondary KPIs
- [Metric 1]: [Target value] ([Deadline])
- [Metric 2]: [Target value] ([Deadline])
## Functional requirements
### Core features (MVP)
#### [Feature 1]
**User story**:
As a [user], I want [feature] so that [goal]
**Acceptance criteria**:
- [ ] [Criterion 1: described in a measurable form]
- [ ] [Criterion 2: described in a measurable form]
- [ ] [Criterion 3: described in a measurable form]
**Priority**: P0 (Required)
#### [Feature 2]
**User story**:
[Description]
**Acceptance criteria**:
- [ ] [Criterion 1]
- [ ] [Criterion 2]
**Priority**: P1 (Important)
### CLI interface (if applicable)
```bash
# Example of basic operations
[command] [subcommand] [options]
# Write specific command examples
```
### Future features (Post-MVP)
#### [Feature 3]
[Brief description]
**Priority**: P2 (Nice to have)
## Non-functional requirements
### Performance
- [Requirement 1]: [Measurable standard]
- Example: Command execution time: within 100ms
- [Requirement 2]: [Measurable standard]
- Example: Task list display: within 1 second for up to 1000 items
### Usability
- [Requirement 1]: [Measurable standard]
- Example: A new user can learn the basic operations within 5 minutes
- [Requirement 2]: [Measurable standard]
### Reliability
- [Requirement 1]: [Measurable standard]
- Example: Zero data loss (automatic backup)
- [Requirement 2]: [Measurable standard]
### Security
- [Requirement 1]: [Measurable standard]
- [Requirement 2]: [Measurable standard]
### Scalability
- [Requirement 1]: [Measurable standard]
- [Requirement 2]: [Measurable standard]
## Out of scope
Items explicitly considered out of scope:
- [Item 1]
- [Item 2]
- [Item 3]

52
.claude/skills/repository-structure/SKILL.md Normal file
View File

@ -0,0 +1,52 @@
---
name: repository-structure
description: A detailed guide and template for creating a repository structure definition document. Use only when defining the repository structure.
allowed-tools: Read, Write
---
# Repository Structure Definition Skill
This skill is a detailed guide for defining a clear and maintainable repository structure.
## Prerequisites
Before you begin defining the repository structure, confirm the following:
### Required documents
1. `docs/product-requirements.md` (PRD)
2. `docs/functional-design.md` (Functional Design Document)
3. `docs/architecture.md` (Architecture Design Document)
The repository structure defines a concrete directory layout that reflects the technology stack and system composition determined during architecture design.
## Priority of existing documents
**Important**: If an existing repository structure definition document is present at `docs/repository-structure.md`, follow the priority order below:
1. **Existing repository structure definition document (`docs/repository-structure.md`)** - Highest priority
- Contains the project-specific directory structure
- Takes precedence over this skill's guide
2. **This skill's guide** - Reference material
- Generic templates and examples
- Use when there is no existing definition document, or as a supplement
**When creating from scratch**: Refer to this skill's template and guide
**When updating**: Update while preserving the structure and content of the existing definition document
## Output destination
Save the repository structure definition document you create to the following location:
```
docs/repository-structure.md
```
## Template reference
When creating the repository structure definition document, use the following template: ./template.md
## Detailed guide
For a more detailed creation guide, refer to the following file: ./guide.md

400
.claude/skills/repository-structure/guide.md Normal file
View File

@ -0,0 +1,400 @@
# Repository Structure Document Authoring Guide
## Basic Principles
### 1. Clarify Roles
Each directory should have a single, well-defined role.
**Bad example**:
```
src/
├── stuff/ # Vague
├── misc/ # Miscellaneous
└── utils/ # Too generic
```
**Good example**:
```
src/
├── commands/ # CLI command implementations
├── services/ # Business logic
├── repositories/ # Data persistence
└── validators/ # Input validation
```
### 2. Enforce Layer Separation
Reflect the architecture's layer structure in the directory structure:
```
src/
├── ui/ # UI layer
│ └── cli/ # CLI implementation
├── services/ # Service layer
│ └── task/ # Task management service
└── repositories/ # Data layer
└── task/ # Task repository
```
### 3. Split by Technical Concern (Baseline)
Split directories by related technical concerns:
**Basic structure**:
```
src/
├── commands/ # CLI commands
├── services/ # Business logic
├── repositories/ # Data persistence
└── types/ # Type definitions
```
**Mapping to the layer structure**:
```
CLI/UI layer → commands/, cli/
Service layer → services/
Data layer → repositories/, storage/
```
## Designing the Directory Structure
### Expressing the Layer Structure
```typescript
// Bad example: flat structure
src/
├── TaskCLI.ts
├── TaskService.ts
├── TaskRepository.ts
├── UserCLI.ts
├── UserService.ts
└── UserRepository.ts
// Good example: clear layers
src/
├── cli/
│ ├── TaskCLI.ts
│ └── UserCLI.ts
├── services/
│ ├── TaskService.ts
│ └── UserService.ts
└── repositories/
├── TaskRepository.ts
└── UserRepository.ts
```
### Placement of the Test Directory
**Recommended structure**:
```
project/
├── src/
│ └── services/
│ └── TaskService.ts
└── tests/
├── unit/
│ └── services/
│ └── TaskService.test.ts
├── integration/
└── e2e/
```
**Rationale**:
- Test code is separated from production code
- Easy to exclude tests at build time
- Can be organized by test type
## Naming Convention Best Practices
### Principles for Directory Names
**1. Use the plural form (layer directories)**
```
✅ services/
✅ repositories/
✅ controllers/
❌ service/
❌ repository/
❌ controller/
```
Rationale: They hold multiple files
**2. Use kebab-case**
```
✅ task-management/
✅ user-authentication/
❌ TaskManagement/
❌ userAuthentication/
```
Rationale: Compatibility with URLs and the file system
**3. Use specific names**
```
✅ validators/ # Input validation
✅ formatters/ # Data formatting
✅ parsers/ # Data parsing
❌ utils/ # Too generic
❌ helpers/ # Vague
❌ common/ # Meaningless
```
### Principles for File Names
**1. Class files: PascalCase + role suffix**
```typescript
// Service classes
TaskService.ts
UserAuthenticationService.ts
// Repository classes
TaskRepository.ts
UserRepository.ts
// Controller classes
TaskController.ts
```
**2. Function files: camelCase + start with a verb**
```typescript
// Utility functions
formatDate.ts
validateEmail.ts
parseCommandArguments.ts
```
**3. Type definition files: PascalCase or kebab-case**
```typescript
// Interface definitions
Task.ts
UserProfile.ts
// Type definition collections
task-types.d.ts
api-types.d.ts
```
**4. Constant files: UPPER_SNAKE_CASE or kebab-case**
```typescript
// Constant definitions
API_ENDPOINTS.ts
ERROR_MESSAGES.ts
// or
api-endpoints.ts
error-messages.ts
```
## Managing Dependencies
### Dependency Rules Between Layers
```typescript
// ✅ Good example: dependency from an upper layer to a lower layer
// cli/TaskCLI.ts
import { TaskService } from '../services/TaskService';
class TaskCLI {
constructor(private taskService: TaskService) {}
}
// ❌ Bad example: dependency from a lower layer to an upper layer
// services/TaskService.ts
import { TaskCLI } from '../cli/TaskCLI'; // Forbidden!
```
### Avoiding Circular Dependencies
**Problematic code**:
```typescript
// services/TaskService.ts
import { UserService } from './UserService';
export class TaskService {
constructor(private userService: UserService) {}
}
// services/UserService.ts
import { TaskService } from './TaskService'; // Circular dependency!
export class UserService {
constructor(private taskService: TaskService) {}
}
```
**Solution 1: Extract shared type definitions**
```typescript
// types/Service.ts
export interface ITaskService { /* ... */ }
export interface IUserService { /* ... */ }
// services/TaskService.ts
import type { IUserService } from '../types/Service';
export class TaskService {
constructor(private userService: IUserService) {}
}
// services/UserService.ts
import type { ITaskService } from '../types/Service';
export class UserService {
constructor(private taskService: ITaskService) {}
}
```
**Solution 2: Rethink the dependencies**
```typescript
// Extract shared functionality into a separate service
// services/NotificationService.ts
export class NotificationService {
notifyTaskAssignment(taskId: string, userId: string): void {
// Notification handling
}
}
// services/TaskService.ts
import { NotificationService } from './NotificationService';
export class TaskService {
constructor(private notificationService: NotificationService) {}
}
// services/UserService.ts
import { NotificationService } from './NotificationService';
export class UserService {
constructor(private notificationService: NotificationService) {}
}
```
## Scaling Strategy
### Recommended Structure
**Standard pattern**:
```
src/
├── commands/
│ └── TaskCommand.ts
├── services/
│ ├── TaskService.ts
│ └── UserService.ts
├── repositories/
│ ├── TaskRepository.ts
│ └── UserRepository.ts
├── types/
│ ├── Task.ts
│ └── User.ts
├── validators/
│ └── TaskValidator.ts
└── index.ts
```
**Rationale**:
- Responsibilities are clear per layer
- No later refactoring required
- Easy to standardize across a team
### Timing for Module Separation
**Signs that separation should be considered**:
1. A directory contains 10 or more files
2. Related functionality is grouped together
3. It can be tested independently
4. It has few dependencies on other features
**Separation procedure**:
```typescript
// Before: everything placed in services/
services/
├── TaskService.ts
├── TaskValidationService.ts
├── TaskNotificationService.ts
├── UserService.ts
└── UserAuthService.ts
// After: modularized by feature
modules/
├── task/
│ ├── TaskService.ts
│ ├── TaskValidationService.ts
│ └── TaskNotificationService.ts
└── user/
├── UserService.ts
└── UserAuthService.ts
```
## Handling Special Cases
### Placement of Shared Code
**shared/ or common/ directory**
```
src/
├── shared/
│ ├── utils/ # General-purpose utilities
│ ├── types/ # Shared type definitions
│ └── constants/ # Shared constants
├── commands/
├── services/
└── repositories/
```
**Rules**:
- Only things genuinely used across multiple layers
- Do not include anything used in only a single layer
### Managing Configuration Files (when applicable)
```
config/
├── default.ts # Default settings
└── constants.ts # Constant definitions
```
### Managing Scripts (when applicable)
```
scripts/
├── build.sh # Build script
└── dev-tools.ts # Development helper script
```
## Document Placement
### Document Types and Their Locations
**Project root**:
- `README.md`: Project overview
- `CONTRIBUTING.md`: Contribution guide
- `LICENSE`: License
**docs/ directory**:
- `product-requirements.md`: PRD
- `functional-design.md`: Functional design document
- `architecture.md`: Architecture design document
- `repository-structure.md`: This document
- `development-guidelines.md`: Development guidelines
- `glossary.md`: Glossary
**Within the source code**:
- TSDoc/JSDoc comments: Descriptions of functions and classes
## Checklist
- [ ] Each directory's role is clearly defined
- [ ] The layer structure is reflected in the directories
- [ ] Naming conventions are consistent
- [ ] The placement policy for test code is decided
- [ ] Dependency rules are clear
- [ ] There are no circular dependencies
- [ ] A scaling strategy has been considered
- [ ] Placement rules for shared code are defined
- [ ] A management method for configuration files is decided
- [ ] Document locations are clear

306
.claude/skills/repository-structure/template.md Normal file
View File

@ -0,0 +1,306 @@
# Repository Structure Document
## Project Structure
```
project-root/
├── src/ # Source code
│ ├── [layer1]/ # [Description]
│ ├── [layer2]/ # [Description]
│ └── [layer3]/ # [Description]
├── tests/ # Test code
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # E2E tests
├── docs/ # Project documentation
├── config/ # Configuration files
└── scripts/ # Build/deploy scripts
```
## Directory Details
### src/ (Source Code Directory)
#### [Directory 1]
**Role**: [Description]
**Files placed here**:
- [File pattern 1]: [Description]
- [File pattern 2]: [Description]
**Naming conventions**:
- [Rule 1]
- [Rule 2]
**Dependencies**:
- May depend on: [Directory name]
- Must not depend on: [Directory name]
**Example**:
```
[Directory name]/
├── [example-file1].ts
└── [example-file2].ts
```
#### [Directory 2]
**Role**: [Description]
**Files placed here**:
- [File pattern 1]: [Description]
**Naming conventions**:
- [Rule 1]
**Dependencies**:
- May depend on: [Directory name]
- Must not depend on: [Directory name]
### tests/ (Test Directory)
#### unit/
**Role**: Placement of unit tests
**Structure**:
```
tests/unit/
└── src/ # Same structure as the src directory
└── [layer]/
└── [filename].test.ts
```
**Naming conventions**:
- Pattern: `[name of file under test].test.ts`
- Example: `TaskService.ts` → `TaskService.test.ts`
#### integration/
**Role**: Placement of integration tests
**Structure**:
```
tests/integration/
└── [feature]/ # Split into directories by feature
└── [scenario].test.ts
```
#### e2e/
**Role**: Placement of E2E tests
**Structure**:
```
tests/e2e/
└── [user-scenario]/ # By user scenario
└── [flow].test.ts
```
### docs/ (Documentation Directory)
**Documents placed here**:
- `product-requirements.md`: Product Requirements Document
- `functional-design.md`: Functional design document
- `architecture.md`: Architecture design document
- `repository-structure.md`: Repository structure document (this document)
- `development-guidelines.md`: Development guidelines
- `glossary.md`: Glossary
### config/ (Configuration File Directory - when applicable)
**Files placed here**:
- Configuration files
- Constant definition files
**Example**:
```
config/
├── default.ts
└── constants.ts
```
### scripts/ (Script Directory - when applicable)
**Files placed here**:
- Build scripts
- Development helper scripts
## File Placement Rules
### Source Files
| File type | Location | Naming convention | Example |
|------------|--------|---------|-----|
| [Type 1] | [Directory] | [Rule] | [Example] |
| [Type 2] | [Directory] | [Rule] | [Example] |
### Test Files
| Test type | Location | Naming convention | Example |
|-----------|--------|---------|-----|
| Unit test | tests/unit/ | [target].test.ts | TaskService.test.ts |
| Integration test | tests/integration/ | [feature].test.ts | task-crud.test.ts |
| E2E test | tests/e2e/ | [scenario].test.ts | user-workflow.test.ts |
### Configuration Files
| File type | Location | Naming convention |
|------------|--------|---------|
| Environment config | config/environments/ | [environment-name].ts |
| Tool config | Project root | [tool-name].config.js |
| Type definitions | src/types/ | [target].d.ts |
## Naming Conventions
### Directory Names
- **Layer directories**: plural, kebab-case
- Example: `services/`, `repositories/`, `controllers/`
- **Feature directories**: singular, kebab-case
- Example: `task-management/`, `user-authentication/`
### File Names
- **Class files**: PascalCase
- Example: `TaskService.ts`, `UserRepository.ts`
- **Function files**: camelCase
- Example: `formatDate.ts`, `validateEmail.ts`
- **Constant files**: UPPER_SNAKE_CASE
- Example: `API_ENDPOINTS.ts`, `ERROR_MESSAGES.ts`
### Test File Names
- Pattern: `[target].test.ts` or `[target].spec.ts`
- Example: `TaskService.test.ts`, `formatDate.spec.ts`
## Dependency Rules
### Dependencies Between Layers
```
UI layer
↓ (OK)
Service layer
↓ (OK)
Data layer
```
**Forbidden dependencies**:
- Data layer → Service layer (❌)
- Data layer → UI layer (❌)
- Service layer → UI layer (❌)
### Dependencies Between Modules
**No circular dependencies**:
```typescript
// ❌ Bad example: circular dependency
// fileA.ts
import { funcB } from './fileB';
// fileB.ts
import { funcA } from './fileA'; // Circular dependency
```
**Solution**:
```typescript
// ✅ Good example: extract a shared module
// shared.ts
export interface SharedType { /* ... */ }
// fileA.ts
import { SharedType } from './shared';
// fileB.ts
import { SharedType } from './shared';
```
## Scaling Strategy
### Adding Features
Placement policy when adding new features:
1. **Small features**: place in an existing directory
2. **Medium features**: create a subdirectory within a layer
3. **Large features**: separate into an independent module
**Example**:
```
src/
├── services/
│ ├── TaskService.ts # Existing feature
│ └── task-management/ # Separation of a medium feature
│ ├── TaskService.ts
│ ├── SubtaskService.ts
│ └── TaskCategoryService.ts
```
### Managing File Size
**Guidelines for splitting files**:
- A single file: 300 lines or fewer recommended
- 300-500 lines: consider refactoring
- 500 lines or more: splitting strongly recommended
**How to split**:
```typescript
// Bad example: all functionality in one file
// TaskService.ts (800 lines)
// Good example: split by responsibility
// TaskService.ts (200 lines) - CRUD operations
// TaskValidationService.ts (150 lines) - validation
// TaskNotificationService.ts (100 lines) - notification handling
```
## Special Directories
### .steering/ (Steering Files)
**Role**: Define "what to do this time" for a specific development task
**Structure**:
```
.steering/
└── [YYYYMMDD]-[task-name]/
├── requirements.md # Requirements for this task
├── design.md # Design of the changes
└── tasklist.md # Task list
```
**Naming convention**: `20250115-add-user-profile` format
### .claude/ (Claude Code Settings)
**Role**: Claude Code settings and customization
**Structure**:
```
.claude/
├── commands/ # Slash commands
├── skills/ # Task-mode-specific skills
└── agents/ # Subagent definitions
```
## Exclusion Settings
### .gitignore
Files that should be excluded in the project:
- `node_modules/`
- `dist/`
- `.env`
- `.steering/` (temporary files for task management)
- `*.log`
- `.DS_Store`
### .prettierignore, .eslintignore
Files that should be excluded by tooling:
- `dist/`
- `node_modules/`
- `.steering/`
- `coverage/`

386
.claude/skills/steering/SKILL.md Normal file
View File

@ -0,0 +1,386 @@
---
name: steering
description: A skill for recording the work plan and task list for each work instruction in documents. Load it during work planning, implementation, and verification triggered by user instructions.
allowed-tools: Read, Write
---
# Steering Skill
A skill that supports implementation based on steering files (`.steering/`) and reliably manages progress in tasklist.md.
## Purpose of This Skill
- Support creation of steering files (requirements.md, design.md, tasklist.md)
- Manage incremental implementation based on tasklist.md
- **Automatically track progress and enforce tasklist.md updates**
- Record a retrospective after implementation is complete
## When to Use
Use this skill at the following times:
1. **During work planning**: when creating steering files
2. **During implementation**: when implementing according to tasklist.md
3. **During verification**: when recording the retrospective after implementation is complete
## Mode 1: Creating Steering Files
### Purpose
Create steering files for a new feature or change.
### Procedure
1. **Check the steering directory**
```
Get the current date and create a directory in the form `.steering/[YYYYMMDD]-[feature-name]/`
```
2. **Review the persistent documents**
- `docs/product-requirements.md`
- `docs/functional-design.md`
- `docs/architecture.md`
- `docs/repository-structure.md`
- `docs/development-guidelines.md`
Read these to understand the project's direction
3. **Create files from templates**
Load the following templates, replace the placeholders with concrete content, and create the files:
- `.claude/skills/steering/templates/requirements.md` → `.steering/[date]-[feature-name]/requirements.md`
- `.claude/skills/steering/templates/design.md` → `.steering/[date]-[feature-name]/design.md`
- `.claude/skills/steering/templates/tasklist.md` → `.steering/[date]-[feature-name]/tasklist.md`
4. **Detail out tasklist.md**
Based on requirements.md and design.md, flesh out tasklist.md:
- Describe the tasks of each phase concretely
- Make subtasks clear as well
- State the order of implementation
## Mode 2: Implementation (Most Important)
### Purpose
Proceed with implementation according to tasklist.md and **reliably record progress in the document**.
### 🚨 Important Principles
**MUST**:
- Implement with tasklist.md always open
- When starting a task, always update `[ ]`→`[x]` using the Edit tool
- When completing a task, always record completion using the Edit tool
- **Keep working until all tasks in tasklist.md are complete**
- NEVER: do not move on to the next task without updating tasklist.md
**NEVER**:
- Proceed with implementation without looking at tasklist.md
- Manage progress with the TodoWrite tool alone (TodoWrite is a helper; tasklist.md is the official record)
- Update multiple tasks in batch (update in real time)
- **Skip a task for reasons such as "due to time constraints" or "planned as a separate task"**
- **Finish work while leaving incomplete tasks (`[ ]`)**
### 🚨 Principle of Fully Completing Tasks
**Rules that absolutely must be followed**:
1. **Keep working until all tasks in tasklist.md are complete**
- Continue implementation until every task is `[x]`
- Do not skip for reasons such as "it takes too long" or "it's difficult"
- Do not write a retrospective while incomplete tasks remain
2. **Skipping tasks is forbidden in principle**
- "Planned as a separate task due to time constraints" is forbidden
- "Postponed because the implementation is too complex" is forbidden
- Reasons such as "it's difficult, do it later" or "testing is a hassle" are forbidden
- Skipping is permitted only for technical reasons (see below)
3. **How to handle a task that is too large**
- Split the task into smaller subtasks
- Add the split subtasks to tasklist.md
- Complete the subtasks one by one
4. **Skipping is permitted only when a task becomes unnecessary for technical reasons**
Skipping is possible only when one of the following technical reasons applies:
- A change in the implementation approach made the feature itself unnecessary
- An architecture change replaced it with a different implementation method
- A change in dependencies made the task impossible to execute
- An upper-level design change made this task meaningless
Skip procedure:
- Clearly state the technical reason in tasklist.md and mark it as skipped
- Example: `- [x] ~~task name~~ (unnecessary due to a change in approach: the architecture was changed from X to Y, so this layer is no longer needed)`
- Record the reason for the change in detail in the retrospective section
5. **Bad examples when incomplete tasks remain**
```markdown
## Post-Implementation Retrospective
**Tasks not implemented**:
- Implementing tests (planned as a separate task due to time constraints) ❌ Absolutely not allowed
```
6. **What correct completion looks like**
- All tasks are `[x]`
- There is no "tasks not implemented" entry in the retrospective section
- If the implementation approach changed, the reason is clearly stated
### Implementation Flow
#### Step 1: Load tasklist.md
```
Read('.steering/[date]-[feature-name]/tasklist.md')
```
Grasp the overall task structure and identify the next task to work on.
#### Step 2: Start task management with TodoWrite
Based on the contents of tasklist.md, create a task list with the TodoWrite tool:
- This is an auxiliary, internal Claude Code note
- **tasklist.md is the official document**
#### Step 3: Task Loop (repeat for each task)
**3-1. Check the next task**
```
Read tasklist.md and identify the next incomplete task (`[ ]`)
```
**3-2. Record the task start in tasklist.md (required)**
```
Use the Edit tool to update the relevant line in tasklist.md from `[ ]`→`[x]`
Example:
old_string: "- [ ] Implement StorageService"
new_string: "- [x] Implement StorageService"
```
**Important**: Immediately after running the Edit tool, confirm that the update succeeded.
**3-3. Update the status in TodoWrite as well**
```
Change the relevant task to "in_progress" with the TodoWrite tool
```
**3-4. Carry out the implementation**
```
Implement according to the development guidelines (docs/development-guidelines.md)
```
**3-5. Record task completion in tasklist.md (required)**
```
After implementation is complete, always update tasklist.md with the Edit tool to record completion
If there are subtasks, update each subtask individually as well
```
**3-6. Update the status in TodoWrite as well**
```
Change the relevant task to "completed" with the TodoWrite tool
```
**3-7. On to the next task**
```
Return to Step 3-1
```
#### Step 4: Checking at Phase Completion
When each phase (e.g., Phase 1, Phase 2) is complete:
1. **Load tasklist.md and check progress**
```
Read('.steering/[date]-[feature-name]/tasklist.md')
```
2. **Check completed tasks**
- Are all tasks `[x]`?
- Are there any tasks that were overlooked?
3. **Report to the user**
```
"Phase 1 is complete. Please check the progress in tasklist.md."
```
#### Step 4.5: All-Tasks-Complete Check (required)
**Always run this after implementing all phases, before writing the retrospective**:
1. **Load tasklist.md**
```
Read('.steering/[date]-[feature-name]/tasklist.md')
```
2. **Check for incomplete tasks (`[ ]`)**
- Are all tasks `[x]`?
- Is there even one `[ ]` remaining?
3. **If an incomplete task is found**
**❌ What you must not do**:
- Write "planned as a separate task due to time constraints" in the retrospective
- Ignore the incomplete task and move on to the next step
**✅ The correct response**:
**Pattern A: Implement the task**
```
Return to Step 3 (the task loop) and implement the incomplete task
```
**Pattern B: If the task is too large**
```
1. Split the task into smaller subtasks
2. Add the split subtasks to tasklist.md
3. Complete the subtasks one by one
```
**Pattern C: Only when a task became unnecessary for technical reasons**
Skipping is possible only when one of the following technical reasons applies:
- A change in the implementation approach made the feature itself unnecessary
- An architecture change replaced it with a different implementation method
- A change in dependencies made the task impossible to execute
Skip procedure:
```
1. Clearly state the technical reason in tasklist.md:
"- [x] ~~task name~~ (unnecessary due to a change in approach: describe the specific technical reason in detail)"
2. Record the reason for the change in detail in the retrospective section
3. Clearly describe why this task became unnecessary and what it was replaced with
```
4. **Proceed only after confirming all tasks are complete**
```
Confirm that every task is `[x]` before proceeding to Step 5
```
#### Step 5: After All Tasks Are Complete
1. **Final check**
```
Read('.steering/[date]-[feature-name]/tasklist.md')
```
Confirm that every task is `[x]`
2. **Record in the retrospective section**
```
Update the "Post-Implementation Retrospective" section of tasklist.md with the Edit tool:
- Implementation completion date
- Differences between plan and actual
- Lessons learned
- Improvement suggestions for next time
```
### Self-Check During Implementation
Every 5 tasks, check the following:
- [ ] Did you recently update tasklist.md? (within 5 tasks since the last update)
- [ ] Is progress reflected in the document? (verify with the Read tool)
- [ ] Can the user understand the progress by looking at tasklist.md?
## Mode 3: Retrospective
### Purpose
After implementation is complete, record a retrospective in tasklist.md.
### Procedure
1. **Load tasklist.md**
```
Read('.steering/[date]-[feature-name]/tasklist.md')
```
2. **Write the retrospective content**
- Implementation completion date
- Differences between plan and actual (points that differed from the plan)
- Lessons learned (technical insights, process improvements)
- Improvement suggestions for next time
3. **Update with the Edit tool**
```
Update the "Post-Implementation Retrospective" section of tasklist.md
```
4. **Report to the user**
```
"I have recorded the retrospective in tasklist.md. Please check the content."
```
## Troubleshooting
### If you forgot to update tasklist.md
If you notice during implementation that you forgot to update tasklist.md:
1. **Update immediately**
```
Read('.steering/[date]-[feature-name]/tasklist.md')
Identify the completed tasks and update them all to `[x]` with the Edit tool
```
2. **Report to the user**
```
"The tasklist.md update was delayed, so I have reflected the current progress."
```
3. **Prevent recurrence**
- Update reliably from the next task onward
- Strictly follow the self-check every 5 tasks
### Divergence between tasklist.md and the implementation
When the plan and the implementation differ significantly:
1. **Add an annotation to tasklist.md**
```
Add an annotation to the relevant task with the Edit tool:
"- [x] task name (changed implementation method: reason)"
```
2. **Add new tasks as needed**
```
Add new tasks with the Edit tool
```
3. **Update design.md too**
```
If the design change is significant, update design.md as well
```
## Checklist (Most Important)
Always check before implementation:
- [ ] Did you load tasklist.md?
- [ ] Did you identify the next task?
- [ ] Did you update with the Edit tool when starting the task?
Always check after implementation:
- [ ] Did you update with the Edit tool when completing the task?
- [ ] Did you check the progress in tasklist.md?
- [ ] Is it in a state where the user can understand the progress?
## Effects of This Skill
When this skill is used correctly:
- ✅ tasklist.md always reflects the latest progress
- ✅ The user can grasp progress at a glance
- ✅ Divergence between the document and the implementation disappears
- ✅ Retrospectives become easy, leading to improvements next time
- ✅ A record valuable as project history remains
## Important Reminder
🚨 **The most important role of this skill is to reliably manage the progress of tasklist.md.**
- TodoWrite is a volatile note (not visible to the user)
- **tasklist.md is the persistent document (the user sees it)**
During implementation, always ask yourself, "When the user looks at tasklist.md, can they understand the progress?"

96
.claude/skills/steering/templates/design.md Normal file
View File

@ -0,0 +1,96 @@
# Design Document
## Architecture Overview
{Describe the architecture pattern to adopt}
```
{Describe the architecture diagram in text or Mermaid}
```
## Component Design
### 1. {Component name 1}
**Responsibilities**:
- {Responsibility 1}
- {Responsibility 2}
**Implementation highlights**:
- {Points to note during implementation}
- {Technical constraints}
### 2. {Component name 2}
**Responsibilities**:
- {Responsibility 1}
- {Responsibility 2}
**Implementation highlights**:
- {Points to note during implementation}
- {Technical constraints}
## Data Flow
### {Use case name}
```
1. {Step 1}
2. {Step 2}
3. {Step 3}
```
## Error Handling Strategy
### Custom Error Classes
{Define the necessary error classes}
### Error Handling Patterns
{How errors are handled}
## Test Strategy
### Unit Tests
- {Test target 1}
- {Test target 2}
### Integration Tests
- {Test scenario 1}
- {Test scenario 2}
## Dependent Libraries
{Describe any newly added libraries}
```json
{
"dependencies": {
"{library name}": "{version}"
}
}
```
## Directory Structure
```
{File structure to be added or changed}
```
## Implementation Order
1. {Implementation step 1}
2. {Implementation step 2}
3. {Implementation step 3}
## Security Considerations
- {Security-related points to note}
## Performance Considerations
- {Performance-related points to note}
## Future Extensibility
{A design that accounts for future extensions}

48
.claude/skills/steering/templates/requirements.md Normal file
View File

@ -0,0 +1,48 @@
# Requirements
## Overview
{Describe the feature overview in 1-2 sentences}
## Background
{Why this feature is needed and what problem it solves}
## Features to Implement
### 1. {Feature name 1}
- {Specific feature description}
- {What the user will be able to do}
### 2. {Feature name 2}
- {Specific feature description}
- {What the user will be able to do}
## Acceptance Criteria
### {Feature name 1}
- [ ] {Verifiable condition 1}
- [ ] {Verifiable condition 2}
- [ ] {Verifiable condition 3}
### {Feature name 2}
- [ ] {Verifiable condition 1}
- [ ] {Verifiable condition 2}
## Success Metrics
- {Describe quantitative goals if any}
- {Describe qualitative goals if any}
## Out of Scope
The following will not be implemented in this phase:
- {Feature not implemented 1}
- {Feature not implemented 2}
## Reference Documents
- `docs/product-requirements.md` - Product Requirements Document
- `docs/functional-design.md` - Functional design document
- `docs/architecture.md` - Architecture design document

107
.claude/skills/steering/templates/tasklist.md Normal file
View File

@ -0,0 +1,107 @@
# Task List
## 🚨 Principle of Fully Completing Tasks
**Keep working until all tasks in this file are complete**
### Mandatory Rules
- **Make every task `[x]`**
- "Planned as a separate task due to time constraints" is forbidden
- "Postponed because the implementation is too complex" is forbidden
- Do not finish work while leaving incomplete tasks (`[ ]`)
### Plan Only Tasks That Can Be Implemented
- At the planning stage, list only "tasks that can be implemented"
- Do not include "tasks that might be done in the future"
- Do not include "tasks under consideration"
### The Only Case Where Skipping a Task Is Permitted
Skipping is possible only when one of the following technical reasons applies:
- A change in the implementation approach made the feature itself unnecessary
- An architecture change replaced it with a different implementation method
- A change in dependencies made the task impossible to execute
When skipping, always state the reason clearly:
```markdown
- [x] ~~task name~~ (unnecessary due to a change in approach: specific technical reason)
```
### If a Task Is Too Large
- Split the task into smaller subtasks
- Add the split subtasks to this file
- Complete the subtasks one by one
---
## Phase 1: {Phase name}
- [ ] {Task 1}
- [ ] {Subtask 1-1}
- [ ] {Subtask 1-2}
- [ ] {Task 2}
- [ ] {Subtask 2-1}
- [ ] {Subtask 2-2}
## Phase 2: {Phase name}
- [ ] {Task 1}
- [ ] {Subtask 1-1}
- [ ] {Subtask 1-2}
- [ ] {Task 2}
## Phase 3: Quality Check and Fixes
- [ ] Confirm that all tests pass
- [ ] `npm test`
- [ ] Confirm that there are no lint errors
- [ ] `npm run lint`
- [ ] Confirm that there are no type errors
- [ ] `npm run typecheck`
- [ ] Confirm that the build succeeds
- [ ] `npm run build`
## Phase 4: Documentation Updates
- [ ] Update README.md (as needed)
- [ ] Post-implementation retrospective (record at the bottom of this file)
---
## Post-Implementation Retrospective
### Implementation Completion Date
{YYYY-MM-DD}
### Differences Between Plan and Actual
**Points that differed from the plan**:
- {Technical changes not anticipated at planning time}
- {Changes in the implementation approach and the reasons}
**Tasks that became newly necessary**:
- {Tasks added during implementation}
- {Why the addition was necessary}
**Tasks skipped for technical reasons** (only when applicable):
- {Task name}
- Reason for skipping: {specific technical reason}
- Alternative implementation: {what it was replaced with}
**⚠️ Note**: Do not list tasks skipped for reasons such as "time constraints" or "difficulty" here. Completing all tasks is the principle.
### Lessons Learned
**Technical insights**:
- {Technical knowledge gained through implementation}
- {New technologies or patterns used}
**Process improvements**:
- {What went well in task management}
- {How the steering files were leveraged}
### Improvement Suggestions for Next Time
- {Things to watch out for in the next feature addition}
- {More efficient implementation methods}
- {Improvements to task planning}

12
.devcontainer/devcontainer.json Normal file
View File

@ -0,0 +1,12 @@
{
"name": "claude-code-book-chapter8",
"image": "mcr.microsoft.com/devcontainers/base:bookworm",
"workspaceFolder": "/workspaces/claude-code-book-chapter8",
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "lts"
},
"ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
},
"postCreateCommand": "npm install"
}

46
.gitignore vendored Normal file
View File

@ -0,0 +1,46 @@
# Temporary files
tmp/
# Node.js
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Build outputs
dist/
build/
*.tsbuildinfo
# Environment variables
.env
.env.local
.env.*.local
# Logs
logs/
*.log
# OS files
.DS_Store
Thumbs.db
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# Testing
coverage/
.nyc_output/
# Steering files (task management - temporary)
.steering/*
!.steering/.gitkeep
# Lock files (keep package-lock.json for consistency)
# yarn.lock
.claude/settings.local.json

2
.husky/pre-commit Normal file
View File

@ -0,0 +1,2 @@
npx lint-staged
npm run typecheck

14
.prettierignore Normal file
View File

@ -0,0 +1,14 @@
# ドキュメント・設定ディレクトリ
.claude/
.steering/
docs/
CLAUDE.md
# ログファイル
*log.json
# 依存関係
node_modules/
# ビルド成果物
dist/

9
.prettierrc Normal file
View File

@ -0,0 +1,9 @@
{
"semi": true,
"trailingComma": "es5",
"singleQuote": true,
"printWidth": 80,
"tabWidth": 2,
"useTabs": false,
"arrowParens": "always"
}

0
.steering/.gitkeep Normal file
View File

128
CLAUDE.md Normal file
View File

@ -0,0 +1,128 @@
# Project Memory
## Technology Stack
- Development environment: devcontainer
- Node.js v24.11.0
- TypeScript 5.x
- Package manager: npm
## Basic Principles of Spec-Driven Development
### Basic Flow
1. **Document creation**: Define "what to build" in persistent documents (`docs/`)
2. **Work planning**: Plan "what to do this time" in steering files (`.steering/`)
3. **Implementation**: Implement according to tasklist.md and update progress as you go
4. **Verification**: Testing and operation checks
5. **Update**: Update documents as needed
### Important Rules
#### When Creating Documents
**Create one file at a time, and always obtain the user's approval before moving on to the next.**
When waiting for approval, communicate clearly:
```
"The creation of [document name] is complete. Please review the content.
Once you approve, I will proceed to the next document."
```
#### Checks Before Implementation
Before starting a new implementation, always check the following:
1. Read CLAUDE.md
2. Read the related persistent documents (`docs/`)
3. Search for existing similar implementations with Grep
4. Understand existing patterns before starting implementation
#### Steering File Management
Create `.steering/[YYYYMMDD]-[task-name]/` for each piece of work:
- `requirements.md`: The requirements for this work
- `design.md`: The implementation approach
- `tasklist.md`: A concrete task list
Naming convention: `20250115-add-user-profile` format
#### Steering File Management
**Use the `steering` skill when planning work, implementing, and verifying.**
- **When planning work**: Mode 1 (creating steering files) via `Skill('steering')`
- **When implementing**: Mode 2 (implementation and tasklist.md update management) via `Skill('steering')`
- **When verifying**: Mode 3 (retrospective) via `Skill('steering')`
Detailed procedures and update-management rules are defined within the steering skill.
## Directory Structure
### Persistent Documents (`docs/`)
Define "what to build" and "how to build it" for the entire application:
#### Drafts and Ideas (`docs/ideas/`)
- Outputs of brainstorming and ideation
- Technical research notes
- Free-form (minimal structure)
- Automatically loaded when `/setup-project` is run
#### Official Documents
- **product-requirements.md** - Product requirements document
- **functional-design.md** - Functional design document
- **architecture.md** - Technical specification
- **repository-structure.md** - Repository structure definition document
- **development-guidelines.md** - Development guidelines
- **glossary.md** - Ubiquitous language definitions
### Work-Unit Documents (`.steering/`)
Define "what to do this time" for a specific development task:
- `requirements.md`: The requirements for this work
- `design.md`: The design of the changes
- `tasklist.md`: The task list
## Development Process
### Initial Setup
1. Use this template
2. Create persistent documents with `/setup-project` (interactively creating six)
3. Implement features with `/add-feature [feature]`
### Day-to-Day Usage
**Basically, just make requests through normal conversation:**
```bash
# Editing documents
> Please add a new feature to the PRD
> Review the performance requirements in architecture.md
> Add a new domain term to glossary.md
# Adding features (use commands for the standard flow)
> /add-feature edit user profile
# Detailed review (when a detailed report is needed)
> /review-docs docs/product-requirements.md
```
**Key point**: You do not need to be conscious of the details of spec-driven development. Claude Code will determine and load the appropriate skill.
## Principles of Document Management
### Persistent Documents (`docs/`)
- Describe the fundamental design
- Not updated frequently
- The "north star" for the entire project
### Work-Unit Documents (`.steering/`)
- Specialized for a specific task
- Created anew for each piece of work
- Retained as history

21
LICENSE Normal file
View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 Generative Agents
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

32
README.md Normal file
View File

@ -0,0 +1,32 @@
# claude-code-book-chapter8
This repository is the GitHub repository that manages the sample code for ["Practical Claude Code Introduction - A Way of Thinking About AI Coding for Real-World Use"](https://www.amazon.co.jp/dp/4297153548), published by Gijutsu-Hyohron Co., Ltd.
For detailed explanations of the code and prompts in this repository, please refer to the book.
For questions about the book's content or to report errata, please use the issues in the following repository.
https://github.com/GenerativeAgents/claude-code-book
## Notes
The content of this repository may be changed to improve prompt performance based on feedback from readers. Differences will be reflected in the book as needed, but please be aware that there may be discrepancies with the edition you have on hand.
## Usage
### 1. Clone the repository
```bash
git clone [this repository] claude-code-book-chapter8
cd claude-code-book-chapter8
```
### 2. Open via Dev Container
When you select "Reopen in Container" in Visual Studio Code, the environment is automatically set up as follows.
- Building a Node.js LTS environment
- Running npm install
- Installing the latest version of Claude Code
* When using Dev Container, you need to install Docker in advance.

336
docs/ideas/initial-requirements.md Normal file
View File

@ -0,0 +1,336 @@
# TaskCLI - Idea Notes
## Positioning of This Document
This document is the output of brainstorming and ideation; it is not a formal specification.
## Product Vision
A CLI tool that lets developers manage tasks without leaving the terminal. We want to integrate tightly with Git and GitHub, naturally connecting writing code with managing tasks.
**In a nutshell**: A task management tool integrated with Git
---
## Problems to Solve
### Current Pain Points
1. **Too much screen switching**
- Write code in the terminal -> open Trello in the browser -> go back to the terminal again
- Every switch breaks your concentration
- You do this more than 20 times a day
2. **Tasks and code are disconnected**
- You lose track of which branch you're working on for which task
- You forget to write the task number in Git commit messages
- The link between completed tasks and the PRs that were actually merged is ambiguous
3. **Too much manual work**
- Complete a task -> manually update the status -> manually create a PR -> manually close the task
- It seems automatable, but GUI tools don't integrate well
4. **The team's status is hard to see**
- You want to know who is doing what right now, but you can't tell without opening a GUI
- You can't quickly show a task list during pair programming
---
## Target Users
### Persona 1: Individual Developer
- **Age**: 25-35
- **Occupation**: Freelance engineer, someone building products on their own
- **Experience**: 5+ years of development, comfortable with CLI operations
- **Current pain points**:
- Working on multiple projects in parallel, with tasks managed only in their head
- Often thinks, "Wait, what was I supposed to do next on this project?"
- Uses GitHub Issues, but it isn't integrated with local work
- **What they want**:
- Task management that's completed entirely in the terminal
- Automatic integration with Git branches
- Simple and fast
### Persona 2: Small-Team Leader
- **Age**: 30-40
- **Occupation**: Startup lead engineer, tech lead
- **Team size**: 2-5 people
- **Experience**: 10+ years of development, with team management experience
- **Current pain points**:
- Wants to know in real time what team members are working on right now
- Checking tasks at the morning standup takes too long
- Jira and Asana are too heavy, overkill for a small team
- **What they want**:
- Quickly check the whole team's task status from the CLI
- Task progress updated automatically via GitHub integration
- Lightweight and easy to introduce
---
## Candidate Key Features
### P0 (Absolutely Required for MVP)
#### 1. Basic Task Operations
```bash
task add "Implement user authentication feature"
task list
task show 1
task done 1
task delete 1
```
#### 2. Automatic Linking of Tasks and Git Branches
```bash
task start 1
# Automatically creates and switches to the feature/task-1-user-authentication branch
git commit -m "Add login endpoint"
# Information about Task #1 is automatically appended to the commit message
```
#### 3. Task Status Management
- `open` (new)
- `in_progress` (in progress)
- `completed` (completed)
- `archived` (archived)
#### 4. Simple Task List Display
```bash
task list
ID Status Title Branch
1 in_progress Implement user auth feature/task-1-user-authentication
2 open Data export feature -
3 completed Initial setup feature/task-3-initial-setup
```
### P1 (Important but Can Wait)
#### 5. Integration with GitHub Issues
```bash
task sync
# Sync local tasks with GitHub Issues
task import --github
# Import tasks from GitHub Issues
```
#### 6. Automatic Processing on Task Completion
```bash
task done 1
# Automatically does the following:
# 1. Merge the branch into main
# 2. Push to remote
# 3. (Optional) Automatically create a GitHub PR
# 4. Change the task status to completed
```
#### 7. Task Filtering and Search
```bash
task list --status in_progress
task list --assignee me
task search "authentication"
```
#### 8. Priority and Due Date Management
```bash
task add "Urgent bug fix" --priority high --due 2025-01-20
task list --sort priority
```
### P2 (Nice to Have)
#### 9. Team Features
```bash
task list --team
# Task list for all team members
task assign 1 @alice
# Assign a task to another member
```
#### 10. Calendar Display
```bash
task calendar --week
task calendar --month
```
#### 11. Time Tracking
```bash
task start 1
# Start measuring work time
task done 1
# Record work time: 2 hours 30 minutes
```
#### 12. Task Templates
```bash
task template create bug-fix
task add --template bug-fix "Fix login screen bug"
```
---
## Differentiators
### Comparison with Existing Tools
| Feature | TaskCLI | Todoist | Trello | GitHub Issues | Linear |
|------|---------|---------|--------|---------------|--------|
| CLI operation | ✅ | ❌ | ❌ | Partial | ❌ |
| Git integration | ✅✅✅ | ❌ | ❌ | ✅ | ✅ |
| Automatic branch creation | ✅ | ❌ | ❌ | ❌ | ✅ |
| Completed in the terminal | ✅ | ❌ | ❌ | ❌ | ❌ |
| Lightweight and fast | ✅ | ✅ | △ | ✅ | △ |
| Team features | 🚧 | ✅ | ✅ | ✅ | ✅ |
### This Tool's Strengths
1. **No need to switch screens**
- Write code -> check tasks -> back to code
- Everything is completed in the terminal; no GUI needed
2. **A sense of unity with Git**
- Tasks and branches are linked one-to-one
- Commits, merges, and PRs are automatically linked with tasks
- Always clear which task you're working on
3. **Blends into the development flow**
- Start task -> create branch -> commit -> PR -> merge -> complete task
- Automates and supports this entire flow
4. **Simple**
- No need for complex features like Jira or Asana
- Only the features developers truly need
- You can start using it in one minute
---
## Technical Considerations
### Data Storage Method
**Option 1: Local file (JSON)**
- Simple, no special software required
- Stored in `.task/tasks.json`
- Can be managed with Git (shareable within a team)
**Option 2: SQLite**
- Fast search and filtering
- Can handle relational data
- File-based, easy to introduce
**Conclusion**: JSON for the MVP, migrate to SQLite when needed
### Method of Git Integration
- Use Node.js's `simple-git` library
- Automate branch creation, switching, and retrieving commit information
### Integration with the GitHub API
- Use GitHub REST API v3
- Authenticate with a Personal Access Token
- Retrieve, create, and update Issues
### CLI Framework
**Candidates**:
- Commander.js (popular, simple)
- oclif (made by Salesforce, feature-rich)
- yargs (flexible)
**Conclusion**: Commander.js (low learning cost, sufficient features)
---
## Non-Functional Requirements (For Now)
### Performance
- Command execution: within 100ms (feels instantly responsive)
- Task list display: within 1 second even for 1,000 items
### Usability
- Even first-time users can learn the basic operations in 5 minutes
- All features can be checked with the help command
- Error messages are easy to understand
### Reliability
- Data is never lost (automatic backup)
- Can be reverted if an error occurs
- Confirmation is required for dangerous operations
### Extensibility
- Plugin system (in the future)
- Can define custom commands
- Can integrate with other tools (Slack, Discord, etc.)
---
## Success Metrics (For Now)
### User Perspective
- **Adoption rate**: Introduce to 10 developers, and 3 or more keep using it for a week
- **Satisfaction**: Net Promoter Score (NPS) of 30 or above
- **Time savings**: Time spent on task management is cut in half
### Product Perspective
- **Active users**: 100 within 3 months of release
- **GitHub Stars**: 500 within 6 months of release
- **Retention rate**: 60% or more still using it after 1 month
---
## Future Considerations
### Things Not Yet Decided
1. **How far to take team features**
- How many team-oriented features should we include?
- The balance between individual developers and team development
2. **The money question (in the future)**
- Completely free and open source?
- Make the Pro version (team features) paid?
3. **Cloud sync**
- Is sync via Git enough?
- Should we provide a dedicated cloud service?
4. **Other version control systems**
- Should we also support GitLab and Bitbucket?
- What's the priority?
### Technical Concerns
1. **Environments without a Git repository**
- How do we handle this? Throw an error? Limit functionality?
2. **Performance with large repositories**
- What happens when tasks exceed 10,000?
3. **Cross-platform support**
- Does it work on Windows, macOS, and Linux?
- Does it work properly in Git Bash?
---
## Next Steps
1. **Review this document**
- Are there any missing perspectives?
- Are the priorities reasonable?
2. **Create the PRD (Product Requirements Document)**
- Create the formal document with the `/setup-project` command
- Based on these idea notes, make it more detailed and concrete
3. **Build a prototype**
- A minimal prototype with only the MVP features (P0)
- Actually use it and gather feedback

23
eslint.config.js Normal file
View File

@ -0,0 +1,23 @@
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import prettierConfig from 'eslint-config-prettier';
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommended,
prettierConfig,
{
rules: {
'@typescript-eslint/no-unused-vars': [
'error',
{ argsIgnorePattern: '^_' },
],
'@typescript-eslint/explicit-function-return-type': 'off',
'@typescript-eslint/explicit-module-boundary-types': 'off',
'@typescript-eslint/no-explicit-any': 'warn',
},
},
{
ignores: ['node_modules/**', 'dist/**', '.steering/**'],
}
);

1
mvp-log.json Normal file
View File

@ -0,0 +1 @@
{"type":"result","subtype":"success","is_error":false,"duration_ms":1014006,"duration_api_ms":1078810,"num_turns":114,"result":"## 🎉 MVP Core Features Implementation Complete\n\nThe TaskCLI application has been successfully implemented with all 6 core features from the product requirements document:\n\n### ✅ Implemented Features\n\n1. **Basic Task Operations** - Add, show, delete, archive tasks\n2. **Git Branch Auto-linking** - Automatic branch creation when starting tasks \n3. **Status Management** - Open → In Progress → Completed → Archived workflow\n4. **Simple List Display** - Formatted table output with color-coded statuses\n5. **JSON Data Persistence** - File-based storage with automatic backups\n6. **Error Handling & Help** - Comprehensive error handling and help system\n\n### 🏗️ Architecture\n\n- **3-Layer Architecture**: Clean separation of concerns\n- **TypeScript + ESM**: Modern module system with type safety\n- **CLI Framework**: Commander.js for robust command handling\n- **Git Integration**: simple-git for seamless version control\n- **Quality**: All tests passing (17/17), lint clean, typecheck passing\n\n### 🐛 Issues Resolved\n\n- **StringUtils Bug**: Fixed trailing hyphen issue in branch name sanitization\n- **Test Coverage**: Core functionality thoroughly tested\n- **Quality Score**: 4.0/5 from implementation validator\n\n### 📁 Key Files Created/Modified\n\n- `src/cli/index.ts` - Main CLI implementation\n- `src/services/` - TaskService, GitService, StorageService\n- `src/ui/UIFormatter.ts` - Display formatting\n- `src/utils/StringUtils.ts` - String sanitization (bug fixed)\n- `src/types/index.ts` - Complete type definitions\n- `package.json` - Dependencies and bin configuration\n\nThe application is now ready for use. Users can install it globally with `npm install -g .` and use the `task` command to manage their development tasks with automatic Git branch creation.","session_id":"ceb1e257-933c-4b1b-aea1-bca481bc18db","total_cost_usd":5.656692449999997,"usage":{"input_tokens":140,"cache_creation_input_tokens":165071,"cache_read_input_tokens":11013207,"output_tokens":41895,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":165071}},"modelUsage":{"claude-sonnet-4-20250514":{"inputTokens":142,"outputTokens":44144,"cacheReadInputTokens":11013207,"cacheCreationInputTokens":302737,"webSearchRequests":0,"costUSD":5.101811849999998,"contextWindow":200000},"claude-haiku-4-5-20251001":{"inputTokens":51871,"outputTokens":1873,"cacheReadInputTokens":0,"cacheCreationInputTokens":0,"webSearchRequests":0,"costUSD":0.061236000000000006,"contextWindow":200000},"claude-sonnet-4-5-20250929":{"inputTokens":255,"outputTokens":7719,"cacheReadInputTokens":238632,"cacheCreationInputTokens":81468,"webSearchRequests":0,"costUSD":0.49364460000000004,"contextWindow":200000}},"permission_denials":[],"uuid":"6087d812-c6df-4dbb-9a2c-0879bc3cc35f"}

4255
package-lock.json generated Normal file
View File

File diff suppressed because it is too large Load Diff

44
package.json Normal file
View File

@ -0,0 +1,44 @@
{
"name": "claude-code-book-chapter8",
"version": "0.1.0",
"description": "Claude Code book - Chapter 8 template",
"type": "module",
"scripts": {
"prepare": "husky",
"build": "tsc",
"dev": "tsc --watch",
"lint": "eslint .",
"format": "npx prettier --write .",
"typecheck": "tsc --noEmit",
"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest run --coverage",
"test:ui": "vitest --ui"
},
"keywords": [
"spec-driven-development",
"claude-code",
"template"
],
"author": "",
"license": "MIT",
"devDependencies": {
"@types/node": "^20.11.0",
"@vitest/coverage-v8": "^2.0.0",
"@vitest/ui": "^2.0.0",
"eslint": "^9.0.0",
"eslint-config-prettier": "^9.1.0",
"husky": "^9.0.0",
"lint-staged": "^15.2.0",
"prettier": "^3.2.0",
"typescript": "~5.3.0",
"typescript-eslint": "^8.0.0",
"vitest": "^2.0.0"
},
"lint-staged": {
"*.{ts,tsx}": [
"eslint --fix",
"prettier --write"
]
}
}

1
prompt.md Normal file
View File

@ -0,0 +1 @@
/add-feature Please develop the core feature (MVP) defined in the product requirements document.

93
src/example.test.ts Normal file
View File

@ -0,0 +1,93 @@
import { describe, it, expect } from 'vitest';
import { add, subtract, multiply, divide } from './example';
describe('Math operations', () => {
describe('add', () => {
it('正の数を足すと正しい結果が返る', () => {
// Given: 準備
const a = 2;
const b = 3;
// When: 実行
const result = add(a, b);
// Then: 検証
expect(result).toBe(5);
});
it('負の数を足すと正しい結果が返る', () => {
// Given: 準備
const a = -2;
const b = 3;
// When: 実行
const result = add(a, b);
// Then: 検証
expect(result).toBe(1);
});
});
describe('subtract', () => {
it('正の数を引くと正しい結果が返る', () => {
// Given: 準備
const a = 5;
const b = 3;
// When: 実行
const result = subtract(a, b);
// Then: 検証
expect(result).toBe(2);
});
});
describe('multiply', () => {
it('正の数をかけると正しい結果が返る', () => {
// Given: 準備
const a = 2;
const b = 3;
// When: 実行
const result = multiply(a, b);
// Then: 検証
expect(result).toBe(6);
});
it('0をかけると0が返る', () => {
// Given: 準備
const a = 5;
const b = 0;
// When: 実行
const result = multiply(a, b);
// Then: 検証
expect(result).toBe(0);
});
});
describe('divide', () => {
it('正の数で割ると正しい結果が返る', () => {
// Given: 準備
const a = 6;
const b = 3;
// When: 実行
const result = divide(a, b);
// Then: 検証
expect(result).toBe(2);
});
it('0で割るとエラーをスローする', () => {
// Given: 準備
const a = 5;
const b = 0;
// When/Then: 実行と検証
expect(() => divide(a, b)).toThrow('Division by zero is not allowed');
});
});
});

18
src/example.ts Normal file
View File

@ -0,0 +1,18 @@
export function add(a: number, b: number): number {
return a + b;
}
export function subtract(a: number, b: number): number {
return a - b;
}
export function multiply(a: number, b: number): number {
return a * b;
}
export function divide(a: number, b: number): number {
if (b === 0) {
throw new Error('Division by zero is not allowed');
}
return a / b;
}

22
tsconfig.json Normal file
View File

@ -0,0 +1,22 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"lib": ["ES2022"],
"moduleResolution": "bundler",
"resolveJsonModule": true,
"allowSyntheticDefaultImports": true,
"esModuleInterop": true,
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"types": ["vitest/globals"]
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}

29
vitest.config.ts Normal file
View File

@ -0,0 +1,29 @@
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
globals: true,
environment: 'node',
include: [
'src/**/*.{test,spec}.{ts,tsx}',
'tests/**/*.{test,spec}.{ts,tsx}',
],
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'node_modules/**',
'dist/**',
'.steering/**',
'**/*.config.{ts,js}',
'**/types/**',
],
thresholds: {
branches: 80,
functions: 80,
lines: 80,
statements: 80,
},
},
},
});