※【前提】内容としては私の要件を組んで作成したsession時の内容をAIにまとめさせています。技術者向けな内容かと思います。
AIの実装精度を上げるために、C/D分離のSKILLS基盤を設計した
入口制御、意思決定、実装、自己改善を分けて、AIに小さなPDCAを回させる
生成AIを開発に組み込む時、最初にぶつかるのは「能力不足」よりも「挙動の不安定さ」だと思っている。
同じ依頼でも出力が揺れる。
文脈を足すほど精度が上がるとは限らない。
一度修正したはずの失敗を、別のタスクでまた繰り返す。
この問題は、モデル単体の性能だけでは吸収しきれない。
そこで今回は、AIに与える役割と読み込み順序そのものを設計し直し、C: 側に共通基盤、D: 側にプロジェクト密着の入口制御を置く、2層のSKILLS構成を作った。
目的は、AIを単発で便利に使うことではなく、一定の流れで安定して動かすことにある。
1. なぜSKILLSが必要だったのか
開発におけるAI活用は、プロンプトを工夫するだけではすぐに限界が来る。
特に、以下のような問題が積み重なる。
- リポジトリに入るたびに、何を先に読むべきかが曖昧
- 設計判断と実装が同時に走り、思考が混線する
- テストや整合性確認が後回しになりやすい
- 修正経験が再利用可能な知識として残りにくい
つまり、問題は「AIが考えられないこと」ではなく、AIにどの順番で、どの責務を持たせるかが設計されていないことだった。
このため、今回のSKILLSでは次の4点を主目的にした。
- 出力の再現性を上げる
- コンテキストを最小化する
- 判断と実装を分離する
- 学習結果を次回に持ち越せるようにする
2. 全体構造：CとDで役割を分離する
今回の設計は、大きく D: 側のローカルSKILLSと、C: 側のグローバルSKILLSに分かれている。D: 側には core-skill と solution-deliberation を配置し、C: 側には core-loader、engineering-core、self-improvement、さらに system skills 群を置いている構成だ。
D側の責務
D側は、そのプロジェクトに入った時の入口制御と意思決定を担う。
core-skillsolution-deliberation
特に core-skill は、最初に読む順番を厳密に固定している。
内容としては、まず docs/sessions/LATEST.md を読み、その次に AGENTS.md を読み、さらに追加の文脈は必要時のみロードする、という構成になっている。
これはかなり重要で、最初から全ドキュメントを読む設計にはしていない。
先に「最新状態」を握り、その後に「守るべきルール」を読む。
この順番があることで、AIは現在地を見失いにくくなる。
一方 solution-deliberation は、実装を始める前に比較・評価・推奨が必要なケースのために分けている。
説明にもある通り、これは architecture、workflow、strategy、best-option のような、代替案比較が本質になるタスクだけで使う前提で、routine implementation や simple file edits には使わない。
C側の責務
C側は、プロジェクト横断で再利用する実装・改善・補助機能のレイヤだ。
ディレクトリ構成としては core-loader、engineering-core、self-improvement に加えて、.system 配下に imagegen、openai-docs、plugin-creator、skill-creator、skill-installer が置かれている。
ここで中心になるのが engineering-core と self-improvement で、前者が実装や修正を、後者が学習と再利用を担う。
つまり、D側が「どう入るか・どう考えるか」を決め、C側が「どう直すか・どう学ぶか」を担う構図になっている。
3. 入口制御：なぜ LATEST.md → AGENTS.md なのか
今回のSKILLS設計で、最も効果が大きかったのは入口の固定化だった。
core-skill の説明では、baseline repository entry skill として、Read the latest session state first, then AGENTS.md, and load extra context only on demand と明示している。
この順序にした理由は単純で、AIにとって先に必要なのは“情報量”ではなく“現在の状態”だからだ。
もし先に静的なルールや大量の補足文書を読むと、現在のタスクがどこまで進んでいるか、何が既に決まっているか、どこから再開すべきかがぼやける。
逆に、先に最新セッションを読むと、
- いま何をしているか
- 直近で何を決めたか
- どこまで終わっているか
が先に揃う。
その上で AGENTS.md を読むことで、「今の状態に対してどの制約で動くか」が確定する。
これは実務上かなり効く。
AIが毎回ゼロから全体像を作ろうとしなくなるからだ。
特に継続タスクでは、入口の順番が乱れるだけで、同じ説明を繰り返したり、終わった検討を蒸し返したりしやすい。
だからこの設計では、最初に全部読むのではなく、最初に読む順番を設計することを優先している。
4. Trigger設計：When分岐で責務を切る
今回の記事で一番伝えたい技術的ポイントのひとつが、Whenベースのスキル分岐だ。
AIに対して「全部やって」とまとめて渡すと、設計の比較検討と、実装の修正と、学習の抽出が一度に混ざりやすい。
これを避けるため、タスクを種類で切り分けている。
考え方としては次のような分岐になる。
- 実装・バグ修正が必要な時
→engineering-core - アーキテクチャ比較や最適案の推薦が必要な時
→solution-deliberation - 再利用価値の高い改善や失敗パターンが見つかった時
→self-improvement - まずはプロジェクト文脈の把握だけが必要な時
→core-skillのみ
D側の solution-deliberation でも、architecture / workflow / strategy / best-option requests がトリガーであり、routine implementation には使わないことが明示されている。
この明確さが重要で、AIの思考を“広げるべき時”と“狭めるべき時”を分けている。
これは人間の開発フローにも近い。
設計会議の頭と、バグ修正の頭と、振り返りの頭は本来別であるべきだ。
AIでも同じで、役割を同時に持たせない方が品質が安定する。
5. engineering-coreでやりたいこと：実装ではなく、修正ループの標準化
今回まだ記事としては engineering-core の全文を出していないが、設計思想として置いている中心ははっきりしている。
それは、AIに「コードを書く」だけではなく、「修正ループを回す」ところまで担わせることだ。
自分の中で engineering-core に期待している動きは、概ねこうだ。
- 現状把握
- 問題の切り出し
- 原因仮説の整理
- 修正方針の決定
- 実装
- テスト
- 失敗時の再修正
- 整合性確認
- 結果の要約
重要なのは、6以降が“おまけ”ではないことだ。
多くのAI活用は、コードを書いた時点で満足しやすい。
でも実務では、そこから先の方が重い。
- テストは通るか
- 仕様と矛盾していないか
- 関連箇所の整合が崩れていないか
- 一見直っただけで、別の不具合を埋め込んでいないか
このレベルまで見る必要がある。
自分がやりたいのは、AIに「最初の修正案」を出させることではない。
バグを見つけ、直し、試し、失敗したら戻り、通ったら整合性まで確認する流れを標準動作にすることだ。
ここができると、AIは単なる補助ではなく、小さなデバッグエンジンとして振る舞えるようになる。
6. AIに小さなPDCAを回させる
この設計のコアは、AIが自分で小さなPDCAを回せるようにすることだ。
Plan
- どこに問題があるか整理する
- 何が既知で何が未確定かを分ける
- 修正方針を立てる
Do
- 実装または修正を行う
- 必要な差分を限定して当てる
Check
- テストを回す
- 差分を見直す
- 関連箇所との整合を確認する
Act
- 今回の失敗・改善・判断根拠を再利用可能な知識にする
- 次回同種タスクで同じ失敗を起こしにくくする
ここで強調したいのは、Actまで含めて設計している点だ。
AI活用は、Plan-Do-Check までは比較的イメージしやすい。
ただ、Act、つまり「今回得たものを次回に効く形へ変換する」工程が弱いと、毎回似た失敗を繰り返す。
だからこそ、今回の構成では self-improvement を独立レイヤとして置いている。
7. self-improvement：失敗を知識へ変換するレイヤ
self-improvement は、今回の設計の中でもかなり重要な役割を持つ。
理由は明快で、AIはその場でうまくやれても、次回同じようにうまくやれるとは限らないからだ。
たとえば、あるバグ修正で次のような知見が得られたとする。
- どんな条件で不具合が起きたか
- 根本原因はどこだったか
- 修正方針として何が有効だったか
- 今後はどういう条件分岐やテストが必要か
こうした情報を、その場限りの会話ログで終わらせると、次回また似たことを一から考えることになる。
それでは改善が蓄積しない。
そのため、self-improvement では、再利用価値の高い失敗パターンや修正パターンを、ノイズの少ない形でナレッジに集約する前提にしている。
単なる反省ではなく、再発防止と再利用のための知識化だ。
自分はここをかなり重視していて、AIに同じミスをさせないためには、モデルを変えるより前に、失敗を構造化して残す仕組みが必要だと考えている。
8. system skills：用途特化機能を分離する理由
C側の .system 配下には、imagegen、openai-docs、plugin-creator、skill-creator、skill-installer などの用途特化スキルを置いている。
たとえば imagegen の SKILL.md では、画像生成・編集が必要な場合のみ使うこと、通常は built-in ツールを優先し、CLI fallback は明示要求時のみ使うことなどが細かく整理されている。
こうした system skills を別レイヤに分けているのは、責務を濁らせないためだ。
つまり、
- 実装基盤は
engineering-core - 学習は
self-improvement - 画像やドキュメントなど用途特化の処理は system skills
というように、共通基盤と補助機能を分ける。
これにより、コアロジックが肥大化しにくくなる。
9. この構造で期待している具体的な効果
このSKILLS構成に期待している効果は、かなり具体的だ。
出力の安定化
入口が固定され、責務が切られ、実行フローが整理されることで、同じタイプの依頼に対して似た処理経路が走る。
これにより、回答や修正のブレが減る。
トークン効率の改善
core-skill の時点で「追加文脈は必要時のみ」と決めているため、不要なファイルを抱え込みにくい。
全部読ませる設計より、むしろ精度とコストの両立がしやすい。
デバッグ速度の向上
バグ検出 → 修正 → テスト → 再確認の流れを前提にすることで、場当たり的に触るよりも修正の往復回数を減らしやすい。
品質の底上げ
修正だけではなく、整合性確認まで含める前提にしているため、ローカル最適な修正で終わりにくい。
学習の蓄積
self-improvement によって、過去の失敗や改善を知識化できれば、同種タスクの立ち上がりが速くなり、同じミスをしにくくなる。
要するに目指しているのは、AIがたまにスーパーな出力をすることではない。
平均点を高く保ったまま、継続的に改善できる状態だ。
10. 運用思想：SKILLSは毎週更新されるべき
個人的には、SKILLSセットは一度作って完成ではなく、最低でも1週間単位で見直されるべきものだと考えている。
理由は単純で、
- 取り組むコードベースが変わる
- 良いプロンプトや良い分岐条件が変わる
- 蓄積される失敗パターンが毎週増える
- AI自体の使い方も変化する
からだ。
つまり、SKILLSは静的ルールブックではなく、運用の中で調整される“実装可能な作法”に近い。
実際、自分はこの構造を固定物ではなく、改善前提の土台として見ている。
11. 今後の見解：AIは外部情報を取り込み、自分で進化する方向へ向かう
これは個人的な見解だが、今後はAIが自ら新しい情報をキャッチアップし、それを前提に自分で実装し、検証し、改善する流れがより現実的になっていくと思っている。
シンギュラリティのような大げさな話をしたいわけではない。
ただ少なくとも、開発現場においては、
- 新しい情報を取る
- 方針に落とす
- 実装する
- テストする
- 失敗を学習する
というループを、AIがより自律的に回す方向に進むはずだ。
その時に必要なのは、単純なモデル性能の向上だけではない。
どう動くか、どう学ぶか、どこで止まるかを定義した構造だと思っている。
今回のC/D分離SKILLSは、その前段としての実装だ。
まとめ
今回構築したSKILLS基盤は、単なる便利機能の集合ではない。D: 側で入口と判断を制御し、C: 側で実装・改善・補助機能を担わせることで、AIの挙動を役割単位に分離している。
特に重要なのは次の3点だ。
LATEST.md → AGENTS.md → 必要時のみ追加読込という入口順序- When分岐による判断・実装・学習の責務分離
- 修正して終わりではなく、テスト・整合性確認・知識化まで含めたPDCA
AIを使うこと自体は、これからますます簡単になる。
でも、AIを安定して使い、バグを減らし、改善を積み上げ、実務で信頼できる形にするには、やはり構造が必要になる。
今回のSKILLS設計は、そのためのひとつの答えとして作った。
そしてこれは完成品ではなく、毎週更新され続ける前提の基盤でもある。
