Documentation Guide

Workflow Integration

• Check docs/en/developer/ first, then fall back to docs/ja/ when the English path is missing or incomplete
• When a behavior or design changes, update the relevant design or feature document before changing code
• Review whether the change also requires updates to locales/, migrations, or user-facing documentation

Structure

Design documents in docs/en/developer/ (recommended as the first lookup target):

docs/en/developer/
├── 01_introduction/          # Overview and onboarding
├── 02_architecture/          # Architecture and design principles (conceptual)
├── 03_development_rules/     # Coding rules and development guidelines
├── 04_testing/               # Testing rules and patterns
├── 05_database/              # Database design and policies
├── 06_feature_specifications/ # Feature specifications
└── 07_design_notes/          # Additional design notes

Directory Roles

02_architecture/

System-wide architecture and design principles

• Clean architecture layer responsibilities
• Dependency injection patterns
• Technology stack composition
• Project structure
• Discord API constraints and guidelines

Examples: layered_architecture.md, dependency_injection.md

06_feature_specifications/

Feature requirements and specifications

• Feature overview
• Use cases
• Business flows
• Constraints
• External integrations

Examples: scheduled_recruitment.md, scheduling_feature.md

05_database/

Database design

• Table definitions
• Relations
• Indexes
• Database user design
• Implementation policies (SeaORM, migrations)

Examples: overview.md, schema_management.md

03_development_rules/

Development rules and best practices

• Architecture rules
• Coding style
• Error handling
• Logging
• Security
• Performance
• Testing

Examples: coding_standards.md, error_handling.md, logging.md

07_design_notes/

Detailed design documents

• Implementation-specific design decisions
• Service layer design
• Data conversion logic
• Technical implementation details

Examples: error_classification.md, scheduling_processing.md

Documentation Principles

Abstraction Principle (Critical)

Do not include concrete code implementation

• Documents describe architecture, responsibilities, and flows conceptually
• Avoid dual maintenance of code and documentation
• Leave implementation details to code, documents explain "why" and "what"

markdown
1❌ Bad (too concrete):
2## User Creation Process
3
4pub async fn create_user(data: UserData) -> Result<User> {
5    let user = User {
6        name: data.name,
7        email: data.email,
8    };
9    repository.save(user).await
10}
11
12✅ Good (abstract design):
13## User Creation Process
14
15### Responsibilities
16- Validate user data
17- Check for duplicates
18- Persist to database
19
20### Flow
211. Validate input data
222. Check email duplication
233. Create user entity
244. Save within transaction

Permanence Principle (Critical)

Documents are permanent design references, not temporary work trackers

• Documents should remain valid regardless of implementation timeline
• Avoid including any time-bound or progress-related information
• Focus on stable design decisions and architectural principles

markdown
1❌ Bad (temporal information):
2## User Authentication Feature
3
4### TODO
5- [ ] Implement password hashing
6- [ ] Add JWT token generation
7- [ ] Currently working on session management
8
9### Progress
10Week 1: Completed user model
11Week 2: In progress - authentication logic
12
13✅ Good (permanent design):
14## User Authentication Feature
15
16### Responsibilities
17- Validate user credentials
18- Generate secure session tokens
19- Manage user sessions
20
21### Security Constraints
22- Passwords must be hashed with bcrypt
23- Tokens expire after 24 hours
24- Sessions invalidate on logout

Do not include:

• Implementation plans or roadmaps
• Progress tracking or status updates
• TODO lists or task checklists
• Temporary notes or WIP markers
• Time-sensitive information (e.g., "currently implementing...", "planned for next sprint")
• Developer assignments or timelines

Documents should be:

• Permanent design references
• Independent of who implements or when
• Focused on "what" and "why", not "when" or "who"

Language

• Repository documentation is primarily in Japanese under docs/ja/ (source of truth in many cases).
• English documentation under docs/en/ is available (often WIP). When you need to read docs for implementation decisions, look under docs/en/ first, then fall back to docs/ja/ if the content is missing.
• Technical terms can remain in English (e.g., Service layer, Repository layer). Minimize code samples.

Structure and Readability

