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

このガイドが解く問題: 既存のコードベースに ad-hoc な docs（あるいは docs なし）があり、pentaglyph を定着させたい。過去の遡及ドキュメント化に 3 スプリント費やすことなく、どう導入すればよいか?

短い答え: 過去をレトロドキュメント化してはいけない。 これから の変更に対して pentaglyph を導入し、現役で効いている少数のレガシー概念だけを後追いで埋めましょう。本ガイドは、現場で最も成功率の高い段階的導入を辿ります。

TL;DR

pentaglyph init を --profile=minimal で実行
arc42 §1, §3, §5, §9 のみ を埋める。§2/§4/§6/§7/§8/§10/§11/§12 は実際に必要になるまでスキップ
過去の決定の ADR を書いてはいけない。これからの決定に対してのみ ADR を書く。 さらに 「みんなが何度も蒸し返している」load-bearing なレガシー決定 3〜5 件についてのみ後追い記録
既存の ad-hoc docs を pentaglyph レイアウトに移すのは 1 件ずつ、そのファイルに次に触る PR の中で
4〜6 週後に --profile=standard への昇格を評価（detailed-design・api-contract・design-guide・impl-plans・postmortems・reports が追加される）

Phase 0 — やってはいけないこと

段階的プランの前に、導入を殺す アンチパターン を:

アンチパターン	何が壊れるか
スプリントを使って過去の ADR を全部書く	実作業が止まる。誰も読まない。チームが pentaglyph をオーバーヘッドと認識する
初日に `pentaglyph init --profile=full` を走らせる	14 ディレクトリが出現。何を埋めればいいか分からず分析麻痺に
LLM でコードから docs を auto-generate	高ボリューム・低シグナルなテキストが量産され、正本のように見えるがすぐ腐る
「arc42 を埋める」を別の work-item にする	doc 執筆をコード作業から切り離してしまう。これこそ pentaglyph が直すべき失敗
既存の `README.md` を全部 1 PR で pentaglyph レイアウトに移す	レビュー不可能な diff 爆弾

これらをやりかけていたら、止まって本セクションを読み直してください。

Phase 1 — 最小スキャフォールド（初日、約 30 分）

リポジトリのルートで:

bunx --bun @uyuutosa/pentaglyph init . --profile=minimal --ai=claude --name="My App"

--profile=minimal で入るもの:

docs/AI_INSTRUCTIONS.md、docs/WORKFLOW.md、docs/STRATEGY.md、docs/INDEX.md
docs/templates/（執筆形式の集合）
docs/arc42/（§1–§12 のスタブ）
.claude/rules/documentation.md（AI auto-load ルール）

それだけ。detailed-design/・api-contract/・user-manual/ は ―― まだ ―― 入りません。各プロファイルが何を含むかは reference/profiles.md を参照。

なぜ minimal なのか? 大きなプロファイルは「全部埋めたい誘惑」を生みます。空ディレクトリのコストは高い: リポが手入れされていないように見え、新参を混乱させます。空の arc42 スタブは構造自体が情報なので許容できます。空の detailed-design/ は許容できません。

コミット:

git add docs/ .claude/
git commit -m "docs: adopt pentaglyph scaffold (minimal profile)"

これで 1 PR です。コードは何も変えていないので、レビュアは 800 ファイルを読まずに承認できます。

Phase 2 — arc42 の 4 セクションだけ埋める（1 週目）

次の 4 ファイルを開き、 今の現実 を捉える最小限を書きます。理想ではなく事実を書く。

ファイル	中身	長さ
`docs/arc42/01-introduction-and-goals/`	このプロダクトは何をやるか? 誰のためか? 2〜3 個の品質目標は?	1〜2 ページ
`docs/arc42/03-context-and-scope/`	どのシステムと統合しているか? 何がスコープ外か?	1 ページ + C4 System Context 図（あるいは「あとで描く」プレースホルダ）
`docs/arc42/05-building-blocks/`	今この時点で存在するモジュール / サービスは? 1 行説明付きで列挙するだけ	1 表
`docs/arc42/09-decisions/`	今は空でよい。`0000-template.md` の存在だけ確認	0

残りの arc42 セクション ―― 制約（§2）、解決戦略（§4）、Runtime View（§6）、Deployment View（§7）、Crosscutting（§8）、品質要求（§10）、Risks（§11）、Glossary（§12） ―― は、具体的に埋める理由ができるまで待ちます。arc42 標準は部分カバーを明示的に許容しているので、義務感を持たないこと。

