compound-docs

compound-docs

プロセス

単一ファイルアーキテクチャです。症状カテゴリのディレクトリごとに、問題ごとに1つのMarkdownファイルを作成します（例：docs/solutions/performance-issues/n-plus-one-briefs.md）。メタデータにはYAMLフロントマターを使用します。

7ステップのドキュメント作成プロセスに従ってください。詳細については、documentation-process.mdを参照してください。

1. 確認を検出 -- 「うまくいった」「修正できた」などの発言の後に自動で実行します。些細な修正はスキップします。
2. コンテキストを収集 -- モジュール、症状、調査の試み、根本原因、解決策、予防策を抽出します。重要なコンテキストが不足している場合は中断します。
3. 既存のドキュメントを確認 -- docs/solutions/で類似の問題を検索します。見つかった場合は、新しいドキュメントに相互参照を追加する、既存のドキュメントを更新する、またはその他の方法を提案します。
4. ファイル名を生成 -- 形式：[sanitized-symptom]-[module]-[YYYYMMDD].md
5. YAMLを検証 -- 下書きを一時的なMarkdownファイルに保存し、validate-frontmatter.shを実行して検証します。バリデーターにはPython 3とPyYAMLが必要です。依存関係が不足している場合は、検証したと誤って伝えず、不足していることを報告してください。無効な場合は、フロントマターを修正し、検証に合格するまで再実行します。
6. ドキュメントを作成 -- resolution-template.mdを使用して、docs/solutions/[category]/[filename].mdにファイルを作成します。
7. 相互参照を追加 -- 関連する問題へのリンクを追加します。重要なパターン（類似の問題が3件以上）を検出します。

記録の判定条件（ステップ1）： このドキュメントがなくても、今後のエンジニアが最終的なコード、テスト、コメント、CLAUDE.md/AGENTS.md、既存のドキュメントまたはスキルを読めば、同じ間違いを繰り返したり、同じ調査をやり直したりすることがない場合は、記録しないでください。それらのいずれかにすでに教訓が記載されている場合はスキップします。

---

選択メニュー

ドキュメントの作成に成功したら、以下の選択肢をAskUserQuestion（Claude Codeの場合。未ロードの場合はToolSearch select:AskUserQuestionでロード）またはrequest_user_input（Codexの場合）で提示します。どちらも使用できない場合は、チャットで番号付きメニューを提示し、ユーザーの回答を待ちます。

Solution documented

File created:
- docs/solutions/[category]/[filename].md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

回答の処理の詳細については、documentation-process.mdを参照してください。

---

成功基準

• YAMLフロントマターが検証済みである（必須項目がすべてあり、形式が正しい）
• docs/solutions/[category]/[filename].mdにファイルが作成されている
• 列挙値がスキーマと完全に一致している
• 解決策のセクションにコード例が含まれている
• 関連する問題が見つかった場合、相互参照が追加されている
• ユーザーに選択メニューが提示され、アクションが確認されている

---

参考資料

• documentation-process.md - 検証ゲートを含む7ステップの完全なプロセス
• yaml-schema.md - YAMLフロントマターのスキーマと列挙値
• quality-guidelines.md - 品質基準、実行ルール、エラー処理
• example-scenario.md - N+1クエリの修正を記録する完全な手順
• resolution-template.md - ドキュメントファイルのテンプレート
• critical-pattern-template.md - 重要なパターンの記録用テンプレート
• validate-frontmatter.sh - YAMLフロントマターをスキーマに照らして検証
• validate-frontmatter.py - 安全なYAMLパーサーと項目の検証。許可されている場合は、python3 -m pip install PyYAMLで依存関係をインストールします

統合

• 古い学習内容のレビュー（Claude Codeの/ia-compound-refresh） -- docs/solutions/を確認し、古くなった項目をレビューします