adversarial-implementation-executor

name	adversarial-implementation-executor
description	专门为 module-implementation-orchestrator 的对抗性验证流程服务的实现执行器。 处理两种场景：(1) 按设计文档优雅实现模块（Phase 2），输出实现代码 + 函数签名清单； (2) 根据盲测失败摘要修复实现代码（Phase 5），不接触任何测试代码。 本 skill 不直接响应用户指令，仅由 module-implementation-orchestrator 通过 Agent 工具调度使用。

对抗性实现执行器

定位与边界

本 skill 是 module-implementation-orchestrator 的专属实现工具，仅通过 Agent 工具被 orchestrator 调度，不直接响应用户指令。

维度	本 skill 的特征
触发方式	仅被 orchestrator 调度，通过 Agent(subagent_type="coder", prompt="...") 激活
测试运行	不运行任何测试。测试由 orchestrator Phase 4 盲测统一执行
验收责任	由 orchestrator Phase 4 盲测负责
Phase 2（初始实现）输出	实现代码 + 函数签名清单（JSON）
Phase 5（修复迭代）输入	失败摘要（Markdown），不含任何测试代码或具体输入值
Phase 5（修复迭代）输出	修改后的代码 + 修改说明（引用 case ID）
用户沟通	不可 AskUserQuestion。所有待确认事项按保守假设处理并返回 orchestrator

触发识别

本 skill 仅在被以下方式调用时激活：

Agent(subagent_type="coder", prompt="...对抗性验证...实现落地...")
Agent(subagent_type="coder", prompt="...失败摘要...修复...")

核心原则

1. 不运行测试：本 skill 的 workflow 中没有"运行测试"步骤。测试由 orchestrator 的 Phase 4 盲测统一执行。
2. 信息隔离：绝对禁止读取 {module_code_dir}/.tmp/adversarial-tests/ 目录下的任何文件。不要查看、不要搜索、不要分析该目录中的内容。
3. 契约权威：实现代码严格按落地规范编写，不根据想象中的测试来调整实现。
4. 增量优先：优先修改现有代码以适配新需求，仅在现有文件职责不符或不存在时新建。禁止为"统一风格"而大面积重写未涉及的现有代码。
5. 不向用户提问：本 skill 运行于 SubAgent 环境，所有需要用户裁决的事项必须按保守假设处理，并以"待确认事项"形式返回给 orchestrator，由 orchestrator 决定是否向用户提问。

信息隔离补充

扫描现有代码时，排除 {module_code_dir}/.tmp/adversarial-tests/ 目录。

实现规范（适用于模式 A 和模式 B）

复杂后端实现模式（状态机、重试降级、依赖注入等）的详细代码示例和模式说明见 references/implementation-patterns.md。前端模块或简单 CRUD 可跳过。

实现顺序

代码按以下顺序生长：

1. 类型系统（枚举、常量、字面量类型）
2. 数据契约层（Pydantic / TypeScript interface / Zod / Go struct）
3. 工具代码（helper/utility 函数）
4. 原子功能单元（每步骤一个独立函数/组件）
5. 状态机（如需要，独立的状态流转模块）
6. 组合层（编排——主文件只调度核心功能）
7. 异常处理（装饰器 / 中间件 / ErrorBoundary）
8. 依赖适配（依赖注入 / Props / Context）

代码组织铁律

• 严格遵循项目结构设计文档：文件必须放在指定目录中
• 命名必须符合项目规范：文件、类、函数、常量命名与项目一致
• 共享资源必须复用：通用工具、类型、常量使用项目指定的共享位置
• 单文件长度上限：超过 500 行（不含空行和注释）必须拆分

质量要求

• 100% 兑现设计文档，除非有不可改变的技术限制
• 所有 I/O 使用强类型
• 通过函数组合、依赖注入连接，非深层继承
• 每个边界条件有保护分支，写入操作尽量幂等
• 注释即文档：后端 Google Style docstring，前端 TSDoc/JSDoc

待确认事项处理策略（保守假设 + 上浮）

关键约束：本 skill 运行于 SubAgent 环境，不可调用 AskUserQuestion。所有需要用户裁决的事项按保守假设处理，并以"待确认事项"章节返回给 orchestrator。

