create-ai-project 1.11.2

package/docs/guides/ja/quickstart.md

@@ -0,0 +1,112 @@
+# クイックスタート - AIと一緒に開発を始めよう
+
+このガイドでは、AI コーディングプロジェクトボイラープレートを使って、最初の機能を実装するまでの手順を説明します。難しいことは後回しにして、まずは動かしてみましょう。
+
+## セットアップ（5分で完了）
+
+### 新規プロジェクトを始める場合
+
+ターミナルを開いて、以下のコマンドを実行するだけです。プロジェクト名は好きなものに変えてください。
+
+```bash
+npx github:shinpr/ai-coding-project-boilerplate my-awesome-project --lang=ja
+cd my-awesome-project
+npm install
+```
+
+これで準備完了です。`my-awesome-project` というフォルダが作られ、必要なファイルがすべて揃った状態になります。
+
+### 既存のプロジェクトに導入する場合
+
+すでにTypeScriptプロジェクトがある場合は、必要なファイルをコピーして使うこともできます。まず、ボイラープレートを別の場所にダウンロードします。
+
+```bash
+# 一時的にボイラープレートをダウンロード
+npx github:shinpr/ai-coding-project-boilerplate temp-boilerplate --lang=ja
+```
+
+次に、既存プロジェクトのルートディレクトリで以下のファイルをコピーします。
+
+```bash
+# 既存プロジェクトのディレクトリで実行
+cp -r temp-boilerplate/.claude/agents-ja .claude/agents
+cp -r temp-boilerplate/.claude/commands-ja .claude/commands
+cp -r temp-boilerplate/docs/rules-ja 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 temp-boilerplate/docs/guides/ja/sub-agents.md docs/guides/sub-agents.md
+cp temp-boilerplate/CLAUDE.md .
+```
+
+もしディレクトリ構成を変更したい場合は、サブエージェント（Sub agents）やコマンド定義ファイル内の `@docs/rules/` で始まるパスを調整する必要があります。また、`docs/rules-index.yaml` も同様に修正してください。
+煩雑なため、特に事情がない場合はデフォルトの構成のまま使うことをお勧めします。
+
+## Claude Codeを起動して最初の設定
+
+プロジェクトディレクトリで Claude Code を起動します。
+
+```bash
+claude
+```
+
+起動したら、まずプロジェクト固有の情報を設定しましょう。これは、AIがあなたのプロジェクトを理解するための重要なステップです。
+
+Claude Codeに以下のコマンド（カスタムスラッシュコマンド）を入力します。
+
+```bash
+/project-inject
+```
+
+対話的に、プロジェクトの情報を明らかにしていきます。この情報は後から変更できるので、気軽に回答をしてみてください。
+質問に答え終わると、プロジェクトの背景情報が `docs/rules/project-context.md` に保存されます。これで、AIはあなたのプロジェクトの目的を理解して、より適切なコードを生成できるようになります。
+
+ファイルの内容を確認し、問題がなければ最後に以下のコマンドを入力し、このステップは完了です。
+
+```bash
+/sync-rules
+```
+
+## 最初の機能を実装してみよう
+
+さあ、実際に機能を作ってみましょう。Claude Codeに作成したい機能の内容をコマンド付きで入力してみてください。
+
+```bash
+/implement Helloと返す簡単なAPIを作成したいです。
+```
+
+/implementコマンドを使うと、設計から実装までの一連の作業を順に進めてくれます。
+
+まず、あなたの要求を分析して、どのくらいの規模の機能なのかを判定します。「これは3ファイルくらいの中規模な機能です」といった具合です。規模に応じて、必要な設計書を作成していきます。
+
+小さな機能なら簡単な計画書だけ、大きな機能ならPRD（プロダクト要求仕様書）からDesign Doc（技術設計書）まで順次作成していきます。各設計書の作成が終わると、自動的にドキュメントのレビューが実施されます。
+
+レビューが終わり設計書ができると、AIが「こんな設計にしましたが、確認してもらえますか？」と聞いてきます。内容を読んで、気になる点があれば修正をお願いできます。問題なければ承認してください。
+利用しているClaude Codeのモデルによっては、レビューの結果が良好であった場合に次の設計書の作成に進むことがあります。どこかのタイミングではあなたに承認を求めてくるので、その場合はまとめて修正指示を出してください。
+
+設計が承認されると、次は結合テストのスケルトンと作業計画書が作られます。実装の手順が示されますので、確認（必要に応じて修正依頼）して承認すると、いよいよ実装が始まります。
+
+AIは作業計画を1コミットの単位にタスク分解して、1タスクずつTDDアプローチで自律的に実装していきます。各タスクが終わるごとに定められた6ステップの品質チェックを行い、エラーを修正し、問題がなければコミットを作成します。あなたは進捗を眺めているだけで大丈夫です。
+
+すべてのタスクが完了すると、「実装が完了しました」と報告してくれます。`git log` を見ると、きれいにコミットが積み重なっているはずです。
+
+## このボイラープレートの開発思想
+
+最後に、このボイラープレートがどんな考え方で作られているかを説明します。
+
+AI活用によるスループットを最大化するためには、極力人間が介入する場面を減らすことが重要です。
+ですが、AIの実行精度を最大化しようとするとコンテキスト管理が非常に重要になるため、適切なタイミングで適切な情報を与えなくてはならず、仕組みを整えなければ人が付き添い実装を進める必要が生じます。そうなってはスループットは最大化できません。
+
+そこで、このボイラープレートでは、各フェーズに対して適切なコンテキスト（ルールや要件、仕様）が選択されること、タスクの実行には不要となる情報を制限すること、これらを仕組みで解決しようとしています。
+
+まずは設計書を作り、それをユーザーとレビューし、認識を揃える。その設計書をコンテキストとして作業を計画し、タスクを作る。タスクの実行は専用のコンテキストを持つサブエージェントが担うことで、タスクに不要な情報が入らず実装が安定する。このような仕組みにすることで、コーディングエージェント単体ではコンテキストウィンドウに収まらないような規模な開発でも品質を保ちながら進められるようになります（Claude Opus 4.1では200Kトークン、Sonnet 4ではベータ版で1Mトークンまで対応していますが、基本は200Kトークンという制限があります）。
+
+詳しい仕組みについては、[こちらの記事](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)で解説されています。興味があれば読んでみてください。
+
+## トラブルシューティング
+
+うまくいかないときは、以下を確認してください。
+
+**実装が途中で止まった場合**
+「/implement Design Doc作成まで終わっているので、続きから再開して実装まで完遂してください」のように、現在の状態を伝えて再開を依頼してください。

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

