Using AI Agent for AI Coding with Typed Boundaries
Summary
适用范围：本文的 Skill、plan、todo 与历史检索名称仅表示职责或实现示例；按目标宿主和项目现有能力映射，不假定预装同名工具。所有建议服从当前授权与项目规则。
使用 AI Agent 做编程任务时，默认最佳实践不是“让 agent 自由写代码”，而是把任务不断收窄成可验证边界：先把自然语言需求压成规格和验收标准，再选择执行入口，再要求实现围绕 typed output、narrow tool surface、explicit dependency context 和 verification gate 展开。 Public boundary: this is a version-sensitive method guide. Examples do not prove that a profile, provider, tool or policy is deployed or authorized.
核心原则来自 [[typed-ai-agent-boundaries]]：模型仍然不确定，但可以让模型和工程系统之间的接口更确定。
Default workflow
1. Start with intent, then force a contract
先从已有请求和项目资料确认小 contract；范围清楚的小任务可直接执行，只有实质歧义才先澄清：
- 目标：这次到底要交付什么。
- 输入：用户、文件、API、数据源、环境变量来自哪里。
- 输出：必须返回什么结构、写入什么文件、暴露什么接口。
- 禁止项：不能访问什么、不能修改什么、不能猜什么。
- 验收：怎样证明完成。
推荐起手式：
把这个需求先压成实现 contract：目标、输入、输出、禁止项、验收标准、风险。不要开始改代码。2. Choose the AI Agent execution lane
先按任务性质选择执行入口，而不是默认让同一个 agent 扛所有事：
- 小范围解释、方案判断：当前 AI Agent session。
- 多文件修改、需要跑测试：AI Agent terminal + todo + verification。
- 需要隔离上下文且宿主支持的独立子任务：受控委派；否则顺序执行。
- 需要正式实现计划：
writing-plans/ plan page。 - 需要预提交质量检查：code review / requesting-code-review 类 workflow。
- 稳定重复流程：先验证，再考虑沉淀 skill；不要直接上 cron。
参考：[[ai-coding-agent-workflow-types]]。
3. Convert uncertain model output into typed artifacts
凡是 AI 输出会被程序消费，优先要求结构化：
- JSON schema / Pydantic model / TypedDict / dataclass。
- 明确字段含义和约束。
- 明确错误返回结构。
- 明确空值、缺省值和未知状态。
AI Agent 任务要求可以这样写：
如果 LLM 输出被程序消费，定义输出 schema 并校验类型与业务约束；JSON 解析成功不等于有效。优先复用现有校验能力，不为此默认新增 Pydantic。4. Treat tools as public APIs, not helper functions
任何给 agent 调用的工具都要窄：
- 一个工具只做一类动作。
- 参数类型明确。
- 返回值结构稳定。
- docstring 写清楚何时使用、限制、失败语义。
- 读操作和写操作分开。
- 高风险写操作必须有 dry-run / preview / approval gate。
AI Agent 任务要求可以这样写：
如果要新增 agent/tool 函数，把它当 public API 设计：类型提示、docstring、错误语义、权限边界和测试都要补齐。5. Inject dependencies; do not hide global state
涉及数据库、API client、文件系统、用户上下文、权限或租户信息时，禁止让实现偷偷读全局变量。应使用显式上下文对象传入。
实践要求：
- 依赖通过参数、context object、RunContext 或项目内等价模式注入。
- 测试能替换 fake / mock。
- 不把 API key 写进配置或代码。
- 权限、用户身份、数据范围必须作为显式输入。
这条适用于企业内网 AI 编程：agent 不应直接访问数据库；它应调用继承权限、可审计、返回 typed result 的窄工具。
6. Make verification mandatory and layered
完成不能只看 agent 自报。AI Agent 必须读回、运行、验证。
最低验证层：
- 静态检查：lint / type check / format check。
- 单元测试：覆盖 schema validation、tool boundary、dependency injection。
- 回归测试：bug fix 必须有失败先行或等价回归用例。
- 行为 smoke：跑一次真实入口或最小可复现命令。
- 安全检查：确认没有 secrets、越权访问、破坏性默认动作。
推荐结束语：
完成前请给出：修改文件、验证命令、验证结果、仍然未覆盖的风险。不要只说 done。Best-practice prompt templates
Implementation request
我要用 AI Agent 实现这个功能：<需求>。
先不要写代码。请先输出：
1. scope / non-scope
2. typed input/output contract
3. tool/API boundary
4. dependency injection plan
5. tests and verification gates
6. files likely to change
等我确认后再执行。Code modification request
按已确认 contract 修改代码。
要求：
- 先读现有实现和测试；不要凭空新建架构。
- LLM/agent 输出必须有 schema 或 typed model。
- 外部依赖必须显式注入，不能藏全局状态。
- 新增工具函数必须有类型提示、docstring、错误语义和测试。
- 完成后运行 lint/type/test/smoke，并报告证据。Review request
请按 typed-boundary 视角 review 这次改动：
- 是否仍依赖自然语言格式解析？
- schema 是否足够表达业务约束？
- tool surface 是否过宽？
- 是否有隐藏全局状态？
- 权限/审计/错误语义是否明确？
- 测试是否覆盖 validation failure 和工具失败？Decision checklist
开始前问：
- 这个需求是否能用一句 contract 表达？不能则先拆。
- 这个输出是否会被程序消费？是则必须 typed。
- 这个工具是否可能产生副作用？是则必须 preview / approval / audit。
- 这个依赖是否和用户、权限、租户、环境有关？是则必须显式注入。
- 这个任务是否需要依赖跟踪或上下文隔离？按需使用现有 todo / plan / subagent，不因跨文件就自动升级。
- 这个流程是否已经重复且跑顺？是才考虑 skill；否则只写 wiki/query 或项目计划。
Anti-patterns
- 直接让 AI Agent “帮我写一个 agent”，但没有输入输出 contract。
- 让 LLM 返回一段自然语言，再用正则从里面抠字段。
- 一个 tool 同时查询、修改、删除、推理，且没有权限边界。
- 在工具函数里偷偷读取全局数据库连接、全局用户、全局环境。
- 只让 agent 自测，不读回 diff、不跑测试、不做 smoke。
- 把一次项目里的临时写法直接沉淀成 skill 或 memory。
Promotion path
这页作为 AI Agent 编程方法查询页。只有当这些规则在真实项目中反复跑通后，才进一步拆成：
- skill：例如“AI Agent typed-boundary coding workflow”。
- project template：Python 项目中的 agent contract / Pydantic model / tool boundary 模板。
- code review checklist：专门检查 LLM 输出、tool surface、dependency injection。
当前不直接创建 skill，因为最佳实践还需要在真实项目中验证。
Relations
- depends_on: typed-ai-agent-boundaries
- depends_on: hermes-ai-workflow-formalization-principles
- depends_on: ai-coding-agent-workflow-types
- depends_on: hermes-context-layer-operating-rules