跳到主要内容

AI Coding

AI Coding 的目标是让模型在真实仓库中产生可运行、可验证、可审查的改动。一次完整任务通常会经过读取、定位、编辑、测试和差异审查，具体工具能力和授权方式则因产品而异。

下文用“修复用户登录后被错误重定向的 Bug”作为贯穿案例。

AI Coding 适合什么任务​

最容易取得稳定结果的任务，通常有明确范围和可执行验收，例如修复能复现的 Bug、增加小功能、补测试、重复性重构和文档同步。

以下任务需要更密集的人工判断：成功标准尚不清楚的架构决策，缺少测试的大范围改写，以及会影响生产数据、账号、权限或对外服务的操作。可验证性越低，任务就越应该被拆小。

准备一个可验证的小任务​

任务开始前，先写一份短契约：

目标：修复登录入口写入 session['return_to']、回调误读 session['next_path'] 的问题。
复现：访问 /login?returnTo=/settings，登录后被跳转到首页。
完成标准：新增 /settings 回跳测试和外部 URL 拒绝测试，相关测试通过，没有无关差异。
允许范围：登录路由、回调逻辑和对应测试。
禁区：不更新依赖，不改数据库，不部署。
验证：运行指定测试、全量测试和构建命令。

“帮我修一下登录”会把问题范围、正确行为和验收方式都留给模型猜测。任务契约不需要很长，但应让开发者和 Agent 可以用同一标准判断是否完成。

让 Agent 先理解仓库​

编辑前先读取与任务相关的项目说明、目录结构、测试和现有实现。仓库可以在 AGENTS.md 或目录内规则文件中记录：

  • 项目结构和模块边界。
  • 安装、测试、构建和格式化命令。
  • 命名、代码风格和文档约定。
  • 不可更改的生成物、数据和外部资源。
  • 完成前必须通过的质量门。

规则文件只保留跨任务稳定的约定。当前 Bug 的临时细节放在任务描述中，大日志和大文件按需读取，避免一次把整个仓库塞进上下文。详见上下文工程。

上下文工程：Invariant → Routing → Knowledge​

随着模型判断能力提高，项目上下文不应只增不减。Thariq 在总结 Claude Code 新一代模型实践时披露，Anthropic 对部分新模型删除了 Claude Code System Prompt 中超过 80% 的内容，而其编码评测没有观察到可测量损失。这是特定产品和模型上的内部结果，不能直接外推为“Prompt 越短越好”；更值得复用的是：定期验证历史约束是否仍然必要。(Thariq)

仓库级上下文可以分成三层：

Invariant
   ↓
Routing
   ↓
Knowledge / Skill / Reference

Invariant 只保存跨任务稳定且必须始终成立的硬约束，例如禁止修改生成物、必须执行的质量门、明确的安全和权限边界。能由测试、Lint、权限系统或 Harness 强制的规则，优先放进机器控制，而不是反复写成自然语言。

Routing 告诉 Agent “遇到什么任务去哪里找”，不复制知识本身。例如文档维护读取写作 Skill，前端任务读取设计约定，发布任务读取 Release Checklist。根规则文件因此可以保持很轻。

Knowledge / Skill / Reference 保存真正的领域知识、复杂流程、Rubric、测试、设计稿和实现参考，并按任务渐进加载。详细内容不因为“未来也许有用”就全部预置进 Context。

这也意味着 Context Duplication 是一种技术债。同一规则如果同时存在于 System Prompt、AGENTS.md、Skill 和 Tool Description，迟早会出现版本漂移和冲突。更稳的原则是：

One rule, one owner; reference it elsewhere.

FEEI.CN 当前让 AGENTS.md 作为 Agent 入口规则的单一来源；更细的任务知识通过路由进入独立 Skill，而不是复制到多个入口文件。

Interface 比示例更值得长期维护​

旧模型经常需要大量 Tool Call 示例；模型能力提高后，示例有时反而会把探索限制在示例覆盖的路径里。工具应该优先通过 Schema 表达语义：清晰的参数名、枚举、前置条件、返回状态和错误类型，让 Agent 能从接口本身理解可做什么。

示例仍然有价值，但应主要用于容易误解的边界行为，而不是替代接口设计。工具行为发生变化时，也只需要修改 Tool Contract，而不是寻找散落在多个 Prompt 中的调用范例。

从“提示步骤”转向“定义授权与成功”​

OpenAI 的 GPT-5.6 官方 Guidance 与 Claude 5 的方向高度一致：模型对用户意图的理解增强后，通常不需要把每一步操作都写进 Prompt；更应该明确 Domain Context、Hard Constraints、Approval Boundaries 和 Success Criteria。OpenAI 也建议减少重复指令和示例，并通过代表性 Eval 验证精简后的 Prompt，而不是假定“越短越好”。(OpenAI GPT-5.6 Model Guidance)

因此任务上下文可以进一步区分：

Goal / Intent
    ↓
Relevant Context
    ↓
Hard Constraints
    ↓
Autonomy & Approval Boundary
    ↓
Required Evidence
    ↓
