docs-review

docs-review

汎用的なドキュメント監査ツールです。docs/ 内の各 Markdown ファイルを読み込み、ファイルパス、フラグ名、コマンド構文、状態名、設定例をスキャンして、どのソースコードについて記述しているかを特定します。その後、実際のソースファイルと照合します。ドキュメントの記述とコードの動作に食い違いがあれば、ファイル名と行番号を根拠として報告します。

使用するタイミング

• 定期的に（週次の cron）実行して、コード変更にドキュメントが追いついていない箇所を検出します
• リリース前に実行して、現在のコードベースに対してドキュメントが正確か確認します
• コマンド、設定スキーマ、状態機械をリファクタリングした後
• docs/ が存在しない場合はスキップし、メモを出力して正常終了します

使用しないタイミング

• 検証可能なソースの記述がない、純粋に説明的なセクション（歴史、理念、根拠）
• 所有していない外部 API のドキュメント。ソースを grep できません
• 書式やスタイルのレビュー。対象となるのは意味上の不一致のみです

実行方法

/docs-review
/docs-review --since 2026-04-01
/docs-review --output reports/docs-drift.md

フラグ	効果
(なし)	すべての docs/*.md ファイルをレビューします
--since <date>	<date> 以降に変更されたドキュメントファイルに絞り込みます（git log --since）
--output <path>	標準出力に加えて、結果をファイルに書き込みます

---

ワークフロー

ステップ 1：ドキュメントを検出する

ls docs/*.md 2>/dev/null || echo "No docs/ directory found"

docs/ ディレクトリが存在しない場合は、正常終了します。

No docs/ directory found — nothing to review.
Exit 0.

--since <date> が指定された場合は、ファイル一覧を絞り込みます。

git log --since="<date>" --name-only --pretty=format: -- docs/*.md | sort -u | grep '\.md$'

何も返されなかった場合は、正常終了します。

No docs files modified since <date> — nothing to review.
Exit 0.

ステップ 2：各ドキュメントファイルから検証可能な記述を抽出する

各ドキュメントを読み、ソースコードと照合できる記述を抽出します。

記述の種類	確認する内容	例
コマンドフラグ	--flag-name のパターン	--group-id、--not-before
状態名／遷移	state/ → state/ または引用符で囲まれた状態文字列	pending/ → running/ → done/
設定キー	設定に関する文脈でバッククォートで囲まれたキー名	`max_concurrent`、`not_before`
ファイルパス	「X にあります」「X を参照」などとして言及されているパス	dispatch.sh、executor.sh
終了コード	「N で終了する」または「N を返す」	exit 0、exit 1
実行例	コードブロック内のコマンド例	./dispatch.sh --agent lexgo

明らかに検証できないセクション（導入文、動機、設計上の根拠、今後の計画）はスキップします。

ステップ 3：各記述をソースと照合する

コマンドフラグ — シェルスクリプトとコードファイルを検索します。

grep -rn "\-\-flag-name" --include="*.sh" --include="*.mjs" --include="*.js" --include="*.py" --include="*.ts" .

一致するものがない場合は、不一致の候補とします。報告する前に、フラグが本当に存在しないことを確認してください。

状態名 — executor／dispatcher スクリプトで状態文字列を検索します。

grep -rn "pending\|running\|done\|failed" --include="*.sh" --include="*.js" --include="*.py" .

ドキュメントに記載された遷移順序と、コードが強制する順序を照合します。

設定キー — 該当する設定ファイルと、それを読み取るコードを grep します。

grep -rn "max_concurrent\|not_before" --include="*.sh" --include="*.yml" --include="*.json" --include="*.js" .

ファイルパス — 存在することを確認します。

[ -f "path/to/file" ] && echo "EXISTS" || echo "MISSING"

ディレクトリの場合：

[ -d "path/to/dir" ] && echo "EXISTS" || echo "MISSING"

終了コード — 該当するスクリプトで実際の終了呼び出しを grep します。

grep -n "exit [0-9]" script.sh

実行例 — バイナリ／スクリプトが存在すること、および例で使われているフラグが実在することを確認します。

[ -x "./dispatch.sh" ] && echo "executable exists" || echo "MISSING"
grep -n "\-\-agent" dispatch.sh

ステップ 4：結果を整形する

見つかった不一致項目ごとに：

DRIFT: docs/dispatch.md:42 claims "--context" flag exists
  Source check: grep "--context" *.sh → not found
  Evidence: no match in dispatch.sh, executor.sh, or any .sh file

検証済みの記述ごとに：

OK: docs/dispatch.md:15 "--group-id" → dispatch.sh:47 (confirmed)

スキップした記述（検証不可能）ごとに：

SKIP: docs/overview.md:1-10 — intro prose, no verifiable source claims

ステップ 5：要約

すべてのファイルの処理後、次を出力します。

=== docs-review summary ===
Docs reviewed: N files
Claims checked: M
  OK:    X verified
  DRIFT: Y items
  SKIP:  Z non-verifiable

Drift items:
  - docs/dispatch.md:42 — "--context" flag not found in source
  - docs/executor.md:18 — state "queued" not found; code uses "pending"

Exit 0 if no drift found, exit 1 if any drift items exist.

--output <path> が指定された場合は、結果全体（OK／DRIFT／SKIP の各行と要約）をそのファイルに書き込みます。

---

実施するチェック

標準の6つのチェックをすべて適用します。

チェック	grep する対象	確認する場所
フラグの整合性	ドキュメント内の --flag-name パターン	*.sh、*.js、*.py、*.ts
状態の整合性	状態文字列と遷移順序	executor、dispatcher スクリプト
設定キーの整合性	設定キー名	設定ファイル、それらを読み取るスクリプト
リンクの有効性	内部リンク [text](./path) または [text](path.md)	ファイルシステム上で解決
パスの存在確認	実在する場所として記載されたパス	[ -f path ] または [ -d path ]
終了コードの正確性	「exits N」または「returns N」	grep -n "exit [0-9]" script

リンクの有効性チェック — すべての内部 Markdown リンクを抽出して検証します。

# Extract internal links (not http/https)
grep -oP '\[.*?\]\(\K[^)]+(?=\))' docs/file.md | grep -v '^https\?://' | while read link; do
  [ -f "$link" ] || [ -d "$link" ] && echo "OK: $link" || echo "DRIFT: broken link → $link"
done

---

アンチパターン

次のことはしないでください。

• ドリフトを捏造する — grep／read で実際に検証した内容だけを報告してください。grep で結果が見つかっても、該当する主張を正確に確認できない場合は、DRIFT ではなく SKIP としてください。
• 正しく見えるドキュメントをスキップする — すべてのドキュメントをチェックしてください。直感は根拠になりません。
• 書式を理由に失敗と判定する — インデントの誤りや、正しい内容の表現の違いはドリフトではありません。
• スタイル上の問題を報告する — 「この例はもっと明確にできる」はドリフトではありません。
• 外部 API のドキュメントをチェックする — ドキュメントがサードパーティ API を説明している場合は、スキップしてください。
• grep を過剰に使う — 部分文字列ではなく、正確なフラグ名に一致させてください。--group は --group-id に一致させてはいけません。

---

チームの Cron への追加

docs-review をスケジュールに従って自動実行するには：

# In crew.yml, under the team's cron section:
cron:
  - schedule: "0 6 * * 1"  # Weekly Monday 6am UTC
    task: "Run docs-review: check docs/ for drift against code"

ドキュメントが活発に変更されているリポジトリでは、毎日のスケジュールを使用してください。

cron:
  - schedule: "0 7 * * *"  # Daily 7am UTC
    task: "Run docs-review --since yesterday: check docs/ for overnight drift"

---

終了コード

終了コード	意味
0	ドリフトが見つからない（またはレビュー対象のドキュメントがない）
1	ドリフト項目が1つ以上見つかった