AI coding agent に信頼できるドメイン知識を与える方法

汎用 coding agent はもっともらしい答えを書けても、stack で重要な細部を見落とすことがあります。最近変更された API、越えてはいけない repository boundary、production を安定させる convention などです。解決策はいつも長い prompt ではありません。小さく再利用できる domain guidance と、検証可能な definition of done を用意しましょう。

1. project rules と domain procedure を分ける

2つの層を作ります。最初は短い repository contract です。project の概要、構成、build/test command、編集禁止ファイル、done の条件を記します。JetBrains の agent behavior documentation は AGENTS.md や CLAUDE.md のような instruction file が repository とともに移動し、複数の tool で共有できると説明しています。

この層は安定した運用情報にします。domain logic の場所、check の実行方法、編集してはいけない範囲を答えられるようにします。1つの workflow だけに必要な rule は別の skill に置きます。

2つ目は domain knowledge です。Android navigation migration、database schema change、release checklist など、繰り返す作業のための focused recipe です。skill には明確な trigger、短い手順、明示的な validation を含めます。

2. knowledge gap を中心に skill を書く

良い skill は model が同じ間違いを繰り返す、または同じ発見を毎回やり直すときに作ります。Android Skills の考え方 は、変化する API や custom architecture にある検証可能な gap に焦点を当てます。未検証で有害な指示を含む可能性のある大規模な集合ではなく、信頼できる source から skill を取得することも勧めています。

小さな例です。

---
name: navigation-upgrade
description: Use when changing the app's Navigation 3 setup or upgrading its related APIs.
---

Before editing:
1. Inspect the current dependency versions and existing navigation tests.
2. Read the project's navigation conventions.
3. Confirm the target API in the approved platform documentation.

While editing:
- Make the smallest vertical change that satisfies the requested behavior.
- Do not replace the navigation architecture without approval.
- Preserve existing deep-link and back-stack behavior unless the task says otherwise.

Done means:
- The focused tests pass.
- The relevant build or lint command passes.
- The response names changed files, checks run, and unresolved risks.

例を狭くしているのは意図的です。framework のマニュアル全体を毎回貼らず、いつ適用し、何を確認し、どの境界を守り、どう完了を示すかを定義します。実際の repository の command と convention に置き換えてください。

3. agent に行動前の確認をさせる

Coding agent は request と environment context を組み合わせ、推論し、edit・test・build を実行します。これは AWS Prescriptive Guidance が説明する pattern です。指示の中で各段階を見えるようにします。

実用的な request は4部分です。

1. Context: feature、関連 directory、constraint。
2. Plan: edit 前に files と checks を列挙。
3. Change: acceptance criteria を満たす最小の実装。
4. Evidence: tests、lint、build、manual checks。

これにより、agent が一文から coding を始め、後で architecture を発見して大きく書き直す状況を避けられます。確認は儀式ではなく、判断に必要な context を得る方法です。

4. 短い feedback loop を与える

Domain guidance は project の動きを説明しますが、実行可能な check が変更の正しさを示します。VS Code の現在の TDD guide は、失敗する test の red、最小実装の green、test を保った refactor を分けています。

複雑な3つの agent は不要です。小さな task ではまず failing test または characterization test を求め、次に実装し、focused test と通常の quality gate を実行します。check に失敗したら、それは requirement や environment に関する情報であり、確信のある要約で隠す理由ではありません。

5. guidance を見直し、不要なら廃止する

skill を versioned engineering infrastructure として扱います。framework の変更、agent の反復ミス、noisy な check があれば見直します。Android Skills の guidance は skill を deprecation の候補としています。model が改善し、不要な指示が生まれる一方、新しい API が新しい gap を作るからです。

軽い maintenance loop:

• skill を使う example task を残す。
• expected files と validation command を記録する。
• skill または model の変更後に実行する。
• 不要になった instruction を削除する。
• security-sensitive action は optional かつ review 可能にする。

目的は agent を賢く見せることではなく、正しい behavior を再現しやすくすることです。短い repository contract、狭く起動する domain procedure、実行可能な done-definition が context から change、evidence への道を作ります。