CodexやKiroへ渡す開発ルールが増えると、共通判断、アプリ固有仕様、実行権限、AIごとの設定が一つの指示書へ混ざりやすくなります。
今回、これらを次の4層へ分離しました。
- Agent Skills：複数の開発で再利用する共通判断
- アプリ固有仕様：特定のシステムだけに適用するルール
- Capability：AIへ許可する作業と実行範囲
- AGENTS.md／Steering：AIごとに正本を参照する入口
この構成を既存のVS Code・Codex・Git・Playwright環境へ追加し、実際の業務管理開発で限定テスト8件と全自動テスト147件を実行しました。
この記事では、4層へ分けた理由、実際の定義方法、運用中にAIが指摘した問題、人間の確認へ戻した位置をまとめます。
先に結論
AIへ渡す情報は、次の四つに分けました。
| 層 | 役割 |
|---|---|
| Agent Skills | 複数の開発で再利用する共通判断 |
| アプリ固有仕様 | 特定のシステムだけに適用するルール |
| Capability | AIへ許可する作業と実行範囲 |
| AGENTS.md／Steering | AIごとに正本を参照する入口 |
重要なのは、ファイル構成そのものではなく、判断基準、対象、作業、実行者を混ぜないことです。
これにより、AIが何を根拠に、どの範囲まで作業しているのかを確認しやすくなりました。
一方、AIの自動選択やRAGまで完成したわけではありません。現在は、人間がApplication、Capability、Providerを選んでいます。
一つの指示書へまとめると役割が混ざる
例えば、「既存テストを削除しない」という指示があります。
これは複数の開発で共通して使えます。
一方、「一般ユーザーには金額を表示しない」は、今回対象にした業務管理システム固有の仕様です。
さらに、「今回はテスト内容の確認だけを行い、全テストは実行しない」は、その作業だけに適用する制限です。
これらを一つの指示書へ並べると、次の区別が曖昧になります。
- ほかのアプリでも必要なルールか
- このアプリだけの仕様か
- 今回だけの作業制限か
- AIが自動的に実行してよい内容か
- 人間の許可が必要な内容か
指示の量より、性質の違う指示が混ざることの方が問題でした。
そこで、指示書を単に短くするのではなく、役割ごとに分けました。
1．共通判断をAgent Skillsへ分ける
最初に分けたのは、複数の開発で再利用する判断基準です。
使用している一つが、locolisu-build-or-buyというAgent Skillです。
このSkillは、新しい開発案、ツール選定、機能追加を評価するときに使用します。
実際のSKILL.mdでは、適用条件を次のように定義しています。
name: locolisu-build-or-buy
description: >
新しい開発案・ツール選定・機能追加を評価するときに起動する。
既存ロコリス資産を先に確認し、次に外部既製品・OSS・APIを調査する。
基本原則は次のとおりです。
- 既製品で十分なら自作を勧めない
- 既存部品の組み合わせで価値が出るなら積極的に採用する
- 既存では目的を満たせなければ、不足部分だけを作ることを検討する
- 独自開発に意味がなければ明確に見送る
実際の確認順序は次のようにしています。
- Applicationを特定し、Registryと固有指示を確認する
- 評価対象、目的、必須要件、利用者構成を確定する
- 既存資産を確認する
- 外部のSaaS、OSS、API、ライブラリを調査する
- 自作が正当化される条件を評価する
- 採用、部品活用型自作、組み合わせ、見送りを判断する
外部調査より前に、既存資産を確認します。
### Step 2：既存ロコリス資産の確認
外部を調査する前に、ロコリス内で既に利用可能なものを先に確認する。
外部候補も、すべてを同じものとして扱いません。
### Step 3：外部代替案の調査
1. 完成SaaS・マネージドサービス（そのまま使う）
2. セルフホスト可能なOSS（自サーバーで動かす）
3. API・外部サービス（呼ぶだけで機能を得る）
4. ライブラリ・パッケージ（コードに組み込む）
このSkillには、画面項目やDB構造など、特定アプリだけの仕様は入れません。
KiroとCodexへ同じSkillを与え、Build方向の誘導を変えながら検証したところ、Skillが適用された状態では、両方とも強いBuild誘導にそのまま従いませんでした。ただし、Skillの自動適用にばらつく回や、Skillは適用されても評価対象を取り違える回もありました。
そのため、Skillが存在することと、今回の作業で必要なSkillが指定されていることを分けて確認します。
現在は、後述するCapabilityとApplication Registryのrequired_skillsで必要なSkillを指定しています。
2．アプリ固有仕様をAgent Skillsから分ける
共通のAgent Skillだけでは、実際のシステムは修正できません。
業務管理には、次のような固有仕様があります。
- 管理者と一般ユーザーで操作範囲が違う
- 一般ユーザーには金額を表示しない
- 案件、作業依頼、業務報告、見積、請求が関連している
- 確定後は許可する操作が変わる
- テストデータは依存関係に従って削除する
これらをBuild-or-Buyのような共通判断へ入れると、別のアプリでSkillを再利用するときに、業務管理の仕様まで持ち込むことになります。
そこで、アプリ固有仕様は専用のinstructions.mdへ分けました。
さらに、Application Registryへ仕様書、実装、テスト、固有指示の場所を登録します。
以下は、実際の構造を公開用に一般化した例です。
"document": {
"repository_id": "document-repository",
"document_path": "applications/<application_id>/",
"instruction_path": "applications/<application_id>/instructions.md"
}
構造として重要なのは次の三つです。
- どの文書リポジトリを使うか
- 対象Applicationの文書はどこか
- 作業前に読む固有指示はどこか
アプリ固有仕様の正本をCodex専用、Kiro専用に分けず、AIの種類に依存しない場所で管理します。
3．Capabilityで作業と実行範囲を分ける
「AIに開発を依頼する」だけでは、作業範囲が広すぎます。
仕様を探すことと、コードを修正すること。
テストを確認することと、実際に実行すること。
設計を評価することと、DBを変更すること。
これらは別の作業です。
現在は、作業の種類をCapabilityとして分けています。
| Capability | AIへ依頼する内容 |
|---|---|
rag_search |
仕様や記録から根拠を探す |
architecture_review |
設計や構成を評価する |
code_edit |
実コードを調査して修正する |
test_review |
テスト内容と検証範囲を確認する |
CapabilityはJSONを正本としています。
Schema上の必須項目は次のとおりです。
id
display_name
reading
purpose
inputs
outputs
checks
current_providers
future_providers
required_skills
human_approval_conditions
execution_mode
notes
SchemaではadditionalProperties: falseとし、定義していない項目を追加できないようにしています。
実際のarchitecture_review.jsonは次の内容です。
{
"$schema": "./capability.schema.json",
"id": "architecture_review",
"display_name": "アーキテクチャレビュー",
"reading": "アーキテクチャー・レビュー",
"purpose": "実装案または既存構造の責務、依存関係、安全性、保守性を根拠付きで評価する。",
"inputs": ["評価対象", "目的と制約", "必要に応じてapplication_id"],
"outputs": ["現状確認", "問題点", "推奨判断", "Evidence", "人間判断事項"],
"checks": ["既存資産を先に確認する", "固有指示、実装、仕様、テストを照合する", "外部候補は必要な場合だけ調査する"],
"current_providers": ["codex_vscode", "kiro_ide", "chatgpt_work"],
"future_providers": ["locolisu_rag"],
"required_skills": ["locolisu-build-or-buy"],
"human_approval_conditions": ["新規依存または外部サービスを採用する場合", "既存構造を広範囲に変更する場合", "仕様と実装の優先順位を確定できない場合"],
"execution_mode": "read_only",
"notes": ["Application非依存のCapabilityである。", "レビューは変更権限を含まない。"]
}
この定義では、単に「設計を見てください」とはしていません。
次を一つのCapabilityとして固定しています。
- 何を入力するか
- 何を出力するか
- 何を確認するか
- どのAIで実行できるか
- どのSkillが必要か
- どの条件で人間へ戻すか
- 読み取りだけか、変更を含むか
execution_modeはread_onlyです。つまり、アーキテクチャレビューを依頼しただけでは、コード修正の権限を与えていません。
required_skillsには、先ほどのBuild-or-Buy Skillを指定しています。
"required_skills": ["locolisu-build-or-buy"]
また、次の場合は人間の承認へ戻します。
"human_approval_conditions": [
"新規依存または外部サービスを採用する場合",
"既存構造を広範囲に変更する場合",
"仕様と実装の優先順位を確定できない場合"
]
Capabilityを分ける目的は、AIの作業を細かく命名することではなく、どの作業を許可したのかを、ほかの作業と混同させないことにあります。
4．AGENTS.mdとSteeringをAIごとの入口にする
Agent Skillsの探索場所や共通指示の読み方は、AI開発環境によって異なります。
今回の検証では、Skillの実行用配置先として次を使いました。
Codex：.agents/skills/
Kiro ：.kiro/skills/
同じSkillをそれぞれの場所で直接編集すると、内容がずれる可能性があります。
そこで、Skillの正本は文書リポジトリ側で管理し、CodexやKiroの探索場所は実行時の入口として扱います。
共通指示も、CodexではAGENTS.md、KiroではSteeringを入口にします。
AGENTS.mdでは、対象Applicationの固有指示を次の手順で参照させています。
- `AI/AI開発基盤/applications/<application_id>.json`と`AI/AI開発基盤/repositories/<repository_id>.json`で、対応する仕様、実装、テスト、固有指示を確認する。
- 対象Applicationの文書を扱う前に、Registryの`document.instruction_path`にある`instructions.md`を全文読む。
- Applicationを特定できない場合、Registryまたは固有指示を読めない場合は、推測して続行せず人間へ確認する。
接続関係は次のとおりです。
AGENTS.md
→ applications/<application_id>.json
→ document.instruction_path
→ 対象Applicationのinstructions.md
AIごとに入口は異なっても、参照する正本は共通です。
また、Applicationを特定できない場合や固有指示を読めない場合は、推測して作業を続けさせません。ここで人間へ戻します。
実装・テスト・仕様も分ける
実際の開発では、作業領域も次の三つに分けています。
| 作業領域 | 管理するもの |
|---|---|
| アプリ | 実コードとDB処理 |
| テスト | Playwrightの自動テスト |
| 文書 | 仕様書、Skill、Registry、設計判断 |
作業領域を分けると、「VS CodeのCodexへ送る」だけでは対象を特定できません。アプリ、テスト、文書のどれを操作するのか分からないためです。
実際の指示では、次を明記します。
- どの作業領域を対象にするか
- 読み取りだけか、変更してよいか
- ほかの作業領域を参照してよいか
- テストを実行してよいか
- どの段階で人間へ確認を戻すか
環境を分けるだけでは足りません。分けた環境を、今回の作業でどう結ぶかまで指定する必要があります。
業務管理の既存テストで実際に試した
この構成が実際の開発で使えるかを確認するため、すでに実装と自動テストが存在する業務管理を対象にしました。
今回扱ったのは、継続契約案件の業務報告に関する既存Playwrightテストです。
確認対象には次が含まれます。
- PC版とスマートフォン版の編集導線
- 一覧へ表示しない操作
- 個別業務報告画面への遷移
- 案件、日付、担当者の一致
- 個別画面からの確定解除
- 解除後の状態
- cleanup時の確定解除
作業中に不自然な点が見つかったときは、テスト側だけを見て修正を確定していません。テストコードの問題なのか、アプリ本体の仕様なのかを切り分けるため、アプリ側の実装も確認しました。
テストを担当するAIが問題を見つけても、その場でアプリを修正させるとは限りません。まず問題を報告させ、必要に応じてアプリ側の作業領域で実コードを確認します。テストが期待する動作にアプリを合わせるのではなく、仕様、実装、テストを照合して判断するためです。
対象テストと依存する初期化を限定実行した段階では、8件すべて成功しました。
さらに、次も確認しています。
- 既存テストを削除・簡略化していない
- 対象外のテストへ変更を広げていない
- 既存の未コミット変更を維持している
- 変更差分に問題がない
- 対象外ファイルを変更していない
- cleanup処理を維持している
限定テストの成功後、全自動テストを実行しました。
全自動テストは147件すべて成功した
実行条件はEdge・workers=1です。
node.exe node_modules\playwright\cli.js test --project=edge --workers=1
結果は次のとおりです。
| 確認項目 | 結果 |
|---|---|
| テスト総数 | 147件 |
e2e-setup |
2件成功 |
| Edge本体 | 145件成功 |
| 全体結果 | 147 passed |
| 失敗 | 0件 |
| スキップ | 0件 |
| 実行時間 | 22.2分 |
| cleanupエラー | なし |
| 失敗成果物 | なし |
git diff --check |
exit 0 |
各テストに組み込んだcleanup検証では、テストデータの残留は確認されませんでした。今回はDBを直接参照した残留確認までは行っていないため、DB上の残留有無は未確認です。
テスト実行前から存在していた未コミット3ファイルについては、実行前後のSHA-256が一致しました。git statusにも新しい変更は増えておらず、全自動テストによる意図しないファイル変更は確認されませんでした。
test-resultsにも失敗時の成果物はなく、.last-run.jsonはstatus: passed、failedTests: []でした。改行コードに関する警告はありましたが、git diff --checkはexit 0です。
この結果から、今回変更したテストは、既存の147件を壊さずに全体へ組み込めたことを確認できました。commitとpushは、この検証時点では未実施です。
147件成功だけを成果にしない
全件成功は必要な結果ですが、それだけで今回の開発環境が有効だったとは判断していません。
今回確認できたのは、次の流れです。
- AIがテスト中の不自然な点を指摘した
- テスト側だけで結論を出さず、アプリ側の実装も確認した
- 仕様、実装、テストを照合して変更範囲を決めた
- 対象テストと依存する初期化を限定実行した
- 未コミット変更を保全した
- 最後に全自動テストを実行した
- 差分、cleanup、失敗成果物の有無まで確認した
AIへコードやテストを修正させるだけでなく、問題を見つけたときに別の作業領域へ確認を戻し、最後まで変更範囲を維持できました。ここが、147件成功という数値よりも重要な結果です。
すぐにRouterを作らない
将来的には、依頼内容から次を選ぶRouterを検討しています。
Application：どのシステムを扱うか
Capability：何をさせるか
Provider：どのAIを使うか
現段階では自動選択させていません。例えば、テストで不自然な動作を見つけた場合でも、次の選択肢があります。
- テストコードを修正する
- アプリ側の実装を確認する
- 仕様書の記述を確認する
- 現在の挙動を正として記録する
- 判断を保留する
この分岐を十分に記録していない状態でRouterを作ると、未整理の判断をそのまま自動化することになります。現在は人間がApplication、Capability、Providerを選び、その履歴を蓄積しています。自動化は、判断基準と失敗例が集まってからです。
RAGも検索対象を整えてから使う
RAGを導入すれば、仕様や過去の判断をAIが探しやすくなります。しかし、検索対象に古い仕様や推測が混ざっていれば、誤った情報を素早く見つけるだけになる可能性があります。
そのため、先に次を整えています。
- 仕様書の正本を決める
- 実コードと仕様の一致を確認する
- 確認済み、推測、不一致を区別する
- 共通のAgent Skillとアプリ固有仕様を分ける
- AIが参照すべき場所を固定する
RAGは、この土台が整ったあとに追加します。検索機能より先に、何を根拠として扱うかを決める必要があります。
最小構成で始めるなら
同じようにAIへの指示が増えている場合、最初からAgent Skills、RAG、Routerをすべて用意する必要はありません。
まず、現在の指示を次のように分けるだけでも整理できます。
| 質問 | 保存する場所 |
|---|---|
| ほかの開発でも使う判断か | 共通ルールまたはAgent Skill |
| このアプリだけの仕様か | アプリ固有仕様 |
| 今回だけの制限か | 作業時の指示 |
| AIが自動実行してよいか | 権限またはCapability |
| 判断の根拠は何か | 仕様、実コード、テスト |
| 最終的に誰が決めるか | 人間の確認工程 |
特に、次の三つを一つの指示へ混ぜないことが重要です。
守るべき判断基準
今回評価する対象
今回許可する作業
Skillが正しくても、評価対象が曖昧なら別のものを正しく評価します。対象が正しくても、実行範囲が曖昧なら不要な変更やテストへ進む可能性があります。
まだ確認できていないこと
今回確認できたのは、一つの業務管理開発で、この分け方を実際の作業へ適用できたことです。次はまだ確認できていません。
- 別の機能改修でも同じ流れを維持できるか
- 新規アプリへ共通のAgent Skillを再利用できるか
- Skillの適用漏れを継続的に検出できるか
- 人間の説明や確認が実際に減るか
- 誤修正や手戻りが減るか
- RAG追加後も根拠を正しく区別できるか
- どの判断をRouterへ任せられるか
- Codex以外でも同じ品質を維持できるか
したがって、現段階で「AI開発基盤が完成した」とは判断していません。AIへ何を渡し、何をさせ、どこで人間が確認するかを整理し、既存開発で一度通して確認できた、というのが現在確認できているところまでです。
まとめ
AIへの指示が増えたとき、すべてを一つの長い指示書へ入れる方法もあります。しかし、共通判断、アプリ固有仕様、作業範囲、AIごとの入口が混ざると、再利用と確認が難しくなります。
今回、これらを四つに分け、既存のVS Code、Codex、Git、Playwright、ChatGPT Workへ追加しました。新しい統合アプリへ置き換えたわけではなく、既存環境で足りている部分を残し、毎回人間が説明していた判断と境界を、再利用できる形へ整理しました。
外部の記事や事例から得たヒントもありますが、紹介されていた方法をそのまま正解として採用したわけではありません。現在の環境で試し、必要なものだけを取り入れ、合わないものは採用しませんでした。
業務管理での最初の実運用では、限定テスト8件と全自動テスト147件がすべて成功しました。それでも、これだけで開発効率や品質が向上したとは断定していません。今後の開発でも同じ運用を続け、説明の繰り返し、誤修正、手戻り、人間の確認回数がどう変わるかを記録します。
AIへ渡す情報を増やす前に、判断基準、対象、作業、実行者を分ける。
この分け方が、既存の開発環境を大きく作り直さずに強化する最初の一歩になりました。
判断の背景はNoteにまとめました
この記事では、Agent Skills、アプリ固有仕様、Capability、AGENTS.md・Steeringを分けた構成と、実際の検証結果を中心に紹介しました。
なぜ新しい統合環境を作らず、現在の開発環境を生かす判断をしたのか。その背景はNoteにまとめています。