Hard rule: システムを 今の状態のまま 描写する。あるセクションで「我々は … する予定」と書きたくなったら、書いている artefact が間違っています。それは impl-plans/（Phase 5+）の仕事です。

Phase 3 — コード変更 → ドキュメント変更の習慣を始める（2 週目以降）

長期的にはこのフェーズだけが本当に重要です。

次に non-trivial な PR を開くときに:

影響を受けるモジュールを特定し、docs/arc42/05-building-blocks/ で引く
building-block エントリがある場合、変更でモジュールの役割が変わっていれば 1 行サマリを更新
変更が public API を追加しているなら、templates/3_module-detailed-design.md から docs/detailed-design/<module>.md を作成して新 API を記述（--profile=minimal で作られていないディレクトリですが、ここで作って構いません）
後で疑問視されそうな non-obvious な決定が含まれていれば、templates/5_adr.md で ADR を書く

Claude に助けてもらいましょう（how-to/use-with-claude-code.md 参照）:

「この diff を push しようとしてる。pentaglyph の code change → doc change ルールを適用して。この PR で必要な doc 更新を docs/WORKFLOW.md §2 を引用してリストアップして」

最初の 3〜4 PR は不自然に感じます。5 件目で別作業ではなくなります。

Phase 4 — load-bearing なレガシー決定だけ後追いする（2〜4 週目）

チームの過去の選択すべてに ADR を書いてはいけません。みんなが何度も蒸し返している決定 3〜5 件 だけ書きます。

実用的なヒューリスティック: 過去 6 か月で「X を選んだのって、なんでだっけ?」と誰かに聞かれた決定は ADR 候補です。それぞれについて:

templates/5_adr.md を開く
記憶 + 当時いた人との 10 分の雑談で埋める
Status: Accepted と Date: <実際に決定がなされた日。今日ではない> をセット
脚注を追加: 「遡及的に YYYY-MM-DD に記録」

3〜5 件で十分。それ以上は Phase 0 のアンチパターンです。

Phase 5 — 既存の ad-hoc docs を移行（3 週目以降、機会的に）

docs/architecture.md や README.md の中に、本来モジュール詳細設計であるべきセクションがあるはずです。一度に全部動かすな。関連コードに次に触れる PR で 1 件ずつ動かします。

こういうときの Claude 用プロンプト:

「この PR は src/auth/ を変える。古い docs/architecture.md に Authentication というセクションがある。それを templates/3_module-detailed-design.md を使って docs/detailed-design/auth.md に移行して。移行したセクションは architecture.md から削除して 1 行リンクに置き換えて」

4〜8 週これを続けると、レガシー doc は自然に縮小します。最終的に削除できます。

Phase 6 — プロファイルを昇格する（4〜6 週目、任意）

--profile=minimal で作られていないディレクトリが必要になったら ―― 例えば impl plans をスプリント日付で追跡し始めたら:

bunx --bun @uyuutosa/pentaglyph add impl-plans .
# あるいはまとめて:
bunx --bun @uyuutosa/pentaglyph add api-contract .
bunx --bun @uyuutosa/pentaglyph add detailed-design .
bunx --bun @uyuutosa/pentaglyph add design-guide .

add は冪等で、名指したディレクトリだけを書き出します。re-init は不要。

add セクションを 4 個以上使ったなら、実質 --profile=standard に昇格したことになります。新参も同じになるよう、チームハンドブックに反映してください。

チームに見せられるタイムライン

週	活動	工数
0	`pentaglyph init --profile=minimal`	30 分
1	arc42 §1, §3, §5 を埋める	2〜3 時間
1〜4	全 PR に code change → doc change を適用	PR 1 件あたり約 10 分
2〜4	load-bearing な ADR 3〜5 件を後追い	各 30 分
3 以降	ad-hoc docs を機会的に移行	該当コードに触ったとき
4〜6	必要ならプロファイル昇格	`add` ごとに 5 分

最初の 1 か月の意図的な工数は 約 1 日分の作業を 4 週間に薄く分散、 さらに 全 PR への小さな税金。この税金こそが価値の本体です。

pentaglyph を導入しないべきとき

数少ない不適合なプロジェクト形状:

使い捨てスクリプト / 単発プロトタイプ。コスト > 利益。README.md 1 ファイルで十分
純粋なドキュメントリポジトリ（ガイドサイト等）。Diátaxis を直接使えばよい。pentaglyph の arc42 + ADR レイヤは価値を足しません
3 か月以内に削除されるコードベース。ADR と detailed-design はチーム交代と時間の経過に効きます。90 日では元が取れません

それ以外は、小規模チームも含めて利益があります。