如何为 AI 编码代理提供可靠的领域知识

通用编码代理可以写出看似合理的答案，却遗漏技术栈中最重要的细节：上个月刚变化的 API、不能越过的仓库边界，或保证生产稳定的项目约定。解决办法不总是更长的提示。更好的做法是提供小而可复用的领域指导，并定义可验证的完成条件。

1. 分离项目规则与领域流程

先建立两层。第一层是简短的仓库契约：项目是什么、如何组织、哪些命令用于构建和测试、哪些文件禁止修改，以及“完成”意味着什么。JetBrains 关于代理行为的文档 将 AGENTS.md 和 CLAUDE.md 等指令文件描述为随仓库保存、可以跨工具共享的指导。

让这一层保持稳定和可操作。它应回答每个任务都需要的问题：领域逻辑在哪里？如何运行检查？哪些内容不能改？只适用于单个工作流的规则应放在单独的 skill 中。

第二层是领域知识：针对重复任务的聚焦配方，例如 Android 导航迁移、数据库 schema 变更或发布清单。一个 skill 需要清晰的触发条件、简短步骤和明确验证。这样默认上下文保持小巧，专门知识只在需要时加载。

2. 围绕知识缺口编写 skill

好的 skill 存在的原因是模型反复犯错，或不断重新发现同一件事。Android Skills 的设计理念 提出一个有用判断：官方 skill 应解决可验证的模型知识缺口，尤其是 API 经常变化或团队使用自定义架构时。该文也提醒开发者从可信来源下载 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.

这个例子有意保持狭窄。它没有把完整框架手册粘进每个提示，而是说明何时适用、需要检查什么、边界是什么，以及如何证明完成。请将平台相关检查替换为仓库中真实存在的命令和约定。

3. 让代理先检查再行动

编码代理会将请求与环境上下文结合，基于上下文推理，然后执行编辑、测试和构建。这正是 AWS Prescriptive Guidance 描述的流程。你的指令应该把这些阶段明确写出来。

一个实用请求包含四部分：

1. 上下文： 说明功能、相关目录和限制。
2. 计划： 编辑前列出预计使用的文件和检查。
3. 变更： 要求满足验收标准的最小实现。
4. 证据： 要求提供支持结果的测试、lint、build 或手工检查。

这样可以避免代理从用户的一句话直接开始编码，之后才发现真实架构并用大范围重写来补救。检查不是仪式，而是代理获取决策所需环境上下文的方式。

4. 给代理一个紧凑的反馈循环

领域指导说明项目如何工作，可执行检查则说明变更是否真的有效。VS Code 当前的 TDD 指南 将流程分为 red（编写失败测试）、green（实现让测试通过的最少代码）和 refactor（保持测试通过并改善结构）。

不需要创建三个复杂代理。对于小任务，先要求一个失败测试或 characterization test；行为明确后再实现。最后运行聚焦测试和项目正常的质量门禁。如果检查无法通过，这说明需求或环境存在信息，而不是应该在自信的总结中隐藏失败。

5. 复查并淘汰指导

把 skill 当作有版本的工程基础设施。框架变化、代理重复犯错或检查变得嘈杂时，都应复查。Android Skills 指南 明确将 skills 视为可能被弃用的资产：模型会进步，旧指令会变得多余，而新 API 会产生新的缺口。

一个轻量维护循环：

• 保留一个会使用该 skill 的示例任务。
• 记录预期文件和验证命令。
• 修改 skill 或模型后重新运行。
• 删除模型已经不需要的指令。
• 让安全敏感操作保持显式、可选并可审查。

目标不是让代理听起来更专业，而是让正确行为更容易复现：简短的仓库契约、精准触发的领域流程，以及可执行的完成定义，共同形成从上下文到变更再到证据的路径。