プロンプトクックブック

このガイドが解く問題: pentaglyph の価値は AI エージェントがキットを使うときに現れる。しかし プロンプトの形 が重要。本クックブックは現場で効くプロンプトを集約し、見た目は妥当でもプロトコルを壊すものをフラグします。

すべてのプロンプトは以下を前提とします:

リポジトリが pentaglyph init … --ai=<your-agent> で初期化済み
エージェントがセッション中に 1 回 docs/AI_INSTRUCTIONS.md と docs/WORKFLOW.md を読むよう指示済み

どちらも未了なら、先に use-with-claude-code.md §1–§2 から。

プロンプトは Claude Code 向けに書かれていますが、Cursor / Copilot も同じく動きます。チャットパネルに貼るだけです。

クイックインデックス

作業	プロンプト
セッションをブートストラップ	§1
PRD を書く	§2
デザインから ADR 候補を抽出	§3
Module Detailed Design を新規に書く	§4
既存コードから Module DD を逆生成	§5
抜けている doc 更新を diff から監査	§6
PR self-review	§7
ADR を supersede	§8
レガシー doc を移行	§9
古くなった doc を監査	§10
アンチパターン	§11

1. セッションをブートストラップ

doc 作業を始めるときに、ちょうど 1 回送ります:

docs/AI_INSTRUCTIONS.md と docs/WORKFLOW.md を端から端まで読んで。今後、docs/ 配下を作成・変更するときは、そのプロトコルに従って。ルールが明示的に許可していない場所にファイルを置きそうになったら、止まって私に確認して。

セッションごとに 1 回でよい。次の 20 プロンプトをアンカーします。

2. 新機能の PRD を書く

次の機能について、pentaglyph ルールに従って PRD が必要:

機能: <1 行説明>

背景: <文脈 2〜3 文>

Template 2 を使って。arc42/03-context-and-scope/prds/ 配下に kebab-case ファイル名で配置。front-matter の status を Draft に。<placeholder> を <実際のプロジェクト名> で埋めて。書き終えたら、私の情報から答えられなかった open questions を列挙して。

末尾の「open questions を列挙」が essential です ―― これがないと Claude はそれっぽい値を発明して埋め、数週間後まで気づかれません。

3. デザインから ADR 候補を抽出

次の <feature> のデザイン案を渡す。このデザインが含意するアーキテクチャ判断のうち、別々の ADR として記録すべきものを各々特定して。それぞれについて 1 文サマリ・名前付き代替案・Template 5（MADR v3.0）で Status: Proposed の ADR ドラフトを書いて。各ドラフトを arc42/09-decisions/ に次の連番 NNNN プレフィックスで配置。

デザイン: <デザインノートを貼る>

決定を bundle しないで。各 ADR は 1 決定。候補が 5 件を超える場合は、上位 5 件をフラグして、残りを起草するか聞いて。

「bundle するな」ルールが重要なのは、最もよくある ADR の失敗が「Feature X のアーキテクチャ」というタイトルで 4 つの別決定を含む単一 ADR だからです。それは ADR ではなく、小さなデザイン doc です。

4. Module Detailed Design を新規に書く

今から実装する <module> モジュールの Module Detailed Design を書いて。

PRD: docs/arc42/03-context-and-scope/prds/<feature>.md（先に読んで） 関連 ADR: <ADR 番号リスト>

Template 3 を使う。docs/detailed-design/<module>.md に配置。docs/arc42/05-building-blocks/ の下に子リンクを追加。Status Draft。末尾に open questions を列挙。

5. 既存コードから Module DD を逆生成

既存プロジェクトに pentaglyph を導入するとき:

src/<module>/ 配下のソースを読んで。現在の実装を記述する Module Detailed Design（Template 3）を書く ―― 望ましい未来の姿ではなく。docs/detailed-design/<module>.md に配置。意図を推測せざるを得なかったセクションには [INFERRED — 確認お願いします] をマークして。

design rationale を発明しないで。構造選択の理由がコードから見えないなら空欄にして Open Question に追加して。

[INFERRED — 確認お願いします] マーカーは、逆生成 doc が接触後すぐ腐るのを防ぐ規律です。

6. 抜けている doc 更新を diff から監査

これは クックブック中で最もレバレッジの高いプロンプト です。PR ごとに実行。

私の staged diff（git diff --cached）を見て。docs/WORKFLOW.md §2（Code change → doc update mapping 表）を 1 行ずつ歩いて、私の diff に該当する各行について、対応する doc がこの PR で更新されているか教えて。

報告フォーマット:

✅ <行> — <file> でカバー済

❌ <行> — <expected file> への更新が漏れている