@@ -0,0 +1,266 @@
+# ルール編集ガイド
+
+このガイドでは、LLMの特性を踏まえた実行精度を最大化させるための効果的なルール作成について、考え方・ポイントを提供します。
+
+## 本ボイラープレートの思想とルールファイルの重要性について
+
+このボイラープレートは、「Agentic Coding」「Context Engineering」の概念を元に設計されています。
+- Agentic Coding: LLMが自律的に判断し、実装タスクを遂行すること
+- Context Engineering: LLMが適切な判断を下すために必要な文脈を、適切なタイミングで提供する仕組みを構築すること
+
+詳細は[この記事](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)を参照してください。
+
+これらの概念を実現するためには、適切なルールの管理と[サブエージェント](https://docs.anthropic.com/ja/docs/claude-code/sub-agents)の存在が重要なキーとなります。
+
+ルールファイルは後述するLLMの実行精度を最大化する観点で記載されています。
+
+サブエージェントはメインエージェントとは異なる専用のコンテキストを持つため、単一責務を果たすために必要なルールファイルのみを読み込みタスクを実行するように設計されています。
+メインエージェントがタスクを実行する際は、「メタ認知（自分の思考や学習プロセスを客観的に把握すること）」の概念を用い、タスクの背景を理解し、ルールファイル群からタスクに必要なルールをピックアップし、タスクを実行します。
+適切なタイミングで過不足ないルールを取得することで、実行精度を最大化しようというアプローチです。
+
+LLMの出力を完全に制御することは不可能ですが、仕組みを整備することで、実行精度を最大化することは可能です。
+裏を返すと、ルールファイルの内容によって、LLMの実行精度は容易に低下してしまいます。
+
+完全に制御することはできないという前提を持った上でタスクを実行させ、生じた課題を振り返り、仕組みにフィードバックをしていくことで、実行精度の維持向上が実現します。
+実際のプロジェクトで活用し、思ったような結果にならなかった時は、ルールファイルの改善を検討してみてください。
+
+## どのファイルに記載するべきかの判断基準
+
+### ファイルごとの役割と適用範囲
+
+| ファイル | 適用範囲 | 適用タイミング | 記載する内容の例 |
+|---------|----------|--------------|--------------|
+| **CLAUDE.md** | 全タスク | 常時適用 | Edit/Write前の承認必須、5ファイル以上変更で停止 |
+| **ルールファイル** | 特定技術領域 | その技術使用時 | 具体的な型を使用、エラーハンドリング必須、関数30行以内 |
+| **ガイドライン** | 特定作業 | その作業実施時 | サブエージェントの使い分け方 |
+| **Design Doc** | 特定機能 | その機能開発時 | その機能の必須要件、APIの仕様、セキュリティ制約 |
+
+### 判断フローチャート
+
+```
+いつこのルールが必要か？
+├─ 常に必要 → CLAUDE.md
+├─ 特定機能の開発時のみ → Design Doc
+├─ 特定技術を使用する時 → ルールファイル
+└─ 特定の作業を行う時 → ガイドライン
+```
+
+## LLMの実行精度を最大化する9つのルール原則
+
+LLMの特性と本ボイラープレートの設計思想を踏まえた、ルール作成の原則を9つ紹介します。
+`/refine-rule`コマンドというルールの変更を支援するカスタムスラッシュコマンドも提供していますが、LLMの特性として「生成後に出力と考え方を突き合わせなければ課題に到達しづらい傾向」があるため、コマンドを用いず対話的にルールの修正を行うことを最終的には推奨します。
+
+### 1. 最小記述で最大精度を実現する（コンテキスト圧迫 vs 実行精度）
+
+コンテキストは貴重なリソースです。冗長な説明を避け、本質的な情報のみを記述します。
+一方で、ただ短くすればいいという訳ではなく、判断に迷わない最小限の記述でなければいけません。
+
+```markdown
+❌ 冗長な記述（24文字）
+エラーが発生した場合は必ずログに記録してください
+
+✅ 簡潔な記述（12文字）
+エラーは全てログ記録必須
+
+❌ 省略しすぎた記述（8文字）
+エラーは全て記録
+```
+
+同じ意味なら短い表現を心がけてください。ただし、曖昧さが生じるほど短くしないよう心がけてください。
+
+### 2. 表記を完全に統一する
+
+同じ概念には常に同じ用語を使います。表記のブレはLLMの理解を妨げます。
+
+```markdown
+# 用語定義（プロジェクト全体で統一）
+- API応答/返り値 → `レスポンス`で統一
+- 利用者/顧客 → `ユーザー`で統一
+- 誤り/異常 → `エラー`で統一（例外/障害は文脈によっては使い分ける）
+```
+
+### 3. 重複を徹底的に排除する
+
+同じ内容を複数箇所に書くのはコンテキストの無駄遣いです。1箇所にまとめます。
+
+```markdown
+❌ 複数箇所に同じ内容が記載されている
+# docs/rules/base.md
+標準エラー形式：{ success: false, error: string, code: number }
+
+# docs/rules/api.md
+エラーレスポンスは `{ success: false, error: string, code: number }` の標準エラー形式に従う
+
+✅ 1箇所に集約されている
+# docs/rules/base.md
+標準エラー形式：{ success: false, error: string, code: number }
+```
+
+ファイル間の重複もチェックし、矛盾や冗長性を排除します。
+更新漏れによる表記揺れのリスクもあるため、重複の排除はメンテナンスコストの低下にもつながります。
+
+### 4. 責務を適切に集約する
+
+関連する内容は1つのファイルにまとめることで単一責務を維持でき、タスクに不要なコンテキストの混入を防げます。
+
+```markdown
+# 認証関連は1ファイルに集約
+docs/rules/auth.md
+├── JWT仕様
+├── 認証フロー
+├── エラーハンドリング
+└── セキュリティ要件
+
+# ❌ 責務を分散させる
+docs/rules/auth.md
+├── JWT仕様
+├── エラーハンドリング
+└── セキュリティ要件
+docs/rules/flow.md
+├── ユーザー登録フロー
+└── 認証フロー
+```
+
+ただし、1ファイルが巨大になりすぎると読み込みコストが高くなるため、300行前後（約1,500トークン）を目安に論理的な単位での分割やルールの厳選を行なってください。
+
+### 5. 測定可能な判断基準を設定する
+
+曖昧な指示は解釈のブレを生みます。数値や具体的な条件で判断基準を明確化します。
+
+```markdown
+✅ 測定可能な基準
+- 関数の行数：30行以下
+- 循環的複雑度：10以下
+- レスポンスタイム：p95で200ms以内
+- テストカバレッジ：80%以上
+
+❌ 曖昧な基準
+- 読みやすいコード
+- 高速な処理
+- 十分なテスト
+```
+
+注意点として、LLMは時間を理解でないため「30分以内に完了する粒度でタスク分解をする」といった記載は効果的に作用しません。
+
+### 6. NGパターンを推奨・背景としてのNG形式で示す
+
+禁止事項の羅列より、推奨パターンとその理由を示す方が効果的です。
+
+```markdown
+✅ 推奨形式での記述
+【状態管理】
+推奨：Zustandまたは Context API を使用
+理由：グローバル変数はテスト困難、状態追跡が複雑
+NG例：window.globalState = { ... }
+
+❌ 禁止の羅列
+- グローバル変数を使うな
+- window オブジェクトに値を保存するな
+```
+
+禁止事項は背景情報として活用しましょう。
+
+### 7. 暗黙の前提を言語化する
+
+プロジェクト内では当然な内容でも、LLMには明示しなければ伝わりません。
+
+```markdown
+## 前提条件
+- 実行環境：Node.js 20.x on AWS Lambda
+- 最大実行時間：15分（Lambda制限）
+- メモリ上限：3GB
+- 同時実行数：1000（アカウント制限）
+- タイムゾーン：全てUTC
+- 文字コード：UTF-8のみ
+```
+
+プロジェクト開始時や、プロジェクトの前提が変わった際は`/project-inject`コマンドを使い、プロジェクトのコンテキストをルールとして明文化しましょう。
+
+### 8. 重要度順に記述を配置する
+
+LLMは冒頭の情報により注意を払います。最重要ルールを先頭に、例外的なケースは末尾に配置します。
+
+```markdown
+# APIルール
+
+## 最重要原則（必ず守る）
+1. 全APIはJWT認証必須
+2. レート制限：100req/分
+3. タイムアウト：30秒
+
+## 標準仕様
+- メソッド：REST原則に従う
+- ボディ：JSON形式
+- 文字コード：UTF-8
+
+## 例外ケース（特殊な場合のみ）
+- ファイルアップロード時のみ multipart/form-data 許可
+- WebSocket接続は /ws エンドポイントのみ
+```
+
+### 9. スコープ境界を明確にする
+
+何を扱い、何を扱わないかを明示することで、不要な処理や誤解を防ぎます。
+
+```markdown
+## このルールの適用範囲
+
+### 対象
+- REST API全般
+- GraphQLエンドポイント
+- WebSocket通信
+
+### 対象外
+- 静的ファイル配信
+- ヘルスチェックエンドポイント（/health）
+- メトリクスエンドポイント（/metrics）
+```
+
+## 参考：効率的なルール記述
+
+`docs/rules`配下に、これらの原則を意識したルールファイルが存在します。
+それぞれ重複が無く、単一責務で、最小限の記述を心がけて作成しているので、ルールを追加・新設する際の参考にしてください。
+
+### 各ルールファイルと適用原則の対応
+
+| ルールファイル | 主な内容 | 適用されている原則の例 |
+|------------|---------|-------------------|
+| **typescript.md** | TypeScriptコード作成・修正・リファクタリング、モダンな型機能活用 | **原則2**: 表記統一（any型完全禁止など用語を統一）<br>**原則5**: 測定可能な基準（フィールド数20個まで、ネスト深さ3階層まで） |
+| **typescript-testing.md** | テスト作成、品質チェック、開発ステップ | **原則5**: 測定可能な基準（カバレッジ70%以上）<br>**原則8**: 重要度順の配置（品質要件を冒頭に配置） |
+| **ai-development-guide.md** | 技術的判断基準、アンチパターン検出、ベストプラクティス | **原則6**: NGパターンを推奨形式で示す（アンチパターン集）<br>**原則3**: 重複排除（Rule of Threeによる共通化判断） |
+| **technical-spec.md** | 技術設計、環境設定、ドキュメント作成プロセス | **原則4**: 責務の集約（技術設計関連を1ファイルに）<br>**原則7**: 暗黙の前提を言語化（セキュリティルール明文化） |
+| **project-context.md** | プロジェクト固有情報、実装原則 | **原則7**: 暗黙の前提を言語化（プロジェクト特性の明文化）<br>**原則1**: 最小記述で最大精度（簡潔な箇条書き形式） |
+| **documentation-criteria.md** | 規模判定、ドキュメント作成基準 | **原則5**: 測定可能な基準（作成判定マトリクス）<br>**原則9**: スコープ境界を明確化（含むもの/含まないものを明記） |
+| **implementation-approach.md** | 実装戦略選択、タスク分解、大規模変更計画 | **原則8**: 重要度順の配置（Phase順の構成）<br>**原則6**: NGパターンを推奨形式で示す（リスク分析） |
+
+これらのファイル全体で9つの原則すべてが実践されており、実際のルール作成時の参考になります。
+
+## トラブルシューティング
+
+### 問題：ルールが長すぎてコンテキストを圧迫
+
+**対策**
+1. 重複を探して削除
+2. 例を最小限に絞る
+3. 参照形式を活用
+4. 優先度の低いルールを別ファイルへ
+
+### 問題：生成結果が一貫しない
+
+**対策**
+1. 用語・表記を統一
+2. 判断基準を数値化
+3. 優先順位を明確化
+4. 矛盾するルールを排除
+
+### 問題：重要なルールが守られない
+
+**対策**
+1. ファイル冒頭に移動
+2. 【必須】【重要】タグを付与
+3. 具体例を1つ追加
+4. 否定形を肯定形に変換
+
+## まとめ
+
+効果的なルールはLLMの生成を安定させます。9つの原則を意識し、継続的に最適化することでLLMの能力を最大限に引き出すことができます。定期的な実装結果の振り返りと改善を繰り返し、プロジェクトに最適なルールセットを構築していきましょう。