doc

ドキュメントスキル

設定駆動型のドキュメントのひな形作成です。設定はスキル内の config/defaults.yaml にあり、リポジトリのルートにファイルを置く必要はありません。

コマンド

コマンド	実行する内容
start <name>	bash ${AGENTS_SKILLS_DIR}/scripts/start.sh "<name>"
expt <name>	bash ${AGENTS_SKILLS_DIR}/scripts/expt.sh "<name>"
plan <index> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/plan.sh <index> "<title>"
finding <index> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/finding.sh <index> "<title>"
ckpt <index> <description>	bash ${AGENTS_SKILLS_DIR}/scripts/ckpt.sh <index> "<description>"
research <index> <topic>	bash ${AGENTS_SKILLS_DIR}/scripts/research.sh <index> "<topic>"
review <index> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/review.sh <index> "<title>"
learn <index> <domain> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/learn.sh <index> "<domain>" "<title>"
list	bash ${AGENTS_SKILLS_DIR}/scripts/list.sh
status <index>	bash ${AGENTS_SKILLS_DIR}/scripts/status.sh <index>
resume <index>	bash ${AGENTS_SKILLS_DIR}/scripts/resume.sh <index>

start = docs/ のひな形を作成 ＋ 実験を作成します。 新しい作業を始めるときに使用します。 expt = 実験のみを作成します。 docs/ がすでに存在する場合に使用します。

エージェントの動作 — 必ずお読みください

会話ごとに、アクティブな実験を追跡する責任があります。 ユーザーが実験を作成したとき、または実験に言及したときは、そのインデックスを記憶してください。スクリプトはステートレスで並列実行に対応しているため、すべてのスクリプト呼び出しにインデックスを渡してください。

各コマンドを使うタイミング

ユーザーの発言...	実行すること...
「Xを調査しましょう」／新しい作業を開始する	/doc start "<name>" — 返されたインデックスを記憶します
「これを計画して」／「どのように進めるべき？」	この作業を扱う最近の計画がなければ、/doc plan <idx> "<title>" を実行してから計画の内容を書きます。最近の計画を更新・改善する場合は、同じ計画ファイルを編集します。
ユーザーが計画モードに入る	停止してください。 .claude/plan.md は使用しないでください。更新の場合は既存の該当する計画を使用し、それ以外の場合は /doc plan <idx> "<title>" を実行して、そこに記述します。計画は実験フォルダーに保存し、一時ストレージには保存しません。
重要なことを発見した	/doc finding <idx> "<title>" を実行してから、発見内容を書きます
会話を終える／コンテキストを切り替える	/doc ckpt <idx> "<short-label>" を実行します。ラベルは短く（2～5語）します。その後、Mermaid 図を含む「Complete Agent Handoff」の内容をファイルに書きます。 指示されなくても自動的に行ってください。
「Xを調査して」／「Yを調べて」	/doc research <idx> "<topic>" を実行します。プロンプトを書き、調査を行い、結果を書きます
「Xをレビューして」／「この出力を確認して」	/doc review <idx> "<title>" を実行してから、判定を含むレビュー内容を書きます
「これを覚えておいて」／「重要な学び」	/doc learn <idx> <domain> "<title>" を実行して、要点をまとめた知見を書きます
「実験19を続けて」／「再開して」	/doc resume <idx> を実行します — メタデータ、最新の計画、直近5件のチェックポイントを読み込みます。この会話でアクティブな実験として設定します。
「どんな実験がある？」	/doc list
「実験19の状態は？」	/doc status <idx>

コンテキストの解決（ユーザーがインデックスを指定しない場合）

1. この会話で作成または再開した実験を使います
2. ユーザーが名前または番号を指定した実験を使います
3. ユーザーの依頼が明らかに関連する実験を使います
4. 曖昧な場合は「どの実験ですか？」と尋ねてから、選択肢を示すために /doc list を実行します

コンテキストはあなたが判断します。スクリプトが受け取るのは番号だけです。

自動動作

