document

/document - ドキュメント作成エージェント

ワークフロー

/document {ID}
       ↓
1. Resolve task ID → find task document
2. Read task document + test report (pipeline audit)
3. Run git diff — identify pipeline gaps
4. Create/update feature doc (docs/features/{feature}.md)
5. Create/update user guide if user-facing (docs/guides/{feature}.md)
6. Update CLAUDE.md if structural changes detected
7. Write retrospective → update LEARNINGS.md
8. Move task to "Approved" in TASKS.md
       ↓
┌─── Automation Mode? ───┐
│                        │
▼ Manual                 ▼ Auto
Notify user              Output SIGNAL, exit
Ready for /ship

---

自動モードの動作

タスクドキュメントに Automation: auto がある場合：

≡ SIGNAL
STAGE: document
STATUS: DONE
TASK: {ID}
SUMMARY: Feature doc created
REFERENCE: docs/features/{feature}.md
≡ END

手動モード： /clear を実行してから /ship {ID} を実行します。

---

ステップ 1：ドキュメント作成前のチェックリスト — パイプライン全体の監査

ステップ 1A：一次資料を読む

docs/task/{ID}-{task-name}.md        - What was planned + Implementation Notes from /simplify
docs/testing/{ID}-{task-name}.md     - Test results, failures, retry cycles

ステップ 1B：実際のファイル差分を取得する

git diff --name-only main...HEAD

タスクドキュメントの ## File Changes と照合します。差分に含まれていて、タスクドキュメントには含まれていないものはすべて、/simplify または /test の再試行によって追加されています。これらは記録すべきパイプラインの抜け漏れです。

ステップ 1C：パイプラインの抜け漏れを分類する

差分に含まれているがタスクドキュメントにはないファイル	想定される原因	対応
同じファイルが大幅にリファクタリングされている	/simplify による品質改善	新しい規約が生まれた場合は、パターンの変更を CLAUDE.md に記録する
新しいヘルパー／ユーティリティが切り出された	/simplify による単一責任の修正	再利用可能であれば、CLAUDE.md の Important File Locations に追加する
新しいテストフィクスチャまたはシードファイル	/test のセットアップ	テストパターンが明らかになった場合は、LEARNINGS.md に記録する
再試行で追加のファイルが変更された	/test → /implement の再実行	差異を記録し、CLAUDE.md の更新が必要か確認する
サイクルの途中でマイグレーションファイルが追加された	どのステップでも	必ず CLAUDE.md に追加する — マイグレーションは重要なコンテキスト

コードベースを広範囲に調査しないでください。抜け漏れリストにあるファイル、または正確性の確認に明確に必要なファイルのみを開いてください。

ステップ 1D：/simplify の実装メモを読む

タスクドキュメントの ## Implementation Notes で、次を確認します。

• 「What was built」 — 当初の計画と異なる場合があります
• 「Deviations from plan」 — 中程度または重大な逸脱はドキュメントに反映します
• 「Standards check」 — 修正によって CLAUDE.md に記録する価値のある新しいパターンが導入された可能性があります

ステップ 1E：/test の再試行回数を確認する

docs/testing/{ID}-{task-name}.md で、次を確認します。

• 再試行 0 回 → うまくいった点を LEARNINGS.md に記録する
• 再試行 1 回以上 → 失敗の根本原因は教訓です。必ず LEARNINGS.md に記録する
• 同じ問題で複数回再試行 → CLAUDE.md に「Do Not」の項目を追加する

---

ステップ 2：必要なドキュメントを特定する

変更の種類	必要なドキュメント
新機能	機能ドキュメント + ユーザーガイド
機能強化	既存ドキュメントを更新
バグ修正	トラブルシューティングのセクションを更新
API の変更	API リファレンスを更新
パイプラインの抜け漏れ（simplify/test によるファイル追加）	CLAUDE.md + LEARNINGS.md

---

ステップ 3：ドキュメントの作成

機能ドキュメント： docs/features/{FEATURE}.md — 開発者向けの技術的な実装詳細です。概要、ユーザージャーニー、アーキテクチャ（ファイル構成、スキーマ、API エンドポイント）、主要コンポーネント、技術的な注意事項を含めてください。

ユーザーガイド： docs/guides/{feature}.md — エンドユーザー向けの機能の使い方です。クイックスタート、手順を追った説明、ヒント、FAQ、トラブルシューティングを含めてください。

