- 決めたこととその理由に、元の議論への参照を必ず付けて残す「意思決定ログ」を、LLMにWikiへ書かせた
- 書かせたのは2つだけ。コードを読んでも分からない「決めたこととその理由」と、mobileとbackendをまたぐ処理の流れ
- 手で作った2ページに、出典つきの決めたことが41件残った。人にもAIにも、調べやすく、たどりやすい形になった
前提。元のWikiは理由を書く場所だったのに、理由が残らなくなった
私はPMとして、美容サロン向けのモバイルアプリを作っている。対象の機能は肌診断。
元のWikiは、技術選定の理由を書く場所だった。ところが更新が追いつかなくなって、理由が残らなくなった。コードを読めば「どうなっているか」は分かる。分からないのは「なぜそう決めたか」と、mobileとbackendをまたぐ処理の流れだった。
下敷きはLLM Wiki。考え方だけ借りた
Karpathyが2026-04-04にgistで公開した「LLM Wiki」という考え方がある。今のLLMと文書の使い方の多くはRAGで、質問のたびに知識を見つけ直すので、何も積み上がらない。LLM Wikiは、原本と人の間に、LLMが育て続けるWikiを置く考え方。知識は一度まとめたら最新に保つ。
3つの層がある。原本(人が集める、変えない)、Wiki(LLMが全部持つ)、スキーマ(構造と決まりを書いた文書)。3つの操作がある。Ingest(原典を取り込んで関係ページを直す)、Query(Wikiを引いて答え、良い答えはWikiに戻す)、Lint(矛盾や古さを点検する)。
人の手で作るWikiが廃れるのは、保守の手間が価値より早く増えるから。LLM Wikiは、その手間をLLMが全部持つ。
当てはめ方。原本は開発の中で溜まるものにした
- 原本:releaseのmobileとbackendのコード、PRの本文とレビュー、Backlogの課題とコメント。人が集める代わりに、開発の中で自然に溜まるものを原典にした
- Wiki:アプリのリポジトリのGitHub Wiki。人が書いてきた既存のWikiに、LLMが肌診断のページを足す形にした
- スキーマ:スキル update-llm-wiki のSKILL.md。書くものを2つに絞った
- 目録の代わりは _Sidebar.md、履歴の代わりはWikiのgitの履歴
書かせるものは2つだけ
1つ目は、決めたこととその理由。理由が原本に書かれたものだけを書く。出典にBacklogのコメントかPRを付ける。
2つ目は、mobileとbackendをまたぐ処理の流れ。mermaidのシーケンス図で書く。
ページの置き場所は、既存のWikiの作りに合わせた。要件定義の下に機能のページと子ページ、設計の下にデータフローのページという形。
ほかの情報は、それぞれの正本に任せた
- 見た目:Figmaとコード
- APIの仕様:OpenAPI
- 理由がコードのコメントにある決定:コード
全部をWikiに集めない。Wikiに書くのは、どこにも残らないものだけにした。
決めたことの書き方。具体例を2つ
書式は、決めたことを1行、その下に理由と出典。
- 20件の上限はbackendだけで判定し、同時の作成で21件になることは受け入れる
- 理由:カウンタ列や排他制約は、会員のフォーム操作に見合わないため。21件になってもそれ以上は増えず、1件消せば上限内に戻る
- 出典:課題2件のコメント3件
- 数値の項目では、保存した時点の正常範囲を値と一緒に控える
- 理由:後から正常範囲を変えても、過去の判定を保つため
結果。出典つきの決めたことが41件残った
- 手で作った2ページに出典つきの決めたことは41件(OCR取り込みのページに24件、カスタム項目のページに17件)。件数はWikiの先頭の時点で、この2ページの「出典:」の行を数えた
- 最初のコミットは2026-11-17 19:37、5ファイル、270行の追加
- 作ったページは「肌診断」(概要、関連課題、機能一覧、API、テーブル8つ)、「肌診断-OCR取り込み」、「肌診断-カスタム項目」、データフロー(BFF)に2節のシーケンス図
- 作ったページが実際に使われた場面は、まだ確認できていない
前段の取り組み。エンティティグラフとの役割分担
2026-10-02に、画面、API、ユースケース、テーブルなどをnodeとedgeにしたエンティティグラフをWikiに追加していた(30ファイル、20,947行)。用途は障害調査とキャッチアップで、スキル ask-entity-graph がこれを引いて答える。
役割の分け方は、エンティティグラフはコードから機械的に取れる構造、LLM Wikiはコードに無い理由。gistのコメント欄には「コードの知識の本質は関係なので、Markdownは向かず、グラフ型の道具の方がよい」という反論がある。現場での答えは、この2本立てだった。
持ち帰れる判断基準
- LLMに書かせる前に「コードを読んでも分からないものは何か」を決める。そこだけを書かせる
- 理由には必ず出典を付ける。出典が無い理由は、後から検証できない
- 全部を1か所に集めない。既に正本がある情報は、そちらに任せる
自動で更新する仕組みは次の記事で書きます