Develop

开发实施 - 详细规则

目标: 按方案包中任务清单执行代码改动，同步更新知识库，迁移到 history/

前提: plan/ 目录中存在待执行的方案包

备份保护: 执行前建议创建 Git 备份分支或手动备份代码目录

强制前置检查

开发实施的唯一合法条件（满足任一即可）：

条件A - 方案设计完成后确认:
  验证方法: 会话历史中上一条AI输出为方案设计完成 且 当前用户输入为明确确认

条件B - 全授权命令:
  验证方法: MODE_FULL_AUTH状态=true

条件C - 执行命令:
  验证方法: MODE_EXECUTION状态=true

验证失败处理：

IF 不满足任何条件:
  输出: "❌ 路由错误: 进入开发实施需满足前置条件。当前条件不满足，已重新路由。"
  执行: 将当前用户消息按路由优先级重新判定
  终止: 开发实施流程

执行步骤

重要: 所有文件操作遵循G5静默执行规范

步骤1: 确定待执行方案包

全授权命令(MODE_FULL_AUTH=true):
  - 读取CREATED_PACKAGE变量（方案设计阶段设置的方案包路径）
  - 检查该方案包是否存在且完整
    - 存在且完整 → 使用该方案包，设置CURRENT_PACKAGE = CREATED_PACKAGE
    - 不存在或不完整 → 按G6.2输出错误格式并停止
  - 忽略plan/中的其他遗留方案包

交互确认模式/执行命令(MODE_EXECUTION=true):
  - 扫描plan/目录下所有方案包
  - 不存在方案包 → 按G6.2输出错误格式并停止
  - 方案包不完整 → 按G6.2输出错误格式并停止
  - 单个完整方案包 → 设置CURRENT_PACKAGE，继续执行
  - 多个方案包 → 列出清单，等待用户选择
    - 用户输入有效序号(1-N) → 设置CURRENT_PACKAGE，继续执行
    - 用户输入取消/拒绝 → 按G6.2输出取消格式，流程终止
    - 无效输入 → 再次询问

异常输出示例:
  方案包不存在:
    ```
    ❌【HelloAGENTS】- 执行错误

    错误: 未找到可执行的方案包
    - 原因: plan/目录为空或不存在

    ────
    🔄 下一步: 请先使用 ~plan 命令创建方案，或进入方案设计阶段
    ```

  方案包不完整:
    ```
    ❌【HelloAGENTS】- 执行错误

    错误: 方案包不完整
    - 方案包: [方案包名称]
    - 缺失文件: [why.md/how.md/task.md]

    ────
    🔄 下一步: 请补充缺失文件或重新创建方案包
    ```

步骤2: 检查知识库状态并处理

执行方式:

• 按 G10 快速决策树判定
• 如需创建/重建知识库 → 读取 ../kb/SKILL.md 执行完整流程

步骤3: 读取知识库并获取项目上下文

执行方式:

• 按 G10 快速流程执行（先检查知识库 → 不足则扫描代码库）
• 如需详细规则 → 读取 ../kb/SKILL.md

步骤4: 读取当前方案包

读取 plan/YYYYMMDDHHMM_<feature>/task.md 和 why.md

步骤5: 按任务清单执行代码改动

执行规则:
  - 严格按 task.md 逐项执行

任务成功处理:
  - 每个任务执行成功后，立即将状态从 [ ] 更新为 [√]

任务跳过处理(状态更新为 [-]):
  - 任务依赖的前置任务失败
  - 任务条件不满足
  - 任务已被其他任务的实现覆盖

任务失败处理(状态更新为 [X]):
  - 记录错误信息（用于迁移前添加备注）
  - 继续执行后续任务
  - 所有任务完成后，如存在失败:
    - 交互确认模式/执行命令: 列出失败清单，询问用户决定
      - 用户选择继续 → 继续后续步骤
      - 用户选择终止 → 输出"已终止开发实施"，流程终止
    - 全授权命令: 在总结中列出失败任务，清除MODE_FULL_AUTH状态

代码编辑技巧:
  - 大文件处理(≥2000行): Grep定位 → Read(offset,limit) → Edit精确修改
  - 每次Edit只修改单个函数/类

步骤6: 代码安全检查

检查内容:

• 不安全模式（eval、exec、SQL拼接等）
• 敏感信息硬编码
• EHRB风险规避

步骤7: 质量检查与测试

测试执行: 运行task.md中定义的测试任务，或项目已有测试套件

测试失败处理规则（严格执行）:
  ⛔ 阻断性测试（核心功能）:
    - 失败必须立即停止执行
    - 输出关键错误格式
    - 等待用户明确决策（修复/跳过/终止）
    - 禁止自动跳过

  ⚠️ 警告性测试（重要功能）:
    - 失败时在总结中标注
    - 继续执行后续步骤

  ℹ️ 信息性测试（次要功能）:
    - 失败时在总结中记录
    - 继续执行后续步骤

⛔阻断性测试失败输出格式:

❌【HelloAGENTS】- 阻断性测试失败

⛔ 核心功能测试失败，必须处理后才能继续:
- 失败测试: [测试名称]
- 错误信息: [错误摘要]

[1] 修复后重试 - 尝试修复问题后重新测试
[2] 跳过继续 - 风险自负，忽略此错误继续执行
[3] 终止执行 - 停止开发实施

