エンジニアの引き継ぎ術 EP.04 で、コードから読めるものは書かないという原則を扱いました。この回は、その道具立てを扱います。
原則は分かっていても、手段がないと実行できません。何を生成でき、何を人が書くのかを、具体的に整理します。
1. 生成できるものと、書くもの
まず線引きを明確にします。この判断が全てを決めます。
| 対象 | 生成できるか | 腐りやすさ |
|---|---|---|
| APIの仕様 | できる（定義から） | 手書きだとすぐ腐る |
| 設定項目の一覧 | できる | 手書きだと腐る |
| データの構造 | できる（定義から） | 手書きだと腐る |
| 依存関係の図 | できる | 手書きだと腐る |
| 処理の流れ | 部分的に可能 | 腐る |
| なぜそうしたか | できない | 腐らない |
| 触ってはいけない理由 | できない | 腐らない |
生成できるものは腐りやすく、生成できないものは腐らない。この対応は偶然ではありません。コードから読めるもの＝コードが変われば変わるものだからです。逆に「なぜそうしたか」は、その時点の判断として確定しているので、後から変わりようがありません。 の考え方が効くのは、この性質が背景にあります。
機械が生成できるものは機械に任せ、人は生成できないものだけを書く。これで二重管理が消え、腐る対象がなくなります。原則としては単純です。
2. 文書もコードと同じ場所に置く
── 文書をコードと同じ場所・同じ手順で管理する ── という考え方があります。効果は明確です。
- 変更履歴が残る — いつ誰がなぜ変えたかが分かる
- レビューを通る — コードの変更と一緒に確認される
- コードと一緒に更新される可能性が上がる — 同じ変更に含められる
- 検証を自動化できる — リンク切れや古さを機械的に確認
- 公開まで自動化できる — 手作業の反映が要らない
3番目が最大の利点です。別の場所にあると、更新が別作業になります。同じ場所にあれば、コードを変えるついでに直せる。この差が、腐るかどうかを分けます。
GEO/LLMO EP.09 で構造化データについて同じ話をしました。同じ情報を2箇所に持たないという原則は、領域を変えて何度も現れます。
3. 図をテキストから生成する
図は最も腐りやすい文書です。描画ツールで作った図は、更新の手間が大きく、差分も見えません。
対策は、テキストから図を生成することです。テキストなら変更履歴に残り、レビューでき、修正も容易です。
graph TD Client[利用者] --> Proxy[前段の層<br/>認証・制限・記録] Proxy --> LLM[推論サーバ] Proxy --> Log[(アクセス記録)] LLM --> Model[(モデルファイル)]
subgraph 手元の機器 Proxy LLM Model end
style Proxy fill:#eb5d32,color:#fff style LLM fill:#99cbd0この記法（Mermaid）は多くの環境で描画されます。変更したい箇所を1行直すだけでよく、差分も読める。描画ツールで作り直す手間と比べると、維持のしやすさが違います。
| 図の種類 | テキストから生成 | 備考 |
|---|---|---|
| 構成図・依存関係 | 向く | 変更が多いので効果が大きい |
| 処理の流れ | 向く | 分岐や順序を表現できる |
| データの構造 | 向く | 定義から自動生成も可能 |
| 画面の配置 | 向かない | 見た目が主なので描くほうが速い |
| 概念を伝える図 | 向かない | 自由度が要る |
下2行は素直に描いてよい領域です。全部をテキストにする必要はありません。効果が出るのは変更が多い図なので、そこに絞ってください。
4. 古くなったことを検知する
生成できないもの（判断の理由など）は、人が書くので腐りえます。完全には防げませんが、古くなったことに気づく仕組みは作れます。
import subprocessfrom datetime import datetime
def last_commit_date(path: str) -> datetime | None: """そのパスが最後に変更された日時を取る。""" r = subprocess.run( ["git", "log", "-1", "--format=%cI", "--", path], capture_output=True, text=True, ) out = r.stdout.strip() return datetime.fromisoformat(out) if out else None
# 文書と、それが説明している対象の対応を書いておくPAIRS = [ ("docs/architecture.md", "src/core/"), ("docs/deployment.md", ".github/workflows/"), ("docs/data-model.md", "src/models/"),]
for doc, target in PAIRS: doc_at = last_commit_date(doc) src_at = last_commit_date(target) if not doc_at or not src_at: print(f" ? {doc}: 履歴が取れません") continue
gap = (src_at - doc_at).days mark = "NG" if gap > 90 else "OK" print(f" {mark} {doc:32s} 対象が {gap:4d} 日新しい")対象のコードだけが更新され、文書が放置されている状態を検出できます。完全ではありませんが、「たぶん古い」候補を機械的に挙げることはできます。
この検査を失敗にすると、意味のない更新（日付だけ直す）を誘発します。警告として出し、人が判断する形が適切です。文書の更新は、機械が強制するものではありません。
5. 生成物と読み物を分ける
生成した文書は正確ですが、読み物ではありません。項目が網羅されているだけで、どこから読めばよいか分からない。
| 種類 | 誰が書くか | 役割 |
|---|---|---|
| 入口の文書 | 人 | 何から読むか、全体像 |
| 判断の記録 | 人 | なぜそうしたか |
| 仕様・一覧 | 機械 | 正確な参照先 |
| 図 | 機械（テキストから） | 構造の把握 |
| 手順書 | 人 | 実行できる形で |
入口の文書だけは、必ず人が書いてください。「まずこれを読む」という1枚があるかないかで、後任の立ち上がりが変わります。生成物へのリンクを並べるだけでも構いません。
これは エンジニアの引き継ぎ術 EP.04 で書いた「入口が1つ」という条件と同じです。文書が10個あっても、どれから読むか分からなければ読まれません。
6. 導入の順序
全部を一度に整える必要はありません。効果の大きい順に導入してください。
- 1入口の文書を1枚作る — これだけで立ち上がりが変わる
- 2文書をコードと同じ場所へ移す — 更新される可能性が上がる
- 3手書きの仕様を生成に置き換える — 二重管理を減らす
- 4図をテキストから生成する形にする — 変更が多い図から
- 5古さの検知を入れる — 警告として
1番目が最も費用対効果が高い。入口が1枚あるだけで、既存の文書が活きます。逆に、いくら整備しても入口がなければ読まれません。
そして、書かないという選択も忘れないでください。エンジニアの引き継ぎ術 EP.04 で書いたとおり、コードから読めるものを書き写すと二重管理になります。生成もせず、書きもしない ── それが正しい場合が多くあります。文書が薄いことは、必ずしも問題ではありません。
生成できるものは腐りやすく、生成できないものは腐らない。だから機械が生成できるものは機械に、人は判断の理由だけを書く。文書はコードと同じ場所に置く（更新される可能性が上がる）。図は変更が多いものだけテキストから生成する。古さの検知は警告に留める（強制すると日付だけの更新を誘発）。そして入口の1枚は必ず人が書いてください。
この記事の感想を教えてください
あなたの 1 クリックで、本当にこの記事は更新されます。「もっと詳しく」「続編希望」が一定数集まった記事は、 ふくふくが 実際に内容を拡充したり続編記事を公開 します。 送信したリアクションはお使いのブラウザに記録され、再カウントされません。