なぜ pentaglyph が存在するのか

このページについて：これは長文の Why です。ツールを「ただ使いたい」だけなら、チュートリアルと How-to ガイドで十分です。このページは「本当にこれが必要か？」と立ち止まったとき — 多くの場合、運用開始から数週間が経って規律がコストに感じ始めた瞬間 — のためにあります。

短い答え

ドキュメント標準はすでに存在します。問題は 標準同士の隙間 にあります：

arc42 は「アーキテクチャドキュメントの 12 セクション」を教えてくれる。でも いつ書き始めるか は教えてくれない。
Diátaxis は「Tutorials / How-to / Reference / Explanation の 4 象限」を教えてくれる。でも 4 象限のどれをどのディレクトリ名にすべきか は決めてくれない。
MADR は「決定 1 件 = 1 ファイル」と教えてくれる。でも いつ Status を Accepted から Superseded にするか のトリガーは決めてくれない。
どの標準も、AI エージェントに「今やった変更に対応するドキュメントは docs/architecture/05-runtime-view/ の module-x.md を更新せよ」とは指示しない。

pentaglyph は外部標準を再発明しません。 標準同士の継ぎ目と、AI エージェントが迷子にならないための単一ワークフローだけを足します。

長い答え

1. 標準を「拾い読み」した結果、3 つの中途半端な慣習が残る

実プロジェクトで起きること：

プロジェクト立ち上げ時に、誰かが arc42 を聞きかじって docs/architecture.md を 1 ファイル作る
半年後、別の誰かが Diátaxis を知って docs/tutorials/ を切る
さらに半年後、3 人目が ADR を知って docs/adr/ を作る

この時点で 3 つのドキュメント文化が混在 し、それぞれが標準の 30% しか実装されていません。新人もエージェントも「どこに書けば正解か」が分かりません。

pentaglyph は 5 つの標準すべてを最初から 1 ディレクトリ構造に並べる。これは「全部使え」という強制ではなく、「使うかどうかにかかわらず、置き場所だけは最初から決めておけ」というデフォルト構造の提供です。

2. AI エージェントは「ここに書け」と明示されないと書けない

LLM はドキュメントを書くのは得意です。しかし「どこに置くか」「いつ更新するか」「他のドキュメントとどう関係付けるか」は、明示されないと推測しません（推測した結果、ランダムな場所に書きます）。

pentaglyph は ディレクトリごとに README.md を置き、その先頭に AI 向けの指示 を書きます。例えば docs/arc42/09-decisions/README.md には：

## AI Instructions

When the user asks you to record an architectural decision:
1. Create a new file `NNNN-<kebab-title>.md` (NNNN = max existing + 1, 0-padded to 4 digits)
2. Use the MADR v3.0 template in this directory's `_template.md`
3. Set Status: Proposed; the user will Accept it via a separate PR
4. Link related decisions with `[[NNNN]]` references

これでエージェントが自走できます。

3. コード変更とドキュメント変更を「同じ PR で」強制する

pentaglyph の WORKFLOW.md には 「コードを変更したら同じ PR でドキュメントも更新する」 ルールが書かれています。これは規律であり、自動化ではありません — でも、ワークフロー文書として最初から書かれていることで、レビュアもエージェントも参照できます。

詳しくはなぜコード変更 → ドキュメント変更なのかを参照。

4. 「ドキュメント標準は人間と AI の共有プロトコル」という発想

最後の動機がこれです。従来、ドキュメント標準は 人間のため に作られていました。 AI エージェントが日常的にコードベースを触るようになると、ドキュメント標準は 人間と AI が共有するプロトコル に変わります。プロトコルとして機能させるには：

配置が 予測可能 であること（autogenerate できる）
ライフサイクル状態が明示されていること（Draft / Active / Superseded / Archived）
各ディレクトリに AI 向け指示 があること（プロジェクト文脈なしで動ける）

pentaglyph はこの 3 条件を構造として組み込んだキットです。

それでも pentaglyph を使わない選択

すでに成熟した社内のドキュメントシステムがあり、人間も AI も迷わず動いているなら、 pentaglyph は不要です。pentaglyph は 「これから整える」「整え直す」 チームのためのものです。

このページは元の英語版 why-pentaglyph.md の要約です。原典には数値ベンチマーク・歴史的経緯・代替案との比較がより詳しく書かれています。