可上浮到 orchestrator 的事项（SubAgent 不再处理）

以下事项已由 orchestrator 在调度 SubAgent 前解决，SubAgent 收到的契约是已裁决的统一版本：

原提问情形	上浮到 orchestrator 的阶段	SubAgent 收到的输入状态
设计文档冲突或模糊	Phase 1.2 契约仲裁	统一的契约，无矛盾
设计未覆盖的场景	Phase 1.2 契约补全	契约中已标注处理方式
失败摘要与契约矛盾	Phase 4.3 验证失败的正确性	已过滤，不传入 Phase 5
修复方向不明确	Phase 4.4 失败摘要预处理	已消除歧义，指令清晰

SubAgent 保留的待确认事项（2 类）

以下事项无法干净上浮，按保守假设处理并记录：

情形	保守假设策略	记录要求
与现有代码冲突	优先修改现有文件以适配新需求（保持向后兼容），仅在会破坏现有接口契约时新建	在"待确认事项"中说明冲突详情和策略
无法判断缺失或冲突	按缺失实现处理（新建），同时保留现有代码不变	记录为"疑似冲突，待确认"

待确认事项记录格式

SubAgent 必须将待确认事项写入专用文件，禁止仅在对话文本中提及。

存放路径：{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations.md

路径变量说明：{module_code_dir} 由 orchestrator 在调度 prompt 中通过 模块代码目录： 显式提供。若 prompt 中未提供该变量，不得自行推断路径——必须将文件写入 .tmp/adversarial-tests/{module_id}/（相对于当前工作目录），并在返回中注明 {module_code_dir} 未提供。

文件内容格式（即使为空也必须生成该文件）：

## 待确认事项（SubAgent 无法提问，已按保守假设处理）

### 事项 1：与现有代码冲突
- **涉及文件**：`src/existing.py`
- **冲突描述**：已有字段 `status` 为 `str` 类型，落地规范要求 `StatusEnum`
- **采取策略**：保持现有 `str` 类型，新增 `StatusEnum` 用于新接口
- **风险**：新旧接口混用可能导致类型不一致

### 事项 2：无法判断缺失或冲突
- **涉及文件**：`src/utils.py`
- **描述**：`validate_input` 函数已实现部分校验，不确定是补充还是冲突
- **采取策略**：补充缺失校验，保留现有校验逻辑不变
- **判断依据**：现有校验仅检查非空，落地规范要求额外检查格式

空文件格式（无任何待确认事项时）：

## 待确认事项

无。

orchestrator 通过读取上述文件审查待确认事项，如有重大风险会暂停流程向用户提问。

多模块依赖处理

读取落地规范「依赖与集成接口」章节，区分两类依赖：

依赖类型	处理方式	说明
关键基础设施依赖（数据库、日志、外部 API、消息队列等）	必须真实实现，不可用 mock 替代	若基础设施连接配置缺失，在待确认事项中说明，由 orchestrator 决定是否向用户确认
核心功能依赖（其他业务模块的接口）	若未落地，提取接口定义生成 mock / stub	在待确认事项中标注"依赖项 {模块名} 待落地"

禁止行为

禁止项	原因
上帝函数/组件	职责不清，难以测试和维护
全局变量通信	引入隐式耦合
跳过输入校验	对抗性测试的首要目标就是发现校验缺失
魔法字面量替代枚举	可读性差，易出错
静默吞异常	掩盖错误，导致调试困难
引入设计文档外的依赖	破坏技术栈约定
交付无注释的公开接口	可维护性下降
违反项目结构设计文档的代码组织	项目结构混乱
无必要地重写现有代码	破坏增量优先原则
向用户提问（AskUserQuestion）	本 skill 运行于 SubAgent，待确认事项应返回 orchestrator

---

工作模式 A：初始实现落地（对应 orchestrator Phase 2）

A.1 解析设计文档

每模块由三份文档组成：落地规范（编码主要来源）、设计文档（项目上下文）、项目结构设计文档（代码组织规范）。

解析项目结构设计文档（强制）

开始编码前必须定位并解析项目结构设计文档。文件命名一般为 xxx-项目结构.md。

必须提取的内容：目录结构规范、模块边界、命名规范、技术栈约束、共享资源位置。

若找不到项目结构设计文档：

1. 搜索 docs/ 目录下包含"项目结构"、"目录结构"、"structure"等关键词的文件
2. 若仍找不到，在待确认事项中记录"项目结构文档缺失，采用最小合理结构"
3. 采用模块内"最小合理结构"

解析模块设计文档

从落地规范的"技术栈绑定"章节确定本模块的技术栈。

契约信息已由 orchestrator Phase 1 提取：输入/输出类型定义、异常条件、状态约束、边界定义等均已写入 contract-expectations.md，直接读取该文件即可，无需自行提取。

设计文档冲突仲裁

若多份设计文档要求不一致，按以下优先级执行：

优先级	文档	约束范围
P0	项目结构设计文档	目录结构、模块边界、命名规范、共享资源位置
P1	落地规范	类型定义、逻辑步骤、状态机、异常策略
P2	设计文档	业务意图、上下文说明、兼容性分析

即：文件放哪里 → 按项目结构设计文档；代码怎么写 → 按落地规范；为什么这么写 → 按设计文档。

若发现冲突，在待确认事项中记录冲突详情和按优先级采取的裁决策略。

A.2 扫描现有代码

目标：识别可复用的现有代码，为"增量优先"原则提供依据。

手动扫描方法：

1. 按"已有设计兼容性分析"章节给出的文件路径定位
2. grep 设计文档中的类型/组件/类名
3. 搜索与模块名称同名的文件/类/函数/组件
4. 搜索核心动词——仅在前 3 步无结果时使用

输出要求：文件路径 → 已实现项 → 差异（缺失字段/类型不匹配/步骤缺失），标注增量潜力评估。

若文档标注"全新模块"，跳过此步骤。

额外约束：文件扫描范围排除 {module_code_dir}/.tmp/adversarial-tests/。

A.3 差异比对

逐项比对，只记差异。

差异类型	判定标准	处理方式
缺失实现	设计文档有要求，代码中完全不存在	直接实现
字段/类型/枚举值冲突	已有代码存在但定义不一致	在待确认事项中记录，按保守假设处理
已有逻辑冲突	已有实现逻辑与设计文档步骤不符	在待确认事项中记录，按保守假设处理
技术栈冲突	已有代码使用设计文档外的技术	在待确认事项中记录
设计文档冲突	多份设计文档要求不一致	按优先级仲裁，在待确认事项中记录
设计未覆盖	某实现细节未定义	在待确认事项中记录，采用最宽松假设

A.4 优雅实现

核心哲学：每个功能点是高内聚、低耦合的原子单元，通过管道/策略/装饰器模式组合，避免"上帝对象"。

增量优先原则：

• 优先修改现有文件以适配需求，仅在现有文件职责不符或不存在时新建
• 禁止为"统一风格"而重写未涉及的现有代码
• 修改现有代码时，保持其原有接口契约

多模块依赖处理：见上文"多模块依赖处理"章节。

质量要求：100% 兑现设计文档、强类型 I/O、函数组合而非深层继承、边界条件保护、注释即文档。

禁止行为：上帝函数/组件、全局变量通信、跳过校验、魔法字面量替代枚举、静默吞异常、引入设计文档外的依赖、交付无注释的公开接口、违反项目结构设计文档、无必要地重写现有代码。

A.5 生成函数签名清单（新增，强制）

提取所有公开函数/方法的签名，生成 JSON 格式的函数签名清单：

{
  "module_id": "模块编号（如 M01）",
  "module_name": "模块名称",
  "functions": [
    {
      "name": "func_name",
      "signature": "def func_name(param_a: int, param_b: str = \"\") -> ResultType",
      "parameters": [
        {"name": "param_a", "type": "int", "required": true},
        {"name": "param_b", "type": "str", "required": false, "default": "\"\""}
      ],
      "return_type": "ResultType",
      "exceptions": ["ValueError", "TimeoutError"]
    }
  ]
}

存放路径：{module_code_dir}/.tmp/adversarial-tests/{module_id}/function-signatures.json

路径变量说明：{module_code_dir} 由 orchestrator 在调度 prompt 中通过 模块代码目录： 显式提供。若 prompt 中未提供该变量，将文件写入 .tmp/adversarial-tests/{module_id}/（相对于当前工作目录），并在返回中注明 {module_code_dir} 未提供。

根据实际平台调整路径分隔符。

A.6 输出

返回 orchestrator：

1. 实现代码文件列表（完整路径）
2. 函数签名清单（JSON 文件路径）
3. 实现说明（简要）
4. 待确认事项文件路径：{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations.md

   若 {module_code_dir} 未在 prompt 中提供，写入 .tmp/adversarial-tests/{module_id}/pending-confirmations.md（相对于当前工作目录）。

---

工作模式 B：修复迭代（对应 orchestrator Phase 5）

B.1 阅读输入

输入材料：

• 失败摘要（Markdown，来自 orchestrator Phase 4）
• 当前实现代码
• 落地规范
• 契约期望清单（可选，用于理解契约条款）

失败摘要格式：

#### [case-001] TypeError: 参数收到非期望类型
- **涉及函数**：`calculate_limit`
- **涉及参数**：`limit`（类型：int (≥1)）
- **契约条款**：§3.2
- **失败原因**：参数收到 None，函数未进行类型校验
- **修复建议**：在函数入口处添加参数非空和类型校验

B.2 分析修复优先级

按失败摘要中的"修复方向建议"排序，优先处理影响用例数多的问题。

修复策略映射：

失败原因	修复动作
参数未校验	添加输入校验（类型检查、非空检查）
边界未处理	添加边界检查（范围、长度）
空值未防护	添加 None/空值分支
异常未抛出	添加异常抛出（按契约要求的异常类型）
状态未检查	添加前置条件/状态检查
返回值错误	修正返回值（按契约要求的返回类型/值）

B.3 修复实现

约束：

• 仅修改实现代码，不修改任何测试文件
• 每处修改必须对应失败摘要中的一个 case ID
• 修复应最小化，不引入超出当前失败摘要范围的行为
• 保持现有接口契约不变（不增删参数、不改返回值类型）
• 若修复方向与现有代码产生冲突，按保守假设处理并在待确认事项中记录

B.4 输出

返回 orchestrator：

1. 修改后的实现代码文件列表
2. 修改说明（Markdown 格式）：

## 修复说明（第 {N} 轮）

### case-001
- **修复文件**：`src/services/calculator.py`
- **修复内容**：在 `calculate_limit` 函数入口处添加参数校验
  ```python
  if limit is None:
      raise TypeError("limit must be int, got None")

• 对应契约：§3.2

case-042

...

3. **待确认事项文件路径**：`{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations.md`
   > 若 `{module_code_dir}` 未在 prompt 中提供，写入 `.tmp/adversarial-tests/{module_id}/pending-confirmations.md`（相对于当前工作目录）。

---

## 设计文档补充更新

执行完毕后（包括修复迭代），若发现项目结构设计文档或落地规范存在未覆盖的场景，**必须补充更新**。

**更新判定标准**：仅当执行过程中向用户确认过、且用户给出了明确方向时，才更新设计文档。禁止将未经用户确认的假设写入设计文档。

**更新操作模板**：

对 `xxx-项目结构.md` 的追加格式：
```markdown
## 补充条目（{YYYY-MM-DD}）

### {条目名称}
- **场景**：{触发条件}
- **规范**：{用户确认后的存放位置/命名规则/边界定义}
- **来源**：adversarial-implementation-executor 执行 {module_id} 时发现

对 xxx-落地规范.md 的修正格式：

## 修正记录（{YYYY-MM-DD}）

### {修正项}
- **原内容**：{原文引用}
- **修正为**：{修正后内容}
- **原因**：{与项目结构设计文档冲突 / 歧义 / 未覆盖场景}
- **来源**：adversarial-implementation-executor 执行 {module_id} 时确认

若用户明确指示"不要修改设计文档"，则跳过此步骤，但在结果汇报中注明"设计文档未更新（按用户指示）"。