はじめに
AI 開発が活発になる中でついに Claude Max を私的に導入してしまった。導入してしまった以上は使い倒そうと過去2回記事にしたローカルLLMを利用したbot開発を行っている。
このbotは最初の記事でも少し触れたがコンセプトが、現在のbot事情、すなわち複雑なコンテキストをなるべく文章としてわかりやすくLLMに伝え、パワフルなLLMでぶん回すという最近の流行りとは真逆のリソースの限られるローカルLLMを対象とした、古式ゆかしき分割統治のプロジェクトであることから、気を抜くとAIが一般的なbotのように実装しようとしてしまう。そのため、要求やスペックをガチガチに書くのもよいのだが、そもそもなぜそんなアーキテクチャを採用しているのかという要求の導出元、すなわちコンセプトをプロジェクトを通して芯としている。それを完遂させるための技術的決断もレポジトリに残すようにし、AIが迷わないように誤らないようにしている。
一見ハーネスエンジニアリングのように聞こえるが、そうではなく大原則から当たり前に導出される推測により、AIがそもそもだいたい正しい方に進むように仕向けるのが肝要だ。今回はこれについて書こうと思う。
コンセプトとはなにか
本記事でいうコンセプトは、要求の導出元のことだ。これはトートロジーでずるいので何のために何を作りたいのか、という目的とゴールの姿だ。 要求でも「何ができるべきか」を語ることはできるが、要求をたくさん並べたところでなんでそんなことをしたいんだっけ？は結構抜けてしまう。 似たところで言うとコード上のコメントと同じ構造で、コードそれ自体ではなぜその意思決定をしたかの経緯が書けないが、コメントはそれを補うことができる。 要求の行間に落ちた意味をコンセプトが補うようにすれば、判断を誤る確率が少なくできる。
コンセプトは「そもそもこのプロジェクトは何であるか」「なぜその要求群になるのか」を語る一段上の文書で、私のリポジトリでは CONCEPT.md として置いている。
リンク読むのだるいでしょうから平たく簡単に言えば下記のようなことが書いてある。
- この bot は家庭用の bot でローカル LLM 上で動く記憶をもったエージェントである
- 正確性よりも一緒にいる感を出すために記憶を持たせるがたまに間違えても良い
- 小さいモデルでも破綻しないよう、一回あたりの判断の出力空間を徹底的に縮める（分割統治）
まあ最後のは要求かもね？だけれど要求だけでは上記の話は書けないし誰も忘れるし、 AI に伝えていないから AI はわからずに実装することになる。 分割統治などは最初の記事で触れたように最近の流行りではないため、 AI は平均的な書き方にしようとして違う実装をすることすらある。
ただ一点付け加えておけばプロダクトを作る際にそこまできっちりしたコンセプトがあれば気苦労はせんのだと言われたらまあそう。 だけど仮のものぐらいはあるでしょ？例えば〇〇のパクリで安く早く作ってソフトウェアが貧弱な間はコンサルで埋めてなんとか売ってしまおうとかね。
実際の開発手順
運用はシンプルで、docs を層にして、修正は必ず上流から入れる。これだけ守っている。
層は上から CONCEPT（何であるか・設計原理）、requirements / SPEC（何ができるべきか）、design（どう作るか）、実装。AI にはこれらを常にコンテキストとして読ませる。
「必ず上流から」とはどういうことか。実装に違和感やバグが出たとき、コードを直接直させるのではなく、まずどの層の誤りなのかを特定する。単なる実装ミスなら実装を直せばよいが、設計の筋が悪ければ design を直してから実装を再導出させるし、要求が実は間違っていたなら requirements から落とし直す。そして、要求同士が矛盾したり、作っていて「なんか違う」が続くときは、コンセプトそのものを見直す。必要であればコンセプトから直して、下流に落とし直す。下流だけを直してもよいがそのうちドキュメントが陳腐化するので、ドキュメントと実装の食い違いを直してほしいというのを熟練の勘で入れている。この辺はチーム開発するならもう少し堅くやるべきかとは思う。
実例を一つ。この bot で実際にあった一番大きなアーキテクチャ変更例は、もともと AI の行動は中央管制官たる「全部ジャッジするくん」が会話を見て何をするべきか、例えば Web Search なのか知識の思い出しなのか、を決めることとしていた。が、これはアーキテクチャ上中央管制官に負担が集中する構造であり、そもそもそんなに美味しい作りではなかったので、 Web Search をするべきかどうか、メモ書きを思い出すべきかはそれぞれ行動を起こす前に独立して判定するように変えた。これは分割統治をベースとするコンセプトに照らすと、より良い設計なわけでコンセプトにも沿っているからとコンセプトは変更せず、要求やアーキテクチャから変更している。なお、実際のドキュメント構造は下記のようである。
実際にこの辺のドキュメントは AI が勝手に作ったのでそのままにさせている。 DECISIONS.md 等に当時の判断基準なども残るので便利は便利。言うなれば社内 Wiki などもう要らんから全部 GitHub でやるくらいの構造になっている。チーム開発でこんなに雑なことしていいかについてはよくわからない、ただいまなら MCP + AI で Notion MCP を使った議事録から DECISIONS.md を更新する PR を AI に作らせればいいので去年（2025/06~07月）よりはだいぶやりやすくなっていると思う。
何が良いか
体感の話になるが、Sonnet や Opus 級のモデルなら、概ね誤らなくなり実装終わって確認すればほぼ動くようになっている。ただ、自分自身の趣味の時間がそんなに取れない中、コンセプトなしで実装したりするのはあまりに時間の無駄なのでないとどうなるかはわからない。とはいえこれは人間と開発するのでも一緒でしょう？という気持ち。
付け加えれば LLM も人間と同じで与えられた原則から当たり前の帰結を導出することができる。だからコンセプトという大原則を渡しておけば、要求に書いていない判断も原則から導出された方向——つまりだいたい正しい方——に倒れる。逆に原則を渡さなければ、その導出力は既存のコードにめちゃくちゃに引っ張られるわけで、そうなると負債が増える方向に倒れるだろう。あと最近 Max にしたから Opus による多面レビュー（この修正を批判的にチェックして等）もかなり有効であり、前述のドキュメントを綺麗に保つよう陳腐化を修正するのと合わせてやると有用であろう。
ハーネスではない
ここまでの話は、ガードレールやハーネスエンジニアリングではない。大筋の開発の原則の話で、上流から直せ、 SDD でやれ、 TDD だぞ、という原則を与えることで比較的品質の高いコードが産まれ続ける。ここ２～３週間くらい別のプライベートプロジェクトをやっているが、 10 万行くらいでも別にそんなに腐ってこないので効果はある？わからないね。
ハーネスは事後出てきたものを lint・テスト・レビューで弾き文字通り品質の低いコードのガードになるが、コンセプトは事前の仕組みで、行動の原則を整えるものである。 ガードするのも大事だが、そもそもガードしないといけないものが出てこなくなる方向の調整であるので両方やったらいい。 個人の開発では事前のコンセプトと TDD の原則でそんなに壊れるようなものがでてこないので便利、 Sonnet, Opus 級が賢すぎるのかもしれないけど。
終わりに
まとめると今回の試みは下記のようなやり方になる。
- docs 下に公式な意思決定等のドキュメントをまとめるようにする
- CONCEPT.md にこのプロジェクトが何であって何を目指すのかを書く
- 実装時は上流工程から CONCEPT -> Requirements -> Spec -> Design のように修正をかける意識をする
- 時々ドキュメント全体を見させる時間を作る
なんか AI に聞いたらあんまこういう記事ないんじゃないの？って言われたので書いた面はある。 正直当たり前のことしか書いていないので個人的にはだからなんだよ、という記事ではあるが記事自体を書くのは必要かと思い筆を取った。
なおこの記事は Fable が書いたものを全面却下し骨子を自分で書き直し Fable にもう一回書かせた内容を半分くらい自分の言葉に変えて書いた。 外向きの文章というのはガチガチにルール決めない限りあまり AI が書けるものではないんだろうなあという思いを新たにしている。
