Feature List as Immutable Contract

长期运行的Agent在构建完整应用时会表现出几种失败模式：

• 过早宣告胜利：Agent仅实现部分需求后就宣称“完成”
• 通过删除测试引发范围蠕变：Agent通过删除或弱化测试而非修复代码来“通过”测试
• 幻觉式完整性：Agent无法追踪已实际实现内容与规划内容的差异
• 功能漂移：在缺乏固定规格说明的情况下，Agent可能会用较易实现的功能替代较难的功能
• 进度遗忘：在不同会话中，Agent会混淆已完成与待处理的内容

提前以结构化、不可变的格式定义所有功能，确保Agent可读取但无法恶意规避：

1. 全面功能规格说明

在启动任何实现工作前，创建包含所有必填功能的JSON文件：

{
  "features": [
    {
      "id": "auth-001",
      "category": "functional",
      "description": "新建聊天按钮可创建全新对话",
      "steps": [
        "点击侧边栏中的「新建聊天」按钮",
        "验证URL已更新为新的对话ID",
        "验证消息输入框为空且处于聚焦状态",
        "验证未显示任何历史消息"
      ],
      "passes": false
    },
    {
      "id": "auth-002",
      "category": "functional",
      "description": "用户可登出且会话将被清除",
      "steps": [
        "点击用户个人资料菜单",
        "点击「登出」选项",
        "验证页面重定向至登录页",
        "验证受保护路由无法访问"
      ],
      "passes": false
    }
  ]
}

2. 不可变性约束

通过prompt指令强制执行以下规则：

• 仅允许Agent在验证完成后设置passes: true
• 禁止Agent从列表中删除功能
• 禁止Agent修改验收标准/步骤
• 禁止Agent将功能标记为「不适用」

3. 验证要求

只有满足以下所有条件，才可将功能标记为通过：

• 功能实现已完成
• 人工或自动化测试确认所有步骤均通过
• Agent已实际使用该功能（而非仅编写代码）

graph TD
    A[已创建功能列表] --> B[所有功能：passes=false]
    B --> C{选择下一个功能}
    C --> D[实现功能]
    D --> E[测试功能]
    E --> F{所有步骤通过？}
    F -->|否| D
    F -->|是| G[设置passes=true]
    G --> H{还有更多功能？}
    H -->|是| C
    H -->|否| I[项目完成]

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style G fill:#fff9c4

创建高效的功能列表

• 复杂应用需涵盖100-200项以上功能
• 验收标准需具体化（聚焦可观测行为，而非实现细节）
• 按类别分组（功能性、UI、性能、安全性）
• 将边缘场景和错误处理作为独立功能纳入
• 以人工测试人员的验证视角来撰写功能描述

Prompt 执行规则

关键规则：
1. 严禁删除或修改 feature-list.json 中的任何功能
2. 严禁编辑“steps”或“description”字段
3. 仅允许将“passes”字段从 false 改为 true
4. 标记功能通过前必须实际完成测试
5. 若某项功能看似无法实现，需向用户咨询——不得跳过

验证工具

• 使用浏览器自动化工具（Puppeteer、Playwright）进行端到端（E2E）验证
• 以用户操作流程执行功能测试，而非仅依赖单元测试
• 标记功能通过时需留存验证证据（截图、日志）

优势：

• 借助明确的完成标准，避免过早宣告任务胜利
• 创建跨会话留存的不可变需求记录
• 使Agent的进度可量化（Y个功能中有X个通过验证）
• 消除“通过删除内容蒙混过关”的攻击向量
• 为增量式会话提供原生工作队列

劣势：

• 需要在功能规格定义上投入大量前期成本
• 不适用于探索性或研究导向的工作
• 可能遗漏在实现过程中发现的涌现式需求
• 格式僵化，无法适配需求变更
• 庞大的功能列表可能导致Agent的context过载

适用场景：

• 构建需求明确的完整应用程序时
• 涉及多轮Agent会话的项目
• 对Agent的可问责性有要求时
• 可复现工作流场景（多个相似项目复用相同功能列表）

规避场景：

• 探索性原型开发时
• 范围不明确的研究任务
• 小型单会话任务
• 需求快速迭代的场景