create-ai-project 1.11.2

package/docs/guides/en/quickstart.md

@@ -0,0 +1,111 @@
+# Quick Start Guide for AI Development
+
+This guide walks you through setting up the AI Coding Project Boilerplate and implementing your first feature. Let's skip the complex stuff for now and just get it running.
+
+## Setup (5 minutes to complete)
+
+### For New Projects
+
+Open your terminal and run these commands. Feel free to change the project name to whatever you like.
+
+```bash
+npx github:shinpr/ai-coding-project-boilerplate my-awesome-project
+cd my-awesome-project
+npm install
+```
+
+That's it! You now have a `my-awesome-project` folder with all the necessary files ready to use.
+
+### For Existing Projects
+
+If you already have a TypeScript project, you can copy the necessary files. First, download the boilerplate to a temporary location.
+
+```bash
+# Download the boilerplate temporarily
+npx github:shinpr/ai-coding-project-boilerplate temp-boilerplate
+```
+
+Then copy the following files into the root directory of your existing project.
+
+```bash
+# Run in your existing project directory
+cp -r temp-boilerplate/.claude/agents .claude/agents
+cp -r temp-boilerplate/.claude/commands .claude/commands
+cp -r temp-boilerplate/docs/rules docs/rules
+cp -r temp-boilerplate/docs/adr docs/
+cp -r temp-boilerplate/docs/design docs/
+cp -r temp-boilerplate/docs/plans docs/
+cp -r temp-boilerplate/docs/prd docs/
+cp -r temp-boilerplate/docs/guides/en/sub-agents.md docs/guides/sub-agents.md
+cp temp-boilerplate/CLAUDE.md .
+```
+
+If you want to change the directory structure, you'll need to adjust paths starting with `@docs/rules/` in sub-agents and command definition files. Also update `docs/rules-index.yaml` accordingly.
+Because this can get complicated, we recommend sticking with the default structure unless you have specific needs.
+
+## Launch Claude Code and Initial Setup
+
+Launch Claude Code in your project directory.
+
+```bash
+claude
+```
+
+Once launched, let's set up project-specific information. This is a crucial step for the AI to understand your project.
+
+Run the following custom slash command inside Claude Code.
+
+```bash
+/project-inject
+```
+
+You'll be guided through an interactive dialog to clarify your project information. Feel free to answer casually - you can change this information later.
+Once you finish answering, your project context will be saved to `docs/rules/project-context.md`. This enables the AI to understand your project's purpose and generate more appropriate code.
+
+After reviewing the file and confirming it looks good, complete this step with the following command.
+
+```bash
+/sync-rules
+```
+
+## Let's Implement Your First Feature
+
+Now let's create your first feature. Specify it using the following command in Claude Code.
+
+```bash
+/implement Create a simple API that returns "Hello"
+```
+
+The `/implement` command guides you through the entire workflow from design to implementation.
+
+First, it analyzes your requirements to determine the feature scale. It might say something like "This is a medium-scale feature requiring about 3 files." Based on the scale, it creates necessary design documents.
+
+For small features, it creates just a simple work plan. For large features, it creates a complete flow from PRD (Product Requirements Document) to Design Doc (Technical Design Document). After each design document is created, an automatic review is performed.
+
+Once the design is complete, the AI will ask "Here's the design I've created. Could you review it?" Read through it and request changes if needed, or approve it if it looks good.
+Depending on the Claude Code model you're using, it may automatically proceed to the next design document if your review is positive. At some point it will ask for your approval, so you can provide batch feedback then.
+
+After design approval, integration test skeletons and a work plan are created. Once you review the implementation steps (requesting changes if needed) and approve, the actual implementation begins.
+
+The AI breaks down the work plan into single-commit task units and autonomously implements each task using a TDD approach. After each task, it performs a defined 6-step quality check, fixes any errors, and creates a commit if everything passes. You can simply watch the progress.
+
+When all tasks are complete, it will report "Implementation complete." Check `git log` to see a clean series of commits.
+
+## Development Philosophy of This Boilerplate
+
+Let me explain the thinking behind this boilerplate.
+
+To maximize throughput with AI assistance, it's crucial to minimize human intervention. However, achieving high execution accuracy with AI requires careful context management—providing the right information at the right time. Without proper systems, humans need to guide the implementation process, which prevents throughput maximization.
+
+This boilerplate solves this through systematic approaches: selecting appropriate context (rules, requirements, specifications) for each phase and limiting unnecessary information during task execution.
+
+The workflow is: create design documents, review them with users to align understanding, use those documents as context for planning and task creation. Tasks are executed by sub-agents with dedicated contexts, which removes unnecessary information and stabilizes implementation. This system helps maintain quality even for projects too large to fit within a single coding agent's context window (Claude Opus 4.1 supports 200K tokens, Sonnet 4 beta supports up to 1M tokens, but the basic limit is 200K tokens).
+
+For detailed mechanics, see [this article](https://dev.to/shinpr/zero-context-exhaustion-building-production-ready-ai-coding-teams-with-claude-code-sub-agents-31b).
+
+## Troubleshooting
+
+If things aren't working, check the following.
+
+**If implementation stops midway**
+Describe the current state to Claude Code and ask it to resume, for example: "You've completed up to the Design Doc creation, so please continue from there and complete the implementation."

package/docs/guides/en/rule-editing-guide.md

@@ -0,0 +1,266 @@
+# Rule Editing Guide
+
+This guide explains the core concepts and best practices for writing effective rules that maximize LLM execution accuracy, based on how LLMs work.
+
+## Project Philosophy and the Importance of Rule Files
+
+This boilerplate is designed based on the concepts of "Agentic Coding" and "Context Engineering":
+- **Agentic Coding**: LLMs autonomously making decisions and carrying out implementation tasks
+- **Context Engineering**: Building mechanisms to provide appropriate context at the right time for LLMs to make proper decisions
+
+For details, see [this article](https://dev.to/shinpr/zero-context-exhaustion-building-production-ready-ai-coding-teams-with-claude-code-sub-agents-31b).
+
+Proper rule management and [sub-agents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) are crucial keys to realizing these concepts.
+
+Rule files are written to maximize LLM execution accuracy as described below.
+
+Sub-agents have dedicated contexts separate from the main agent. They are designed to load only the necessary rule files to fulfill specific responsibilities.
+When the main agent executes tasks, it uses "metacognition" (reflecting on and analyzing its own reasoning process) to understand task context, select necessary rules from the rule file collection, and execute tasks.
+This approach maximizes execution accuracy by retrieving the right rules at the right time without excess or deficiency.
+
+While it's impossible to completely control LLM output, it is possible to maximize execution accuracy by establishing proper systems.
+Conversely, LLM execution accuracy can easily degrade depending on rule file content.
+
+With the premise that complete control is impossible, executing tasks, reflecting on issues that arise, and feeding back into the system enables maintaining and improving execution accuracy.
+When using this in actual projects and results don't match expectations, consider improving rule files.
+
+## Determining Where to Document Rules
+
+### File Roles and Scope
+
+| File | Scope | When Applied | Example Content |
+|------|-------|--------------|-----------------|
+| **CLAUDE.md** | All tasks | Always | Approval required before Edit/Write, stop at 5+ file changes |
+| **Rule files** | Specific technical domains | When using that technology | Use specific types, error handling required, functions under 30 lines |
+| **Guidelines** | Specific workflows | When performing that workflow | Sub-agent selection strategies |
+| **Design Docs** | Specific features | When developing that feature | Feature requirements, API specifications, security constraints |
+
+### Decision Flow
+
+```
+When is this rule needed?
+├─ Always → CLAUDE.md
+├─ Only for specific feature development → Design Doc
+├─ When using specific technology → Rule files
+└─ When performing specific workflow → Guidelines
+```
+
+## 9 Rule Principles for Maximizing LLM Execution Accuracy
+
+Here are 9 rule creation principles based on LLM characteristics and this boilerplate's design philosophy.
+While we provide a `/refine-rule` custom slash command to assist with rule modifications, we ultimately recommend interactive rule editing through dialogue rather than commands, as LLMs tend to have difficulty reaching issues without comparing output with thinking after generation.
+
+### 1. Achieve Maximum Accuracy with Minimum Description (Context Pressure vs. Execution Accuracy)
+
+Context is a precious resource. Avoid redundant explanations and include only essential information.
+However, it's not just about being short - it must be the minimum description that doesn't cause decision hesitation.
+
+```markdown
+❌ Redundant description (22 words)
+Please make sure to record all errors in the log when they occur
+
+✅ Concise description (9 words)
+All errors must be logged
+
+❌ Over-abbreviated description (6 words)
+Record all errors
+```
+
+Aim for concise expressions that keep the same meaning. But don't shorten so much that ambiguity is introduced.
+
+### 2. Completely Unify Notation
+
+Always use the same terms for the same concepts. Notation inconsistencies hinder LLM understanding.
+
+```markdown
+# Term Definitions (Unified across project)
+- API response/return value → Unified as `response`
+- User/customer → Unified as `user`
+- Error/abnormality → Unified as `error` (exception/failure may be used depending on context)
+```
+
+### 3. Thoroughly Eliminate Duplication
+
+Repeating the same content across multiple files wastes context capacity. Consolidate in one place.
+
+```markdown
+❌ Same content in multiple locations
+# docs/rules/base.md
+Standard error format: { success: false, error: string, code: number }
+
+# docs/rules/api.md
+Error responses follow standard error format `{ success: false, error: string, code: number }`
+
+✅ Consolidated in one location
+# docs/rules/base.md
+Standard error format: { success: false, error: string, code: number }
+```
+
+Check for duplication between files and eliminate contradictions and redundancy.
+Eliminating duplication also reduces maintenance costs by preventing notation inconsistencies from update omissions.
+
+### 4. Appropriately Aggregate Responsibilities
+
+Consolidating related content in one file maintains single responsibility and prevents unnecessary context mixing in tasks.
+
+```markdown
+# Authentication consolidated in one file
+docs/rules/auth.md
+├── JWT Specification
+├── Authentication Flow
+├── Error Handling
+└── Security Requirements
+
+# ❌ Dispersed responsibilities
+docs/rules/auth.md
+├── JWT Specification
+├── Error Handling
+└── Security Requirements
+docs/rules/flow.md
+├── User Registration Flow
+└── Authentication Flow
+```
+
+However, if a file becomes too large, reading costs increase, so aim for logical division or rule selection around 250 lines (approximately 1,500 tokens).
+
+### 5. Set Measurable Decision Criteria
+
+Ambiguous instructions cause interpretation inconsistencies. Clarify criteria with numbers and specific conditions.
+
+```markdown
+✅ Measurable criteria
+- Function lines: 30 or less
+- Cyclomatic complexity: 10 or less
+- Response time: Within 200ms at p95
+- Test coverage: 80% or more
+
+❌ Ambiguous criteria
+- Readable code
+- Fast processing
+- Sufficient tests
+```
+
+Note that LLMs cannot understand time, so descriptions like "break down tasks to complete within 30 minutes" are not effective.
+
+### 6. Show NG Patterns as Recommendations with Background
+
+Showing recommended patterns with reasons is more effective than listing prohibitions.
+
+```markdown
+✅ Description in recommended format
+【State Management】
+Recommended: Use Zustand or Context API
+Reason: Global variables are difficult to test and state tracking is complex
+NG Example: window.globalState = { ... }
+
+❌ List of prohibitions
+- Don't use global variables
+- Don't save values to window object
+```
+
+If prohibitions are needed, present them as background context rather than the main rule.
+
+### 7. Verbalize Implicit Assumptions
+
+Even things obvious to human developers must be explicitly stated for LLMs to understand.
+
+```markdown
+## Prerequisites
+- Execution environment: Node.js 20.x on AWS Lambda
+- Maximum execution time: 15 minutes (Lambda limit)
+- Memory limit: 3GB
+- Concurrent executions: 1000 (account limit)
+- Timezone: All UTC
+- Character encoding: UTF-8 only
+```
+
+Use the `/project-inject` command at project start or when project assumptions change to document project context as rules.
+
+### 8. Arrange Descriptions by Importance
+
+LLMs pay more attention to information at the beginning. Place most important rules first, exceptional cases last.
+
+```markdown
+# API Rules
+
+## Critical Principles (Must follow)
+1. All APIs require JWT authentication
+2. Rate limit: 100 requests/minute
+3. Timeout: 30 seconds
+
+## Standard Specifications
+- Methods: Follow REST principles
+- Body: JSON format
+- Character encoding: UTF-8
+
+## Exceptional Cases (Only for special situations)
+- multipart/form-data allowed only for file uploads
+- WebSocket connections only at /ws endpoint
+```
+
+### 9. Clarify Scope Boundaries
+
+Explicitly stating what is and isn't covered prevents unnecessary processing and misunderstandings.
+
+```markdown
+## Scope of This Rule
+
+### Covered
+- REST APIs in general
+- GraphQL endpoints
+- WebSocket communication
+
+### Not Covered
+- Static file delivery
+- Health check endpoint (/health)
+- Metrics endpoint (/metrics)
+```
+
+## Reference: Efficient Rule Writing
+
+Rule files under `docs/rules` are created with these principles in mind.
+Each is written with no duplication, single responsibility, and minimal description, serving as references when adding or creating new rules.
+
+### Correspondence Between Rule Files and Applied Principles
+
+| Rule File | Main Content | Examples of Applied Principles |
+|-----------|-------------|--------------------------------|
+| **typescript.md** | TypeScript code creation/modification/refactoring, modern type features | **Principle 2**: Unified notation (consistent terms like "any type completely prohibited")<br>**Principle 5**: Measurable criteria (20 fields max, 3 nesting levels max) |
+| **typescript-testing.md** | Test creation, quality checks, development steps | **Principle 5**: Measurable criteria (coverage 70% or more)<br>**Principle 8**: Arrangement by importance (quality requirements at the top) |
+| **ai-development-guide.md** | Technical decision criteria, anti-pattern detection, best practices | **Principle 6**: Show NG patterns in recommended format (anti-pattern collection)<br>**Principle 3**: Eliminate duplication (Rule of Three for consolidation decisions) |
+| **technical-spec.md** | Technical design, environment setup, documentation process | **Principle 4**: Aggregate responsibilities (technical design in one file)<br>**Principle 7**: Verbalize implicit assumptions (security rules documented) |
+| **project-context.md** | Project-specific information, implementation principles | **Principle 7**: Verbalize implicit assumptions (project characteristics documented)<br>**Principle 1**: Maximum accuracy with minimum description (concise bullet format) |
+| **documentation-criteria.md** | Scale determination, document creation criteria | **Principle 5**: Measurable criteria (creation decision matrix)<br>**Principle 9**: Clarify scope boundaries (clearly state what's included/excluded) |
+| **implementation-approach.md** | Implementation strategy selection, task breakdown, large-scale change planning | **Principle 8**: Arrangement by importance (Phase-ordered structure)<br>**Principle 6**: Show NG patterns in recommended format (risk analysis) |
+
+All 9 principles are practiced across these files, serving as practical references for rule creation.
+
+## Troubleshooting
+
+### Problem: Rules are too long and overload the context window
+
+**Solutions**
+1. Find and remove duplications
+2. Minimize examples
+3. Utilize reference format
+4. Move low-priority rules to separate files
+
+### Problem: Inconsistent generation results
+
+**Solutions**
+1. Unify terms and notation
+2. Quantify decision criteria
+3. Clarify priorities
+4. Eliminate contradicting rules
+
+### Problem: Important rules are not followed
+
+**Solutions**
+1. Move to file beginning
+2. Add 【Required】【Important】 tags
+3. Add one specific example
+4. Convert negative form to positive form
+
+## Summary
+
+Well-written rules stabilize LLM output. By following the 9 principles and continuously refining your rules, you can maximize LLM capabilities. Build the optimal rule set for your project through regular implementation review and improvement.