────
🔄 下一步: 请输入序号选择

步骤8: 同步更新知识库

重要: 必须在步骤12迁移方案包前完成方案包内容读取

执行方式: 读取 ../kb/SKILL.md 执行完整知识库同步规则

步骤9: 更新 CHANGELOG.md

按G7版本管理规则确定版本号

步骤10: 一致性审计

审计内容:

1. 完整性: 文档涵盖所有模块，必备文件和图表齐全
2. 一致性: API/数据模型与代码一致，无遗漏、重复、死链

真实性优先级（冲突解决机制）:

1. 代码是执行真实性的唯一来源 (Ground Truth)
   → 运行时行为、API签名、数据结构以代码为准

2. 默认修正方向: 修正知识库以符合代码
   → 发现不一致时，必须更新文档以反映代码的客观事实

3. 例外（修正代码）:
   - 知识库是最近P2/P3方案包（刚设计好的方案）
   - 代码有明显错误（Bug）
   - 错误信息指向代码问题

4. 存疑时: 双向验证，优先信任最近的代码变更

步骤11: 代码质量检查（可选）

执行内容: 分析代码文件，识别质量问题

如发现问题:
  交互确认模式:
    - 输出优化建议询问格式
    - 用户确认 → 执行优化、更新文档、重测
    - 用户拒绝 → 跳过优化，继续后续步骤
  全授权命令/执行命令:
    - 在总结中列出建议（不执行）

提交关联: 如需提交，按项目规范执行

代码质量优化建议询问格式:

❓【HelloAGENTS】- 代码质量

发现以下可优化项:
1. [优化建议1] - [影响范围/文件]
2. [优化建议2] - [影响范围/文件]

[1] 执行优化 - 应用上述优化建议
[2] 跳过 - 保持现状，继续后续步骤

────
🔄 下一步: 请输入序号选择

步骤12: 迁移已执行方案包至history/

⚠️ CRITICAL - 强制执行规则:

不可跳过: 此步骤为本阶段结束的原子性操作

执行规则:

1. 更新task.md任务状态和备注:

   • 所有任务更新为实际执行结果（[√]/[X]/[-]/[?]）
   • 非[√]状态任务下方添加备注（格式: > 备注: [原因]）
   • 如有多个失败/跳过任务，可在末尾添加执行总结章节

2. 迁移至历史记录目录:

   • 将方案包目录从 plan/ 移动到 history/YYYY-MM/ 下
   • YYYY-MM 从方案包目录名提取（如 202511201200_xxx → 2025-11）
   • 迁移后完整路径: history/YYYY-MM/YYYYMMDDHHMM_/
   • 迁移操作会自动删除 plan/ 下的源目录
   • 同名冲突处理: 强制覆盖 history/ 中的旧方案包

3. 更新历史记录索引: history/index.md

警告: 此操作将导致 plan/ 下的源文件路径失效，请确保步骤8已完成内容读取 不可跳过: 此步骤为本阶段结束的原子性操作

代码规范要求

规范要求:

• 文件顶部注释: 导入语句前，项目现有注释风格，1-3句话说明模块用途
• 所有代码注释: 必须用{OUTPUT_LANGUAGE}生成
• 代码风格: 遵循项目现有命名约定和格式规范

开发实施 输出格式

⚠️ CRITICAL - 强制要求:

• ALWAYS使用G6.1统一输出格式
• NEVER使用自由文本替代规范格式
• 输出前MUST验证格式完整性

等待用户选择方案包时（步骤1多方案包）

❓【HelloAGENTS】- 开发实施

检测到多个方案包，请选择执行目标:

[1] YYYYMMDDHHMM_<feature1> - [概要描述]
[2] YYYYMMDDHHMM_<feature2> - [概要描述]
[3] YYYYMMDDHHMM_<feature3> - [概要描述]

────
🔄 下一步: 请输入方案包序号(1/2/3)

阶段完成时

严格调用 G6.1 统一输出格式，填充以下数据：

1. 阶段名称: 开发实施
2. 阶段具体内容(≤5条要点):
   • 📚 知识库状态
   • ✅ 执行结果: 任务数量和状态统计
   • 🔍 质量验证: 一致性审计、测试结果
   • 💡 代码质量优化建议（如有）
   • 📦 迁移信息: 已迁移至 history/YYYY-MM/YYYYMMDDHHMM_<feature>/
3. 文件变更清单:

   📁 变更:
     - {代码文件}
     - {知识库文件}
     - helloagents/CHANGELOG.md
     - helloagents/history/index.md
     ...
   

4. 下一步建议: "请确认实施结果是否符合预期?"
5. 遗留方案提醒: 按G11扫描 plan/ 目录，如有遗留方案包则显示

阶段转换规则

完成所有动作后:
  交互确认模式: 输出总结 → 开发实施结束
  全授权命令: 输出整体总结 → 流程结束
  执行命令: 输出整体总结 → 流程结束
  变量清理: CURRENT_PACKAGE将在遗留方案扫描时自动清理(按G11规则)

异常情况（测试失败/用户提出问题）:
  交互确认模式: 在输出中标注，等待用户决定
  全授权命令/执行命令: 在总结中标注测试失败，流程正常结束
  后续用户消息按路由优先级处理