markdown
1# Title
2
3## Overview
4Explain purpose and big picture in 1-2 paragraphs
5
6## Responsibilities
7What this feature/layer handles
8
9## Constraints
10Rules to follow and prohibitions
11
12## Flow
13Process flow in bullets or diagrams
14
15## Examples
16Concrete examples (if needed)

Best Practices

1. Clear Purpose

markdown
1✅ Good:
2# Recruitment Notification Schedule Feature
3
4## Purpose
5Periodically notify recruitment information to increase player participation.
6Time-based notifications support players in different timezones.
7
8❌ Bad:
9# Recruitment Notification Schedule Feature
10
11A feature that manages schedules.

2. Specify Layer Responsibilities

markdown
1✅ Good:
2## Layer Responsibilities
3
4### Service Layer
5- Validate recruitment data
6- Determine notification targets
7- Call Repository layer for data retrieval
8
9### Repository Layer
10- Persist recruitment data
11- Execute queries based on search criteria
12
13❌ Bad:
14## Processing
15Save and retrieve data.

3. Explicit Constraints

markdown
1✅ Good:
2## Constraints
3
4- Transaction management only in Facade layer
5- Prohibited: Direct dependency on other Service layers
6- Prohibited: Long-held transactions
7
8❌ Bad:
9## Notes
10Be careful with transactions.

4. Visualize Flow

markdown
1✅ Good:
2## Process Flow
3
41. Receive user input
52. Validate input data
6   - Check required fields
7   - Check format
83. Check for duplicates
94. Execute within transaction:
10   - Create entity
11   - Save to database
12   - Update related data
135. Return result
14
15❌ Bad:
16## Processing
17Save data.

When to Update Documentation

Update Required

1. Architecture Changes

   • Layer responsibility changes
   • New pattern introductions
   • Dependency relationship changes

2. New Feature Addition

   • Add feature spec to features/
   • Update related architecture/

3. Database Schema Changes

   • Update database/tables/
   • Update relation diagrams

4. Rule Changes

   • Update documents in rules/
   • Reflect in CLAUDE.md

Update Not Required

• Minor function name or parameter changes (per abstraction principle)
• Internal implementation optimization
• Bug fixes (not affecting design)

Document Templates

Feature Specification (features/)

markdown
1# Feature Name
2
3## Overview
4Purpose and big picture of this feature
5
6## Use Cases
7- Use case 1: Description
8- Use case 2: Description
9
10## Business Flow
111. Step 1
122. Step 2
133. Step 3
14
15## Constraints
16- Constraint 1
17- Constraint 2
18
19## Related Features
20- Reference to related feature 1
21- Reference to related feature 2

Architecture Document (architecture/)

markdown
1# Architecture Name
2
3## Purpose
4Why adopt this architecture
5
6## Composition
7Main components and responsibilities
8
9## Design Decisions
10- Decision 1: Reason
11- Decision 2: Reason
12
13## Constraints
14- Constraint 1
15- Constraint 2

Rules Document (rules/)

markdown
1# Rule Name
2
3## Principles
4Fundamental concepts
5
6## ✅ Recommended Patterns
7Recommended implementation approach (conceptual level)
8
9## ❌ Anti-patterns
10Implementation to avoid (conceptual level)
11
12## Exceptions
13When this rule doesn't apply

Review Checklist

Check when creating/modifying documents:

• No concrete code implementation included
• No temporal information (plans, progress, TODOs) included
• Responsibilities and flow clearly described
• Written in Japanese
• Constraints and prohibitions specified
• References to related documents included
• Purpose (why) explained
• Structured and readable

Common Mistakes

❌ Code Paste

markdown
1❌ Bad:
2## Implementation
3
4pub struct UserService {
5    repository: Arc<dyn UserRepository>,
6}
7
8impl UserService {
9    pub async fn create(&self, data: UserData) -> Result<User> {
10        self.repository.create(data).await
11    }
12}

✅ Conceptual Explanation

markdown
1✅ Good:
2## UserService Responsibilities
3
4- Validate user data
5- Apply business rules
6- Persist data through Repository layer
7
8## Flow
91. Validate input data
102. Apply business rules (e.g., age restrictions)
113. Delegate to Repository layer

Summary

Documents convey concepts and architecture. Leave concrete implementation to code, describe "why designed this way" and "what to follow".