# Varubogu Gbf Discord Bot Rs Documentation > Documentation Guide - Skill: `tomevault-io/varubogu-gbf-discord-bot-rs-documentation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/varubogu-gbf-discord-bot-rs-documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/varubogu-gbf-discord-bot-rs-documentation/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/varubogu-gbf-discord-bot-rs-documentation --- # Documentation Guide ## 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 ❌ Bad (too concrete): ## User Creation Process pub async fn create_user(data: UserData) -> Result { let user = User { name: data.name, email: data.email, }; repository.save(user).await } ✅ Good (abstract design): ## User Creation Process ### Responsibilities - Validate user data - Check for duplicates - Persist to database ### Flow 1. Validate input data 2. Check email duplication 3. Create user entity 4. 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 ❌ Bad (temporal information): ## User Authentication Feature ### TODO - [ ] Implement password hashing - [ ] Add JWT token generation - [ ] Currently working on session management ### Progress Week 1: Completed user model Week 2: In progress - authentication logic ✅ Good (permanent design): ## User Authentication Feature ### Responsibilities - Validate user credentials - Generate secure session tokens - Manage user sessions ### Security Constraints - Passwords must be hashed with bcrypt - Tokens expire after 24 hours - 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 # Title ## Overview Explain purpose and big picture in 1-2 paragraphs ## Responsibilities What this feature/layer handles ## Constraints Rules to follow and prohibitions ## Flow Process flow in bullets or diagrams ## Examples Concrete examples (if needed) ``` ## Best Practices ### 1. Clear Purpose ```markdown ✅ Good: # Recruitment Notification Schedule Feature ## Purpose Periodically notify recruitment information to increase player participation. Time-based notifications support players in different timezones. ❌ Bad: # Recruitment Notification Schedule Feature A feature that manages schedules. ``` ### 2. Specify Layer Responsibilities ```markdown ✅ Good: ## Layer Responsibilities ### Service Layer - Validate recruitment data - Determine notification targets - Call Repository layer for data retrieval ### Repository Layer - Persist recruitment data - Execute queries based on search criteria ❌ Bad: ## Processing Save and retrieve data. ``` ### 3. Explicit Constraints ```markdown ✅ Good: ## Constraints - Transaction management only in Facade layer - Prohibited: Direct dependency on other Service layers - Prohibited: Long-held transactions ❌ Bad: ## Notes Be careful with transactions. ``` ### 4. Visualize Flow ```markdown ✅ Good: ## Process Flow 1. Receive user input 2. Validate input data - Check required fields - Check format 3. Check for duplicates 4. Execute within transaction: - Create entity - Save to database - Update related data 5. Return result ❌ Bad: ## Processing Save 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 # Feature Name ## Overview Purpose and big picture of this feature ## Use Cases - Use case 1: Description - Use case 2: Description ## Business Flow 1. Step 1 2. Step 2 3. Step 3 ## Constraints - Constraint 1 - Constraint 2 ## Related Features - Reference to related feature 1 - Reference to related feature 2 ``` ### Architecture Document (architecture/) ```markdown # Architecture Name ## Purpose Why adopt this architecture ## Composition Main components and responsibilities ## Design Decisions - Decision 1: Reason - Decision 2: Reason ## Constraints - Constraint 1 - Constraint 2 ``` ### Rules Document (rules/) ```markdown # Rule Name ## Principles Fundamental concepts ## ✅ Recommended Patterns Recommended implementation approach (conceptual level) ## ❌ Anti-patterns Implementation to avoid (conceptual level) ## Exceptions When 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 ❌ Bad: ## Implementation pub struct UserService { repository: Arc, } impl UserService { pub async fn create(&self, data: UserData) -> Result { self.repository.create(data).await } } ``` ### ✅ Conceptual Explanation ```markdown ✅ Good: ## UserService Responsibilities - Validate user data - Apply business rules - Persist data through Repository layer ## Flow 1. Validate input data 2. Apply business rules (e.g., age restrictions) 3. Delegate to Repository layer ``` ## Summary Documents convey **concepts and architecture**. Leave concrete implementation to code, describe "why designed this way" and "what to follow". --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/varubogu) — claim your Tome and manage your conversions.