Semantic search over a Markdown knowledge base, served over MCP.
v0.14.0 で .xls サポートを取り下げたとき、その理由は 4 箇所に残った —
CHANGELOG.md、英日両方の README、parser/xlsx.rs の 32 行の doc comment、
そして .dev/knowledge/ 配下の private ノート。一方で「将来やり直すかもしれない」
という意思はどこにも残らなかった。private な backlog には項目が無く、
.dev/feature-ideas.md は .xls を done のまま載せていた = 出荷した内容と
正反対のことを主張していた。1 週間後にこの決定を再構成するには 4 つの文書を読み、
5 つ目が間違っていることに気付く必要があった。
これは .xls に固有の失敗ではない。取り下げの PR では取り下げそのものが成果物
なので、変更の説明に労力が向く。採らなかった選択肢を記録するのはその PR の
scope 外に見え、そのまま落ちる。選択肢を比較したあらゆる決定に同じことが起きる —
選んだ道はコードに現れるが、捨てた道はどこにも現れない。
欠けているのは「なぜこうなっているのか、他に何を検討したのか、その代償は何か」に対する 唯一の正典である。それはバージョン管理下にあり、clone に付いてきて、決定を下す pull request 上で review できるものでなければならない。
.dev/decisions/ に private な決定ログを置く。安価で気楽、既存の
private ノート群と一貫する。docs/decisions/、MADR 準拠。コードと同じく git 管理下に置く。選択肢 3 (docs/decisions/、MADR 準拠) を採用する。記録をバージョン管理下に
置く唯一の選択肢だから。
選択肢 1 が .xls の状況を生んだ当のやり方である。選択肢 2 は、利便性より重い
性質で失格になる: .dev/ は .git/info/exclude で除外され、nested repository も
無く、backup も無い。そこに置いた決定ログはバージョン管理されず、clone に付いて来ず、
公開ドキュメントから参照できず、マシンと共に失われる。ADR の価値の中で最も大きいのは
永続性であり、選択肢 2 はそれを消してしまう。
MADR。任意セクションは、必要性が立つ場合を除いて
省略する。ファイル名は NNNN-title-with-dashes.md、0000 から連番、
docs/decisions/ 配下。
英日ペア — NNNN-slug.md と NNNN-slug.ja.md — とする。README および
docs/ 配下で既に使っている規約に合わせる。
英語単独も検討したが却下した。現時点の主たる読者はプロジェクトオーナーであり、
日本語を読むため。長文の英日併記に対する通常の反論はドリフトだが、ここでは
当てはまらない — ADR は編集ではなく superseded で置き換える運用なので、本文は
一度書いたらそのまま放置される。時間とともに変わるのは Status 行だけである。
3 つすべてを満たす時だけ書く:
実務で報告される支配的な失敗は「ADR が少なすぎる」ではなく多すぎることである。
閾値が無いとログが日常的な選択で埋まり、重要な決定が見つけられなくなる。迷ったら
CHANGELOG のエントリで足りる。
ADR は「なぜ」の正典である。他所に重複していた理由づけを吸収する一方、 以下には手を出さない:
| 場所 | 引き続き担うもの |
|---|---|
CHANGELOG.md |
そのリリースで何が変わったか、アップグレード時の影響 |
README |
今日ユーザに何ができて何ができないか |
docs/ARCHITECTURE.md |
現在のシステムがどう組み上がっているか |
| ソースコメント | その行で読者に必要な事実 — 実測値、不変条件 |
.dev/knowledge/ |
調査でどう間違えたか、繰り返さないための罠 |
ADR を追加したら、その理由づけを言い直しているだけの他所の記述は、要約 + リンクに削る。
ADR は取り消しを反映するために編集しないし、削除もしない。決定を変えるときは
新しい ADR を追加し、古い方の status を superseded by ADR-NNNN にする。
捨てた理由づけこそが記録の目的である。
使う status: proposed / accepted / rejected / deprecated /
superseded by ADR-NNNN。
CHANGELOG / README / ソースコメントは、
それぞれが論証を丸ごと抱える代わりに要約 + リンクに縮められる。.dev/knowledge/ に置く。# N. 短い名詞句
- Status: proposed | accepted | rejected | deprecated | superseded by ADR-NNNN
- Date: YYYY-MM-DD
- Deciders: 誰が
## 背景と問題
どんな力が働いているかを中立に述べる。何もしなければ何が壊れるか。
## 検討した選択肢
1. ...
2. ...
## 決定
「...」を採用する。理由は ...
### 結果と代償
決定後の状況 — **悪くなった点も含める**。
### 確認方法
何をもって遵守を確認するか (テスト / CI ステップ / 実測)。
## 参考
PR / issue / 実測値 / 関連 ADR へのリンク。