⚠️ <行> — 部分カバー。ギャップは <具体的なギャップ>

まだ漏れの更新を生成しないで。ギャップリストだけ作って。

「まだ生成しないで」の行が、Claude が 400 行の doc を書いてレビュー地獄になるのを防ぎます。先にギャップリストをもらい、それから 1 件ずつ更新を頼むこと。

7. PR self-review

§6 をクリアしたあと:

この PR を pentaglyph ルールに照らして self-review して。特に確認:

Accepted ADR 本文への編集は 0 件。front-matter のみの編集なら OK

新 durable docs はすべて front-matter（status、owner、last-reviewed）を持つ

新 volatile docs はすべて YYYY-MM-DD_ プレフィックスを持つ

発明されたディレクトリ 0 件。すべての新ファイルが docs/WORKFLOW.md §1 に名指された場所の下にある

ADR なしでコードに埋め込まれた暗黙のアーキテクチャ判断 0 件

PR タイトル / 説明は実装詳細ではなくユーザー向け変更を要約している

違反はファイルと行で報告。auto-fix しないで。

8. ADR を supersede

ADR-<NNNN> (<title>) を supersede したい。新決定は <1 文説明>。

次の連番 NNNN プレフィックスを選ぶ

Template 5 で新 ADR を書く。front-matter に Supersedes: <NNNN> を含める

<NNNN>.md の front-matter のみ 更新して Superseded by: <new NNNN> を追加、Status: Accepted → Status: Superseded に変更

<NNNN>.md の本文を編集しない。本文は歴史記録

書き終えたら、両ファイルの git diff サマリを見せて。

「本文を編集しない」ルールが Claude が最もよく破るところ。「git diff サマリを見せて」の行が、over-reach を露呈させます。

9. レガシー doc を pentaglyph レイアウトに移行

レガシーファイル <path> に pentaglyph レイアウトの下に re-home すべき内容が含まれている。読んで:

durable な claim（システム構造・決定・契約）を各々特定

それぞれについて、どの pentaglyph ファイルに属するか決定 ―― docs/WORKFLOW.md §1 を引用して justify

正しいテンプレートで新ファイルを生成

移行した内容は <path> から消し、新しい場所への 1 行リンクに置き換える

揮発性の内容（ステータス更新・日付付き TODO 等）は破棄 ―― それらは移行されず、忘れ去られるべき。

最後の文が critical。レガシー doc は通常 30% が durable、70% が日付付きクラフトです。クラフトを移行すると新構造が汚染されます。

10. 古くなった doc を監査

docs/<path> を読んで。その主張を <relevant src path> 配下の現在のコードと比較。次のいずれかに分類:

🔴 Wrong — 現在のコードと矛盾

🟡 Stale — かつて真実だったがコードが先に進んだ

🟢 Still accurate

セクション別にグループ化。doc を書き直さないで ―― 監査だけ作って。何を更新するかは私が決める。

定期的に（月次が妥当）リポジトリで最も参照される 5 docs に対して実行。多くの doc は不可視に腐ります。このプロンプトが腐敗を可視化します。

11. アンチパターン ― 見た目は妥当でもプロトコルを壊すプロンプト

避けるべきもの:

アンチプロンプト	なぜプロトコルを壊すか
「この機能の docs を全部書いて」	PRD / ADR / Module DD を 1 コールに混ぜる。それぞれ別の決定。順次頼むこと
「`docs/` をもっと clean に再編成して」	構造は cleanliness のためではなく placement determinism のため。エージェントの感覚で再編成すると determinism が壊れる
「X に言及する全 doc を更新して」	大量盲目更新が audit trail を腐らせる。 1 つの canonical doc を更新、それ以外はそこへのリンクであるべき
「コードベース全体の docs を生成して」	高ボリューム・低シグナル。結果はコードのように読める ―― それこそ pentaglyph が付加価値を生まない領域
「ADR をもっと読みやすいフォーマットに変換して」	MADR v3.0 がフォーマット。交渉の余地なし
「この 3 ADR を 1 つに結合して」	1 ファイル 1 決定の性質を失う。`git blame` 考古学に必要
「このクイック fix なら front-matter スキップしていい」	front-matter こそ doc を machine-readable にする。クイック fix こそ落ちやすい

役立つ習慣

最もよく使うプロンプトをエディタにテンプレートとして保存しましょう（Claude Code → .claude/commands/、Cursor → snippets）。ほぼ全プロジェクトで保存する価値がある 4 つ:

§1 — bootstrap
§6 — diff audit
§7 — PR self-review
§10 — stale audit

この 4 つで pentaglyph プロジェクトの定常ドキュメント作業の約 90% をカバーします。