skill-acceptor

name	skill-acceptor
version	1.0.0
description	专为 AI 代理设计的代码级验收与架构简报生成协议。在审查合并代码前使用，将复杂代码翻译为高度抽象的结构化大纲，并提供精准的代码锚点，彻底消除人类逐行阅读代码的负担。

Skill Acceptor

AI 生成代码的架构级透视与总结协议。绝对不要让人类去阅读未经消化的底层样板代码。

何时使用 (When to Use)

• 在 AI Agent（如 @task-tdd）刚写完一堆代码后
• 在审查或合并 AI 生成的 Pull Request (PR) 之前
• 当你需要快速了解“刚刚到底实现了什么业务逻辑”时
• 任何时候，当人类需要在脑海中建立代码库模型，而不想看源码时

验收提取协议 (Acceptance Protocol)

第一步：变更范围检查 (Step 1: Scope Check)

需要确认的信息：
- [ ] 这个功能的主要入口点在哪里？(如：具体哪个 API/Controller)
- [ ] 核心新增或修改了哪几个文件？
- [ ] 数据库表结构是否有变更？
- [ ] 是否引入了新的外部依赖或中间件？
- [ ] 有没有修改全局配置文件？

第二步：核心代码过滤 (Step 2: Code Filter - MANDATORY)

阅读所有变更文件。提取时必须排查以下违规项：

🚨 提取简报时严格禁止以下行为 (违规即重试)：
─────────────────────────────────────────
• 大段粘贴原始代码 (必须转译为人话)
• 解释基础语法 (如："这里定义了一个变量"、"使用了 for 循环")
• 陷入死循环、计算公式等底层数学细节
• 罗列未做实质性修改的无关文件
• 忽略了事务控制、Redis 锁、并发等关键架构要素
• 堆砌毫无重点的流水账
─────────────────────────────────────────

第三步：业务链路梳理 (Step 3: Logic Scope)

评估执行流：
- [ ] 这个功能的第一步操作是什么？(如：参数校验、鉴权)
- [ ] 核心流转涉及哪些服务或表？(串行还是并行？)
- [ ] 每个关键步骤对应在哪个文件、哪个函数中？(必须记录，方便人类一键定位)
- [ ] 数据是如何被持久化或处理的？(如：DB事务)
- [ ] 失败或报错时是如何给前端响应的？

第四步：逻辑复杂度评级 (Step 4: Complexity Classification)

复杂度级别	示例场景	提取动作
🟢 极简	样板代码、简单的 Getter/Setter	直接忽略，无需在简报体现
🟡 普通	标准 CRUD 操作、基础配置参数	一句话概括，避免流水账
🔴 复杂	核心业务流转、并发控制、复杂算法	重点提炼为 1-2-3 明确的执行步骤，附带代码锚点
⛔ 异常	降级兜底、超时重试、事务回滚	必须在“边界防御”中单独罗列说明

输出格式 (Output Format)

分析完毕后，必须严格输出以下控制台面板样式的简报：

代码验收简报 (ACCEPTANCE REPORT)
═══════════════════════════════════════
功能: [简述构建了什么功能]
入口: [如: OrderController.create()]
───────────────────────────────────────
📦 变更速览 (DIFF OVERVIEW):
• [文件名 1]: [一句话说明用途，如：新增支付路由]
• [文件名 2]: [一句话说明用途，如：增加事务注解]
• DB/依赖: [如：新增 orders 表 / 无]
───────────────────────────────────────
🧠 核心实现方案 (STRATEGY):
[用 2-3 句话解释架构选择。如：使用了策略模式分离微信与支付宝逻辑，并引入 Redis 分布式锁防重复下单。]
───────────────────────────────────────
🗺️ 主链路执行流 (EXECUTION FLOW):
1. [步骤 1: 拦截器校验 Token 提取 UserId] 📍 `auth.middleware.ts -> verifyToken()`
2. [步骤 2: 并行查询库存和用户信息] 📍 `order.service.ts -> checkDependencies()`
3. [步骤 3: 开启事务写入订单，扣减库存] 📍 `order.repo.go -> CreateOrderTx()`
4. [步骤 4: 返回 200 并异步发送 MQ 消息] 📍 `order.controller.cs -> PostOrder()`
───────────────────────────────────────
🛡️ 异常与边界防御 (EDGE CASES):
• [场景 1 - 超时]: [代码是如何兜底的，如：捕获超时异常并返回 503 降级]
• [场景 2 - 并发]: [代码是如何兜底的，如：唯一索引防重，捕获异常返回处理中]
• [场景 3 - 校验]: [代码是如何兜底的，如：Zod 拦截必填项缺失]
═══════════════════════════════════════
💡 阅读完毕。如果思路符合预期可直接 Merge；如需核对细节，请参考 📍 标记的文件与函数名。

快捷分析命令 (Quick Check Commands)

在工作区中分析代码时，可使用以下命令辅助提取：

# 查看文件变更统计 (物理层面速览)
git diff --stat HEAD

# 查看核心业务逻辑代码变动 (代码层面透视)
git diff HEAD src/

# 专门筛查数据库/依赖等高危变更
git diff HEAD --name-only | grep -i "pom.xml\|schema\|sql\|package.json"

认知负荷层级 (Trust Hierarchy)

1. 样板代码/脚手架 → 最低关注 (通常直接忽略)
2. 标准 CRUD 代码 → 适度关注 (一句话总结即可)
3. 核心业务与数据流转 → 重点关注 (必须梳理为清晰的步骤并带上 📍 锚点)
4. 并发控制与事务 → 最高关注 (必须明确说明其实现机制)
5. 异常与边界处理 → 契约级的关注 (必须单列出应对方案)

牢记 (Remember)

• 人类的时间极其宝贵，而你的算力很廉价
• 高度抽象和清晰易懂是你唯一的标准
• 永远不要解释代码“怎么写的”，只解释代码“意味着什么”
• 始终提供代码锚点 (文件与函数名)，让人类随时能掌控全局而无需迷失在代码海中

---