コンテンツにスキップ
pentaglyph

pentaglyph を Claude Code で使う

このガイドが解く問題: Claude Code がインストールされていて、プロジェクトは pentaglyph init … --ai=claude で scaffold 済み。Claude に「docs をどこに置くか推測する」のではなく「実際にキットを 使わせる」にはどうすればよいか?

これは how-to であってチュートリアルではありません。pentaglyph init を 1 度走らせた前提で書いてあります。まだなら先に getting-started チュートリアル を。

TL;DR

Section titled “TL;DR”
  1. --ai=claude で初期化。これで .claude/rules/documentation.md が auto-load ルールとしてインストールされる
  2. セッションごとに 1 回、Claude が docs/AI_INSTRUCTIONS.md を読んだことを確認
  3. 定常 4 作業（doc 執筆・diff 監査・PR レビュー・ADR supersede）には プロンプトクックブック の 4 プロンプト を使う
  4. Claude がしくじったら、記憶ではなく docs/WORKFLOW.md を引用して指摘する

1. auto-load ルールが入っているか確認

Section titled “1. auto-load ルールが入っているか確認”

pentaglyph init … --ai=claude で次が作られているはず:

.claude/rules/documentation.md

このファイルは Claude Code に「docs/** を触ったときは、先に docs/AI_INSTRUCTIONS.md と docs/WORKFLOW.md を読め」と指示する短いポインタです。Claude Code は working directory が一致するときに自動で load します。

確認:

Terminal window
cat .claude/rules/documentation.md | head -20

ファイルがなければ --force で再実行:

Terminal window
bunx --bun @uyuutosa/pentaglyph init . --profile=standard --ai=claude --force

なぜこれが重要か: auto-load ルールがないと、Claude は docs/ を汎用 Markdown ディレクトリとして扱い、独自レイアウトを発明し始めます。このルールこそが pentaglyph を「AI-friendly」ではなく「AI-native」たらしめている部品です。

2. セッションの正しい開始

Section titled “2. セッションの正しい開始”

ドキュメント作業を含む新規セッションの最初の 1 メッセージは、Claude を pentaglyph の 2 ソースファイルにアンカーさせるべきです:

「docs/AI_INSTRUCTIONS.md と docs/WORKFLOW.md を読んで。今後 docs/ 配下を作成・変更するときは、そのプロトコルに従って」

これを言うのは セッションにつき 1 回 だけ。一度 Claude のコンテキストにこの 2 ファイルが入れば、auto-load ルールが残りの会話の間スコープに留めてくれます。

このステップを飛ばしても、Claude は auto-load ルールだけからルールを推論する かもしれません が、最初にフルソースを読ませた方が品質は明らかに高いです。

3. 定常 4 作業

Section titled “3. 定常 4 作業”

Claude とのドキュメントやり取りはほぼ 4 作業のどれかです。それぞれ プロンプトクックブック にテンプレがあります。下では 何を期待すべきか を示します。

3.1 新規 doc を書く

Section titled “3.1 新規 doc を書く”

あなた: 「OAuth を実装するところ。PRD を書いてから、OAuth をセッションクッキーより選んだ ADR、それからモジュール詳細設計を書いて。配置とテンプレートは pentaglyph ルールで」

Claude は:

  1. Template 2、5、3 を読む
  2. 出力を docs/arc42/03-context-and-scope/prds/oauth.md、docs/arc42/09-decisions/NNNN-adopt-oauth.md、docs/detailed-design/auth.md（あるいは WORKFLOW.md が解決する等価パス）に配置
  3. 3 ファイルを相互リンク

Claude が docs/specs/ や発明した場所に置いた場合、止めて引用: 「WORKFLOW.md §1 には PRD は arc42/03-context-and-scope/prds/ の下と書いてある。動かして」

3.2 コード diff を監査する

Section titled “3.2 コード diff を監査する”

変更を stage したあと:

あなた: 「私の staged diff を見て。この PR は pentaglyph の code change → doc change ルールを満たしてる? 漏れている doc 更新をリスト、WORKFLOW.md §2 を引用」

Claude は:

  1. git diff --cached を inspect
  2. §2 のマッピング表をたどる
  3. PR を承認、あるいは漏れをリスト（例: 「src/auth/handler.ts を変えたけど docs/detailed-design/auth.md §3 endpoints を更新してない」）

これがキット全体で最もレバレッジの高いプロンプトです。全 PR の前に実行を。

3.3 PR をレビューする

Section titled “3.3 PR をレビューする”

オープンな PR（自分のものでも他人のものでも）に対して:

あなた: 「feature/oauth を pentaglyph ルールに照らしてチェックして。テンプレートは尊重されてる? Accepted ADR は触られてない? front-matter は valid? ADR なしでコードに暗黙の判断が埋め込まれてない?」

Claude がフラグする項目:

  • Accepted ADR 本文への編集（禁止 ―― supersede すべき）
  • durable docs での front-matter 欠落
  • ADR に値する、コードに埋め込まれた暗黙の判断
  • 実際のコード変更と乖離した doc 更新

3.4 ADR を supersede する

Section titled “3.4 ADR を supersede する”

あなた: 「ADR-0007 は SQLite を使うと書いてある。PostgreSQL に migrate する。0007 を supersede する新 ADR を書いて、0007 の front-matter を Superseded by NNNN に更新して。0007 の本文は編集しないで」

Claude は:

  1. 次の番号を選ぶ（例: 0024）
  2. 新ファイルの metadata に Supersedes: 0007 をセット
  3. 0007.md の front-matter のみ更新 ―― 本文は無傷で残す

「本文は編集しないで」が critical で、Claude は初回によく忘れます。最初は監視を。

4. Claude がしくじったとき

Section titled “4. Claude がしくじったとき”

不正確な Claude 出力の約 80% は次の 2 つの failure mode です:

Failure A ― 新ディレクトリを発明する。WORKFLOW.md にリストされていない docs/specs/ や docs/architecture/ に doc を置く。修正:

「そのパスは WORKFLOW.md §1 にない。決定木を読み直して、リストされた場所からだけ選んで」

Failure B ― 新テンプレートを発明する。docs/templates/ からコピーせずに doc を書く。結果は通常 front-matter 欠落かカスタムヘディング順。修正:

「docs/templates/N_<name>.md から始めて。新しい形を発明しない」

2 回続けて両方失敗するなら、auto-load ルールが拾われていない可能性大。.claude/rules/documentation.md とエディタ設定を再確認。

5. やってはいけないこと

Section titled “5. やってはいけないこと”
  • セッションをまたいで pentaglyph ルールを「覚えておいて」と Claude に頼ま ない ―― セッションは独立しています。auto-load ルール + §2 の 1 行プロンプトが記憶の全てです
  • WORKFLOW.md の中身をプロンプトに貼ら ない ―― Claude はファイルを直接読めます。貼ると drift します
  • Accepted ADR の本文を Claude に編集 させない。本文が編集されたらファイルの audit-trail 価値は消えます。PR レビューで捕まえる
  • 「今回だけ」と auto-load ルールを 切らない。常に on であることが要点です

6. エディタバリアント

Section titled “6. エディタバリアント”

--ai=cursor と --ai=copilot は等価なルールをそれぞれ .cursor/rules/docs.md と .github/copilot-instructions.md にインストールします。挙動は同一。ファイルパスだけが違います。フルマトリクスは reference/ai-targets.md を参照。

エディタフックを持たないエージェント（--ai=generic）には、ユーザーに各セッション開始時にこの 1 行を貼ってもらいます:

「docs/AI_INSTRUCTIONS.md を読んで、docs/ を触るときは pentaglyph ルールに従って」

関連

Section titled “関連”