Success Criteria

其中最容易被忽略的是 Autonomy Boundary。只写“需要时先问我”会让 Agent 在安全的本地读取、编辑和测试上反复暂停；完全不写又可能让 Agent 把“修复代码”外推成 Push、Deploy 或外部写入。更好的方式是明确：哪些低风险、可回滚、任务范围内的动作可以连续执行，哪些外部、破坏性、付费或扩大 Scope 的动作必须停在 Authority Gate。

这和前面的 Human-at-the-authority-boundary 是同一原则在 Prompt 层的实现：Prompt 不负责微观遥控 Agent，而负责定义它的自主空间和停止边界。

按任务形状选择 Model Loop 还是 Program Loop​

GPT-5.6 的 Programmatic Tool Calling 又补充了一个重要的 Harness 设计判断：并非每一个工具步骤都需要模型重新思考。对于过滤、Join、排序、去重、聚合、格式校验等有界且确定性的中间处理，可以让程序一次处理多个工具结果；如果每个结果都可能改变下一步语义判断、需要审批或最终必须保留原生证据，则应回到模型直接调用。(OpenAI GPT-5.6 Model Guidance)

可以把 Agent 执行拆成两种 Loop：

Model Loop：Observation → Judgment → Action

Program Loop：Input → Deterministic Transform → Structured Output

设计时问的不是“能不能让 Agent 调这个工具”，而是：

这一阶段是否真的需要新的模型判断？

如果不需要，就尽量下沉成程序、Schema、Query 或 Validator；如果需要，就保留 Model Loop，并让模型看到足够的原始证据。两者之间应有明确 Handoff，避免程序和模型重复完成同一工作。

这进一步强化了 Harness 的职责：让模型只处理需要判断的不确定性，把确定性尽可能固化成代码。

定期偿还 Prompt Debt​

项目规则、Skill 和 Prompt 都应该像代码一样接受删除。模型升级、工具能力增强、测试补齐或 Harness 获得新的确定性控制后，旧的自然语言规则可能已经变成冗余约束。

可以周期性检查：

  • 这条规则仍然防止真实失败吗？
  • 是否已经由测试、Schema、权限或工具本身保证？
  • 是否与另一处规则重复或冲突？
  • 删除后 Eval 是否退化？
  • 它属于全局 Invariant，还是应该下沉到特定 Skill？

上下文优化因此不是“把 Prompt 写得越来越完整”，而是持续寻找完成同样任务所需的最小充分上下文。

小步修改并持续验证​

一次可审查的循环是：

复现故障 → 定位最小原因 → 修改少量文件
      → 运行相关测试 → 检查差异 → 决定下一步

先在旧代码上运行回归测试，确认它因为任务契约中的预期差异而失败，而非环境、夹具或错误断言。修复后让同一测试通过，二者结合才能说明测试覆盖了目标故障。局部结果通过后，再运行任务契约要求的更广检查。

当故障原因与新证据冲突时，先更新判断，再继续编辑。长计划只是当前假设，不应在报错已经证明它失效后继续照做。

用差异、测试和运行结果验收​

验收时至少检查四类证据：

  • 需求证据：重现步骤已经得到预期行为。
  • 代码证据：差异只包含任务所需改动，没有覆盖用户的其他修改。
  • 自动验证：相关测试、静态检查和构建按任务契约通过。
  • 运行证据：界面、API 或完整流程在真实环境中表现正常。

工具退出成功只能证明那次调用满足了工具契约，任务完成仍要回到最初的验收标准。测试覆盖不足时，“全部通过”也可能是假成功。

前端任务需要可执行的设计上下文​

“做得好看一点”没有稳定验收标准。前端任务应说明对应的设计系统、目标视口、交互状态和视觉参考，并要求截图或自动化浏览器验证。

可执行的设计文件优先记录语义映射：主文字、辅助文字、背景和边框分别使用什么 token；组内、模块和页面区块使用什么间距；按钮、输入框和弹窗有哪些状态；文案、焦点、键盘导航和动效的边界是什么。规则越接近代码中的可执行选择，多次迭代越容易保持一致。

高风险操作必须暂停​

模型输出只是行动请求。删除或覆盖大量文件、安装未审查依赖、读取密钥、修改数据库、部署生产、推送代码和发送外部消息，都要根据仓库政策进行独立授权。完整控制循环见 Agent 架构基础，更系统的工作区约束见 Harness 工程。

任务失败时，保留已有工作，记录完整错误和当前差异，然后区分输入错误、环境失败、方案错误和权限拒绝。只重试暂时错误；方案已被证据否定时，缩小任务或重新规划。

把重复经验写回项目​

一次纠正只解决当前任务，反复出现的问题应转成自动检查或简短规则。例如：命令总是跑错，就修正项目文档；同类回归反复出现，就补测试或 lint 规则；一个复杂流程多次验证有效，再将它沉淀为 Skill。

只写入已验证、跨任务稳定的经验。临时报错、未确认猜测和一次性偏好留在任务轨迹中，避免让项目规则随着每次对话不断膨胀。