---

ステップ 4：CLAUDE.md — プロジェクトの生きた知識基盤

読む → 削る → 更新する（この順番で）。ただ追記するだけにしないでください。

項目を追加する基準： 将来のエージェントが、その情報がなければミスをする、発見に時間を浪費する、または決定済みの判断を再検討することになる場合に記録します。

このタスク後に更新する条件：

発生したこと	更新する内容
新しいディレクトリを作成した	Project Structure
ファイルを移動または名前変更した	Important File Locations
データベースのマイグレーションを実行した	Stack セクション、スキーマの注記
新しいパッケージをインストールした	Stack セクション
/simplify が繰り返し発生している違反を見つけた	Do Not
アーキテクチャに関する議論が決着した	Architecture Decisions
規約違反を修正した	Key Conventions
古いパターンを置き換えた	古い項目を削除し、新しい項目を追加する

完全に省略してよい場合： 新しいファイル、ディレクトリ、マイグレーション、ルート、パッケージがない、純粋なロジック修正、文言の変更、またはスタイルの微調整。

省略してはいけない場合： マイグレーションを追加した、新しいディレクトリを作成した、ファイルを移動／改名した、新しい API ルートを追加した、新しい環境変数が必要になった、またはパターンを置き換えた場合。

/implement ですでに記録されているはずです。内容を確認し、抜け漏れを補ってください。

ステップ 5：振り返りと LEARNINGS.md

タスクの振り返り： docs/learnings/{ID}-{task-name}.md

パイプライン全体を対象とし、計画と実際の差異、品質ゲートでの指摘、テストの失敗、下した判断を記録します。次の内容を含めます。

• 計画と実際の差異（計画した内容、コミットした内容、相違点、計画外のファイル）
• /simplify で検出されたこと（指摘され、修正したパターン）
• /test で明らかになったこと（失敗と根本原因）
• 重要な教訓（具体的で実行可能なもの）

LEARNINGS.md（プロジェクトのルート）：最も再利用性の高い知見を抽出し、該当するセクションに追記します。

教訓の発生元	LEARNINGS.md のセクション
/simplify がコーディングパターン違反を検出した	避けるべきよくある間違い
/simplify が再利用可能なヘルパーを抽出した	確立されたコーディングパターン
/test が計画にないシステム動作を原因として失敗した	技術スタックの注意点
/test の再試行で統合の不足が明らかになった	避けるべきよくある間違い
差分内に計画外のファイルがあった	技術スタックの注意点 または 確立されたコーディングパターン
パイプライン中にアーキテクチャ上の判断を行った	アーキテクチャと決定事項

LEARNINGS.md の記載ルール：

• 1つの項目には、実行可能な教訓を1つだけ記載します
• その教訓を検出したパイプラインのステップを明記します
• 重要なフレーズを太字にし、1文で説明します
• 重複を避けます。追記する前に確認してください
• LEARNINGS.md がない場合は、次のセクションを含めて作成します：アーキテクチャと決定事項、確立されたコーディングパターン、避けるべきよくある間違い、テストパターン、技術スタックの注意点

---

ドキュメントのチェックリスト

• git diff --name-only main...HEAD を実行し、全ファイルのリストを記録した
• パイプラインの不足を特定し、分類した
• /simplify の実装ノートを読み、相違点を記録した
• /test の再試行回数を確認し、失敗の根本原因を特定した
• 正確なファイルパスを記載した機能ドキュメントを作成／更新した
• ユーザーガイドを作成／更新した（ユーザー向けの場合）
• CLAUDE.md を読み、整理し、更新した（構造上の変更がない場合はスキップ）
• docs/learnings/{ID}-{task-name}.md を作成した
• 重要な教訓を LEARNINGS.md に追記した
• LEARNINGS.md に重複する項目がない
• TASKS.md でタスクを「承認済み」に移動した

---

TASKS.md を更新する

タスクを「承認済み」に移動します。

ID	タスク	タスクドキュメント	機能ドキュメント	テストレポート	承認済み

---

/ship への引き継ぎ

手動モード： 更新したファイルの概要、タスクを「承認済み」に移動したこと、次のステップ /ship {ID} を出力します。 自動モード： SIGNAL を出力して終了します。ルーティングはオーケストレーターが処理します。次のスキルを起動しないでください。