• 会話の終了時、コンテキストの切り替え前、マイルストーンの達成後など、自然な区切りで自動的にチェックポイントを作成します。依頼されるまで待たないでください。
• 計画は experiments に保存します。 .claude/plan.md や一時ストレージには絶対に計画を書かないでください。
• ユーザーが成果物を修正、改良、拡張している場合は、同じ最新ファイルを更新します。最近の作業ドキュメントとは、この会話で作成または再開した計画／調査結果／レビュー／リサーチファイル、または /doc resume で再開した最新の関連ファイルです。そのファイルを直接編集してください。
• トピック、意思決定の段階、マイルストーン、成果物の目的が変わった場合は、新しい番号付きファイルを作成します。つまり、別個の作業には新しい番号付きファイルを作成してください。たとえば、以前の計画が無効になった後の新しい実装方針、個別の調査結果、新しいレビュー、新しいリサーチの問い、チェックポイントのスナップショットなどです。
• 判断はエージェントが行います。 更新か新規作成かが不明な場合は、最近の作業ドキュメントが現在の作業を表しているなら、そちらの編集を優先します。異なるバージョンの履歴を残す必要がある場合にのみ、新規作成してください。
• 再開してから続行します。 既存の experiment に取り組み直す場合は、まず /doc resume を実行して、継続性を保つための Last 5 checkpoints を含むコンテキストを読み込みます。

チェックポイントの内容 — 必須

ckpt コマンドの引数は、チェックポイントの内容ではなく、短いラベル（2～5語）です。スクリプトがファイルを作成した後、次の構成で本文を必ず記入してください。

```mermaid
graph TD
    A[Starting state] --> B[What was done]
    B --> C[Current state]
    C --> D[Next steps]
```

## What
What was accomplished. Bullet points, brief.

## Key Takeaways
Surprising findings, confirmed/rejected hypotheses, numbers that matter.

## Current State
Exact repo state: branch/commit if relevant, changed files, active experiment index, active plan/review/research files, commands already run, test results.

## Issues
Blockers hit, workarounds used, unresolved problems. Include exact error messages if relevant.

## Decisions
Key choices made and why. What was considered and rejected.

## Inferred Priority
Your inferred next priority based on conversation and repo state. Mark as "inferred" unless user stated it explicitly.

## Next
Concrete next steps with enough detail that a fresh agent can continue without reading chat history.
Include file paths, command examples, what to watch out for, and first command to run next.

チェックポイントは完全なエージェント引き継ぎ資料です。Mermaid 図に加え、チャット履歴を読んだり、何が起きたのかを尋ねたりしなくても、新しいエージェントが作業を続けられるだけの詳細を含めてください。簡潔でありながら、ファイルパス、主要な数値、決定事項、現在の状態、優先事項、うまくいったこと、うまくいかなかったこと、次に実行する正確なコマンドを網羅してください。

説明引数に内容を詰め込まないでください。 引数は短く保ちます。例：/doc ckpt 7 "v1 analysis complete"。その後、ファイルを編集してください。

Experiment の構成

experiments/NNN-{name}/
├── .meta.json          auto-updated by scripts
├── plans/              multiple plans, numbered
├── findings/           multiple findings, numbered  
├── checkpoints/        progress snapshots, numbered
├── review/             structured reviews, numbered
└── research/           prompt + response pairs, numbered

セットアップ

/doc start my-investigation — これだけです。docs/ を準備し、最初の experiment を作成します。

フォルダー構成や命名をカスタマイズするには、skill 内の config/defaults.yaml を編集してください。

ルール

1. スクリプトが作成するのは空のテンプレート（frontmatter + 見出し）だけです。スクリプトの実行後、ファイルに実際の内容を記入してください。 スクリプトの実行を作業完了と見なさないでください。
2. ファイルの作成には必ずスクリプトを使用してください。 experiment のディレクトリを手動で作成したり、.meta.json を編集したりしないでください。
3. インデックスは番号のみです。 23 を使います。023 や 023-docs-and-structs ではありません。
4. 自動コミットはありません。 スクリプトはファイルを準備するだけです。コミットするタイミングは、あなたまたはユーザーが決めます。
5. 計画は experiments に保存します。 .claude/plan.md には絶対に保存しないでください。これは譲れないルールです。
6. 最近の作業ドキュメントは編集可能ですが、履歴ドキュメントは追記専用です。 現在の作業の修正には、同じ最新ファイルを更新してください。トピック、マイルストーン、決定事項、スナップショットが異なる場合は、新しい番号付きファイルを作成してください。
7. 有効な learnings のドメインは config/defaults.yaml に記載されています。有効でないドメインを指定すると、learn はエラーになります。
8. タイトルは短くしてください。 タイトルはファイル名になります。最大2～5語にして、簡潔かつ具体的にします。"investigation-into-authentication-flow-reliability-issues" ではなく "auth-flow" を使ってください。順序は番号の接頭辞で示されるため、タイトルはトピックがひと目でわかるものであれば十分です。

$ARGUMENTS