不止是写代码｜研发如何用 SKill 驱动业务缺陷检测

picture.image

本文作者：易柏胜，TRAE 开发者用户

本文最后有详细的 Skills，大家可以自行取用。

picture.image

前言

如何将资深测试专家的“质量思维”无缝传递给一线业务研发，让 Bug 在写代码那一刻就被拦截，而不是等到提测甚至上线后才引爆？

在回答这个问题前，我们需要先界定一下“缺陷”的本质。在研发实战中，缺陷通常分为两类：

通用缺陷（硬知识）： 它是代码层面的“硬伤”，如空指针异常、SQL 注入、内存泄漏或不符合编程规范的命名。这类问题有标准答案，静态扫描工具（SonarQube 等）已经做得很好。
业务缺陷（软知识）： 它是结合具体业务场景的“逻辑漏洞”，比如“在促销活动结束前，订单状态机是否允许直接跳转至退款”或“VIP 用户的权益计算是否遗漏了新规则”。这类问题高度依赖上下文，传统的静态工具对此无能为力。

目前的痛点在于，针对“业务缺陷”的质量平台大多游离在 IDE 之外：规范在文档里、规则在脑子里、开发却在编辑器中。大家虽知晓规范，但没人会在写代码的心流时刻频繁切屏去翻阅几百页的业务文档。

基于这个痛点，本文利用SOLO 模式 + 自定义 Agent Skills 做了一次探索：把复杂的质量检测能力拆成一个个可复用的「原子化研发技能」，让每个开发在写代码时，都能随手召唤一位“虚拟质量专家”。

通过在 IDE 内编排 5 个 Agent Skill，我们把从需求理解、技术方案对齐，到代码变更分析、缺陷判定和修复建议的完整链路自动化串联起来。

这意味着，每位开发者在写代码时，都随时有一位懂业务、懂代码的“虚拟质量专家”在侧，让高危业务缺陷在提测前即刻暴露。

实战数据表明，这种方式显著提升了研发的主动质量意识与缺陷拦截效率。

picture.image

如何让质量能力“住”进 IDE？

作为开发者，我们 90% 的时间都沉浸在 IDE 里构建逻辑、调试堆栈。然而，决定代码正确性的“依据”却散落在 IDE 之外的信息海洋中。

研发体验的断层

需求碎片化： 核心逻辑可能藏在飞书文档的某个批注里，或者 PRD 的第 5 次变更记录中。
知识隐性化： 很多历史业务规则并不在文档里，而是在 Wiki 的角落，甚至存在于已经离职的老员工的口口相传中。
反馈滞后性： 传统的质量检测往往发生在代码提交之后。你得等待 CI 流水线跑完，去 Jenkins 或 Sonar 平台查看几百行日志，才能发现一个逻辑漏洞。此时，你早已切换到下一个任务，这种“异步反馈”极大地拉高了修复成本。

这种割裂带来的直接后果是极高的上下文切换成本。

在真实的编码场景中，很少有人能做到每写一行代码就切屏去翻阅文档或咨询产品经理。当 Deadline 逼近，面对模糊的业务边界，人性使然的选择往往是：

“这个特殊的退款逻辑好像在哪里见过，但现在去翻聊天记录太断片了，凭经验应该是这样写吧……”

许多线上故障并非源于技术能力的匮乏，而是源于认知负荷的超载。当获取“正确规则”的成本过高时，由于缺乏 IDE 内实时的辅助，Bug 便在指尖敲击键盘的那一刻，悄无声息地成为了系统的一部分。

SKill 带来的契机

Agent Skill 机制让我们看到了破局的希望：如果能把质量专家的知识封装成 Skill，直接装进 IDE 里，岂不是就能让研发人员拥有一位“随叫随到的质量专家”？利用 TRAE 的能力，为业务研发提供一套轻量、即时、嵌入式的“质量辅助插件”。

picture.image

设计核心思路：将“专家经验”转化为“Agent Skill”

我们没有从零搭一个新平台，而是基于 TRAE 的 SOLO 模式，把资深 QA 和架构师沉淀多年的经验，拆解成 5 个标准化 Skill。它们聚焦解决研发最常问、也最容易出问题的三个灵魂拷问：

需求到底要什么？
系统是怎么实现的？
我这次改动有没有漏？

如何设计 Skill

我们把质量检测链路拆成研发在 IDE 内可以单独调用的「原子能力」，每个 Skill 都只负责一件事。

picture.image

Skills 使用示例

在研发提交代码代码前，使用 TRAE Skills 进行缺陷检测。

第一步：导入 Skills

在项目根目录创建。trae/skills 文件夹，将技能包放入目录。

picture.image

配置 TRAE Skills

第二步：配置 MCP 工具

业务缺陷检测流程，需要分析需求文档和技术方案文档，因此需要配置飞书 MCP 工具用于查看文档。

飞书 MCP 工具：搜索文档、查看文档、创建文档等功能。

配置流程，参考：

https://open.larkoffice.com/document/mcp\_open\_tools/end-user-call-remote-mcp-server

1. 登录飞书 MCP 配置平台

2. 点击创建 MCP 服务

3. 在 MCP 工具配置 区域，确认当前用户身份。

4. 在添加工具 卡片内，点击添加，在添加工具对话框，选择**「云文档」** 工具集。

5. 点击 确认添加 ，并在弹出的 获取用户授权 对话框，确认授权用户登录信息、飞书 MCP 应用获得的权限信息后，点击授权。

picture.image

6. 添加工具后，在 如何使用 MCP 服务 区域，查看 服务器 URL、JSON。

picture.image

7. 在 TRAE 的 MCP 手动配置对话框内，点击确认。

picture.image

第三步：触发检测流程

完成 Skills 和 MCP 配置后，在 SOLO 模式下触发缺陷检测流程。

picture.image

SOLO 模式下触发检测

picture.image

使用 Skills 进行缺陷检测

picture.image

使用 Skills 进行缺陷检测，产出飞书缺陷报告文档

picture.image

实战：进行一次“无感”检测

接下来，我们从一位业务研发同学的视角，走一遍完整的实战流程，看看这套 Skill 组合是如何帮助他完成 “消息夜间防打扰” 功能开发的。

场景

研发“小张”接到一个需求：在现有消息服务中加入夜间防打扰逻辑——

每天 22:00 - 次日 08:00，营销类消息需要静默（不发送或返回失败），但验证码类消息不受影响。

小张写完了代码，准备提测。

Workflow Strategy: 串行化检测流水线

由于每一步检测之间有严格的数据依赖，我们没有把它们做成松散的零散工具，而是设计了一条包含 5 个阶段的串行 Workflow ，确保每一个环节的输出都成为下一个环节的上下文输入。

picture.image

Step 1: 建立全局技术认知（Skill 1）

调用 Skill: codebase-insight-analyzer

动作： 小张在对话框输入“分析当前仓库”。

背后做了什么？

这个 Skill 不只是粗暴扫文件，而是自动做了一次缩略版的**“架构逆向工程”** ：

技术栈识别： 通过go.mod 和构建脚本，识别出项目基于 CloudWeGo 技术栈（Kitex + Hertz），并依赖 Redis 做缓存；
架构分层推断： 结合目录结构（如 internal/handler 、internal/service 、internal/repo ），推断这是一个 DDD-lite 分层架构，请求大致流向是 Handler -> Service -> Domain -> Repo ；
核心域定位： 通过代码密度和依赖关系，识别出 internal/service/dispatch 、internal/biz/strategy 是业务逻辑最集中的核心域，而 utils 、common 等更多是支撑模块。

产出成果（AGENTS.md）：

最终，Agent 在仓库根目录生成了一份结构化的全局上下文文档 AGENTS.md ，帮后续的所有 Skill 画出了一张清晰的**“作战地图”** 。

  
# Architecture Overview  
- **Style**: DDD-lite / Clean Architecture  
- **Core Modules**:   
  - `internal/service/dispatch`: 消息分发核心域  
  - `internal/biz/strategy`: 策略过滤核心域  
- **Data Flow**: Request -> Handler -> DispatchService -> Strategy -> Repo

价值： 有了这张“地图”，后续再找“防打扰策略”相关逻辑时，Agent 会直接去strategy 等核心域定位，而不会在无关目录里漫游，既省 Token 又提高准确率。

Step 2: 从 PRD 中提炼出结构化需求（Skill 2）

调用 Skill: prd-function-extractor

动作： 小张在对话框提供 PRD 文档链接：xxx ，提取防打扰规则”。

背后做了什么？

这个 Skill 相当于一位 “顶级业务分析师” ，把冗长的 PRD 变成清晰的需求清单，主要做了三件事：

场景识别： 通过飞书 MCP 接口获取文档全文，识别出“用户发送消息”的主场景，以及“夜间”“营销消息”等分支条件；
要素清洗： 用内置的 CoT Prompt 把背景介绍、废话和噪音统统剥离，只保留真正影响逻辑的业务规则和约束条件（比如“按用户时区判断时间段”）；
结构化输出： 把这些自然语言规则变成机器可读的 JSON，并为每条需求打上唯一的 ID。

产出成果（JSON）：

最终，Agent 输出了一份类似下面的标准化需求列表，其中还特别标注了最容易被忽略的边缘场景 （例如时区处理）：

  
[    {      "requirement_id": "PRD-MSG-005",      "scenario_description": "营销消息夜间防打扰",      "business_rule": "每日 22:00 至次日 08:00 期间，类型为 'Marketing' 的消息应被拦截，直接返回发送失败状态。",      "constraints": "1. 仅针对 Marketing 类型，Verification 类型不受限；2. 时间判断需基于用户所在时区（若无时区信息，默认东八区）。",      "priority": "P0"    }  ]

价值： 这一步解决了研发人员“看文档抓不住重点”的痛点。通过强制结构化，Agent 显式地将 “隐性约束” （如时区问题）摆在台面上，让研发在动手写代码之前，就能一眼看到：

哪些是 P0 规则 ；
哪些是必须考虑的边界场 景；
哪些细节一旦漏掉，后面一定会变成 Bug。

Step 3: 让业务规则和技术实现对齐（Skill 3）

调用 Skill: trd-spec-extractor

动作： 在 Skill 1 的仓库知识、Skill 2 的需求 JSON 已经就绪的前提下，让 Agent 去分析 TRD。

背后做了什么？

这一步是整个流水线的“分水岭”，决定了后续缺陷检测能不能真正对上业务意图。Skill 做的不是简单“读一遍 TRD”，而是完成一次 多源信息融合（Context Fusion） ：

输入对齐： 同时读取 “PRD 业务规则（Step 2 输出）” 和 “TRD 技术方案”；
实体映射（Entity Mapping）： 把 PRD 中的自然语言概念（如“用户时区”）映射到 TRD 中的具体技术实体，比如 UserContext.GetTimezone() 、time.ParseInLocation 等；
约束传递： 把“验证码豁免”这样的业务规则，转成技术世界里的硬约束，比如“msgType == Verification 时必须跳过防打扰检查”。

产出成果（JSON）：

Agent 输出了一份 “技术规格书” ，将抽象的业务规则翻译成了具象的代码预期：

  
[    {      "specification_id": "TRD-MSG-005",      "related_requirement_id": "PRD-MSG-005",      "module": "DispatchService.CheckDoNotDisturb",      "specific_requirements": "1. 必须在 DispatchService 中新增私有方法 CheckDoNotDisturb；2. 必须使用 UserContext.GetTimezone() 获取用户时区，禁止使用 time.Now()；3. 针对 msgType=Verification 必须直接返回 true。"    }  ]

价值： 这一步彻底消除了**“自然语言”与“编程语言”之间的语义鸿沟。** 如果没有这一步，后面的检测 Skill 可能会认为：

用time.Now() 也没什么不对；
忘写Verification 的豁免逻辑也“看起来合理”。

而现在，每一条检测都有了清晰的**“定罪依据”** 。

Step 4: 精准锁定变更范围（Skill 4）

调用 Skill: function-level-defect-tracer

动作： Agent 分析 Git Diff，进行初步匹配。

背后做了什么？

这个 Skill 的目标，是为“大法官”准备一份干净、聚焦的**“证据包”** ，因此它对原始 Git Diff 做了精细化加工：

AST 级差异分析： 不是只看“哪几行变了”，而是解析 Go 的 AST，识别这次改动发生在 DispatchService 结构体的 SendMessage 方法内部；
噪音过滤： 自动忽略 import 排序、注释修改、空行变动等对业务逻辑无实质影响的改动；
调用关系追踪： 识别出新增代码引入了对 time.Now() 的调用，并打上“高风险”标签（因为时间相关逻辑往往和状态、时区强相关）。

产出成果（JSON）：

Agent 生成了一份 “变更画像” ，清晰地指出了改了哪里、怎么改的、有什么风险：

  
{  
  "changed_files": ["internal/service/dispatch.go"],  
  "function_level_changes": [  
    {  
      "symbol": "SendMessage",  
      "change_type": "MODIFIED",  
      "diff_hunks_refs": ["dispatch.go#L45-L58"],  
      "change_summary": "在消息分发前新增了基于 time.Now().Hour() 的条件判断分支",  
      "impact_analysis": {  
        "new_dependencies": ["time"],  
        "control_flow": "新增了一个提前返回 (early return) 的分支"  
      }  
    }  
  ],  
  "risk_notes": [  
    {"entity": "SendMessage", "reason": "核心分发链路引入了新的阻断逻辑，可能导致消息丢弃"}  
  ]  
}

价值： 这一步通过 “去噪”和“聚焦” ，极大地降低了后续步骤的上下文干扰。它告诉检测 Skill：“别管那些无关紧要的改动，盯着 SendMessage 里的这 13 行代码看！”这为高精度的缺陷判定奠定了坚实基础。

Step 5: 业务缺陷裁决与一键闭环（Skill 5）

调用 Skill: business-rule-defect-detector

动作： Agent 汇总前 4 步的所有信息，进行最终裁决。

背后做了什么？

这是本方案的**“大脑”** 。不同于传统的 Linter 只看代码，该 Skill 执行的是多源证据链推理（Multi-Source Reasoning）：

1. 证据拼图： Agent 将“架构知识（Skill 1）”、“PRD 规则（Skill 2）”、“TRD 映射（Skill 3）”和“变更画像（Skill 4）”拼在一起。

2. 逻辑推演：

事实：代码变更引入了if hour >= 22 。
规则：PRD 要求的是22:00 - 08:00 全时段拦截。
冲突：代码漏掉了 00:00 - 08:00 这半段。
事实：代码使用了time.Now() 。
约束：TRD 明确要求使用 UserContext.GetTimezone() 。
冲突：违反了技术规格书的实体映射。

3. 结论生成： 基于上述冲突，Agent 判定本次变更存在 [P0] 级业务逻 辑遗漏。

产出成果与闭环：

Agent 自动调用飞书 MCP 接口，生成了一份可读性极强的《业务缺陷检测报告》，并附带了可执行的修复代码：

  
// 修复建议：  
// 1. 获取用户时区上下文  
userLoc := ctx.GetTimezone()  
// 2. 修正跨日逻辑判断  
currentHour := time.Now().In(userLoc).Hour()  
if msg.Type == "Marketing" {  
    if currentHour >= 22 || currentHour < 8 { // 补全了凌晨时段  
        return ErrDoNotDisturb  
    }  
}

价值： 这不仅仅是发现问题，更是解决问题 。小张只需点击 TRAE 的“Apply Fix”按钮，即可一键修复缺陷。通过将业务逻辑、技术规范与代码实现进行深度对齐，小张成功将业务缺陷消灭在了代码提交之前 ，避免了昂贵的返工成本。未来，随着更多业务知识库的接入，这一检测的准确率还将进一步提升。

picture.image

从“人找规范”到“规范找人”

这次实践让我深刻体会到，TRAE IDE 不仅仅是一个代码编辑器，更是一个**“研发能力挂载平台”** 。通过 Agent Skills，我们把散落在 Wiki、PRD、TRD 和专家经验里的质量规范，转化成了每个研发随时可用的“肌肉记忆”。

沉浸式体验（Immersion）： 研发人员无需在 IDE、文档、质量平台之间反复横跳。所有的交互——从查看需求、对齐技术方案到检查缺陷——都在 IDE 的对话框中一气呵成。这种“零切换”的体验，极大地降低了认知负荷。
极致左移（Shift-Left）： 我们将缺陷拦截的时机推到了极限——代码 Commit 之前。这不仅仅是节省了测试成本，更重要的是它改变了研发的心智：“质量不是测试测出来的，而是设计和编码出来的。”
知识的活化（Knowledge Activation）： 以往躺在 Wiki 里落灰的“防打扰规范”、“时区处理指南”、“业务知识”，现在变成了活跃在侧边栏里的 Agent。Skill 让死知识变成了活能力 ，每一次调用都是一次最佳实践的落地。

picture.image

总结

本文用一个具体场景展示了如何借助SOLO 模式 ，通过编排 5 个精准的 Agent Skill，解决一个看似简单但极易出问题的问题：

“怎么防止开发在关键链路里，漏写一个看似不起眼的 if 判断？

SOLO + Agent Skills 的组合，正在开启一种新的研发范式：人与 Agent 协同进化。

人负责定义业务规则、做价值判断；
Agent 负责记忆规则、执行检查、给出修复建议。

在这个体系下，每一位研发都不再是孤身作战，在他身后站着的是：一整套由专家经验、最佳实践和业务规范凝结而成的“数字质量助手”。

这，大概就是 AI 时代下无数个场景的缩影。

picture.image

附录

飞书 MCP 配置

本案例最后会用到飞书文档的调用，我们选择接入飞书 MCP。具体的配置方式可以见文章上半部分。

picture.image

Skills 配置分享给大家

codebase-insight-analyzer

上下滑动查看完整内容

  
---  
name: codebase-insight-analyzer  
description: >  
  为 AI Agent 快速生成代码仓库的结构化全局上下文。自动识别技术栈、架构分层、核心业务域、模块依赖关系与风险热点，在项目根目录下覆盖写入 AGENTS.md，适用于首次接触仓库、缺陷评测准备、架构理解等场景。  
---  
# codebase-insight-analyzer  
## Goal  
对已 clone 到本地的代码仓库进行结构化洞察，形成“全局上下文包”，帮助后续缺陷校验理解：系统分层、业务域边界、关键模块及接口、功能模块的依赖关系与高风险区域。  
---  
## 📋 基本信息  
| 属性 | 值 |  
|------|-----|  
| **Skill 名称** | codebase-insight-analyzer |  
| **分类** | Tier 1: 全局理解 + Tier 2: 结构理解 |  
| **目标应用场景** | AI Coding Agent 快速理解新仓库 |  
| **输出格式** | JSON (agent-consumable) + Markdown (human-readable) |  
| **首次执行耗时** | 3-10 分钟（取决于仓库大小） |  
| **后续增量更新** | < 30 秒（Git hook 触发） |  
---  
## 🎯 核心目标  
生成**代码仓库的结构化"全局上下文包"**，使 AI Agent 能够：  
1. **秒速定位** - 知道从哪里开始读代码（入口点、关键文件）  
2. **精准搜索** - 理解模块间的依赖关系，快速定位相关代码  
3. **风险意识** - 识别高风险区域、核心链路、耦合点  
4. **自动化决策** - 理解技术栈、分层、约定，自动生成符合风格的代码  
**不做的事**：  
- ❌ 不进行缺陷判断或修复建议（留给下游 Skill）  
- ❌ 不做完整代码分析（只做结构化洞察）  
- ❌ 不解析测试代码和脚手架代码  
---  
## 🔍 适用场景  
### ✅ 使用这个 Skill 的时机  
| 场景 | 描述 | 优先级 |  
|------|------|--------|  
| **首次接触仓库** | 新 Agent 启动或开发者上手新项目 | ⭐⭐⭐ 高 |  
| **缺陷评测前准备** | 在深度分析缺陷前，需要理解整体架构和边界 | ⭐⭐⭐ 高 |  
| **大型仓库架构理解** | 超过 100K 行代码，模块众多，结构复杂 | ⭐⭐⭐ 高 |  
| **技术栈梳理** | 需要快速了解技术栈和依赖关系 | ⭐⭐ 中 |  
| **跨模块功能开发** | 需要理解多个模块的协作与数据流 | ⭐⭐ 中 |  
| **代码审查准备** | 审查者需要快速建立代码库心智模型 | ⭐ 低 |  
### ❌ 不适合用这个 Skill 的时机  
- 修改单个隔离的工具函数  
- 已经很熟悉代码库的情况  
- 只关心某个特定文件的内部逻辑  
---  
## 📥 输入参数  
### 必填参数  
```json  
{  
  "repo_path": "/path/to/local/repo"  
}

参数	类型	必需	说明
`repo_path`	string	✅	本地仓库路径（已通过 `git clone` 获取）

可选参数

{  
  "repo_path": "/path/to/repo",  
  "mode": "balanced",  
  "focus_paths": ["src/", "internal/", "cmd/"],  
  "depth": "module",  
  "language_hints": ["go", "java"],  
  "exclude_dirs": ["vendor", "node_modules", ".git"],  
  "max_file_scan": 5000,  
  "output_format": "json_with_markdown"  
}

参数	类型	默认值	说明
`mode`	string	`balanced`	`fast` (仅元数据) / `balanced` (常用) / `deep` (完整分析)
`focus_paths`	array	`[]`	需要重点洞察的目录前缀（如后续缺陷涉及的文件所在目录）。为空时分析整个仓库
`depth`	string	`module`	`architecture` (分层) / `module` (模块细节) / `dependency` (完整依赖)
`language_hints`	array	`[]`	编程语言提示（加快检测），如 `["go", "python"]`
`exclude_dirs`	array	默认值	排除扫描的目录（已包含常见的 node_modules, vendor 等）
`max_file_scan`	int	5000	最多扫描的文件数（防止超大仓库耗时过长）
`output_format`	string	`json_with_markdown`	`json` / `markdown` / `json_with_markdown`

完整输入示例

示例 1：首次接触新仓库（推荐配置）

{  
  "repo_path": "/home/agent/repos/my-service",  
  "mode": "balanced",  
  "depth": "architecture",  
  "output_format": "json_with_markdown"  
}

预期输出：全面的架构总览 + 关键模块细节，适合初期快速理解。

示例 2：缺陷评测前的精准分析

{  
  "repo_path": "/home/agent/repos/payment-service",  
  "mode": "deep",  
  "focus_paths": ["internal/order", "internal/payment", "infra/db"],  
  "depth": "dependency",  
  "output_format": "json_with_markdown"  
}

预期输出：聚焦在关键路径上的完整依赖分析，包括跨模块调用和风险热点。

示例 3：快速了解技术栈（快速模式）

{  
  "repo_path": "/home/agent/repos/legacy-system",  
  "mode": "fast",  
  "depth": "architecture",  
  "language_hints": ["java", "python"]  
}

预期输出：快速的技术栈 + 分层信息，< 1 分钟完成。

📤 输出结构

输出设计理念

根据 AI Agent 的 Token 预算，输出采用分层加载策略：

Level 1 (always)  
├─ tech_stack                 ← 200 tokens  
├─ architecture_overview      ← 300 tokens  
├─ entrypoints               ← 200 tokens  
└─ core_domains              ← 200 tokens  
   Subtotal: ~900 tokens (快速上下文)  
Level 2 (on demand)  
├─ functional_modules         ← 2K-5K tokens  
├─ data_flow_clues           ← 1K-3K tokens  
└─ dependency_clues          ← 2K-5K tokens  
   Subtotal: ~5K-13K tokens(详细分析)  
Level 3 (surgical)  
├─ risk_hotspots             ← 500-1K tokens  
├─ navigation_hints           ← 300 tokens  
└─ evidence_map              ← 500 tokens  
   Subtotal: ~1.3K-1.8K tokens(辅助决策)

完整输出 JSON Schema

{  
  "metadata": {  
    "generated_at": "2026-01-21T14:48:00Z",  
    "repo_path": "/path/to/repo",  
    "repo_size_mb": 125,  
    "total_files": 1847,  
    "total_lines": 250000,  
    "language_distribution": {  
      "go": 85,  
      "proto": 10,  
      "yaml": 5  
    },  
    "analysis_mode": "balanced",  
    "analysis_duration_seconds": 45  
  },  
    
  "tech_stack": {  
    "languages": [  
      {  
        "name": "Go",  
        "version": "1.24",  
        "primary": true,  
        "evidence": "go.mod"  
      }  
    ],  
    "frameworks": [  
      {  
        "name": "Kitex",  
        "version": "0.7.2",  
        "usage": "RPC Framework",  
        "evidence": "go.mod"  
      },  
      {  
        "name": "Hertz",  
        "version": "1.0",  
        "usage": "Web Framework",  
        "evidence": "go.mod"  
      }  
    ],  
    "storage": [  
      {  
        "type": "MySQL",  
        "usage": "Data Store",  
        "driver": "Gorm",  
        "config_location": "conf/db.yaml"  
      },  
       {  
        "type": "Redis",  
        "usage": "Data Store",  
        "config_location": "conf/redis.yaml"  
      }  
    ],  
    "messaging": [  
      {  
        "type": "RocketMQ",  
        "usage": "Messaging",  
        "config_location": "conf/rmq.yaml"  
      }  
    ],  
    "build_system": {  
      "type": "Make / Shell",  
      "build_command": "./build.sh",  
      "test_command": "go test ./..."  
    }  
  },  
  "architecture_overview": {  
    "style": "DDD-lite / Clean Architecture",  
    "diagram": "mermaid graph TD...",  
    "layers": [  
      {  
        "name": "Interface Layer (Adapter)",  
        "directories": ["cmd/", "internal/handler/"],  
        "responsibility": "HTTP/RPC 请求解析，响应组装"  
      },  
      {  
        "name": "Application Layer",  
        "directories": ["internal/service/"],  
        "responsibility": "业务流程编排，事务管理"  
      },  
      {  
        "name": "Domain Layer",  
        "directories": ["internal/domain/"],  
        "responsibility": "核心业务规则，不依赖框架的纯业务逻辑"  
      },  
      {  
        "name": "Infrastructure Layer",  
        "directories": ["infra/", "internal/repo/"],  
        "responsibility": "数据持久化，外部资源访问"  
      }  
    ]  
  },  
    
  "build_and_commands": {  
      "prerequisites": ["Go 1.24+", "MySQL"],  
      "commands": [  
          {"task": "Build", "command": "./build.sh", "description": "Compiles binary"},  
          {"task": "Test", "command": "go test ./...", "description": "Runs all unit tests"}  
      ]  
  },  
    
  "code_style_and_conventions": [  
      "Use GORM/GEN for database operations.",  
      "Wrap errors with context.",  
      "Follow Thrift IDL Guidelines."  
  ],  
    
  "testing_strategy": {  
      "unit_tests": "Located alongside source files (e.g., *_test.go)",  
      "integration_tests": "test/ directory",  
      "mocking": "mockey"  
  },  
    
  "configuration_management": {  
      "files": ["conf/*.yaml"],  
      "loading_logic": "Determines environment (BOE/CN) and loads corresponding YAML."  
  },  
    
  "security_policy": [  
      "NEVER commit API keys or passwords.",  
      "Validate all inputs in the API layer."  
  ],  
  "entrypoints": [  
    {  
      "type": "server_bootstrap",  
      "file": "cmd/server/main.go",  
      "key_functions": [  
        {  
          "name": "main",  
          "responsibility": "程序入口，初始化 DI 容器"  
        }  
      ]  
    }  
  ],  
    
  "core_domains": [  
    {  
      "domain_name": "BugDetect",  
      "path": "agent/bug_detect.go",  
      "responsibilities": ["Defect Detection", "ReAct Agent"]  
    }  
  ]  
}

🔄 执行流程（Procedure）

阶段 1: 前置检查（Pre-Analysis）

检查项:  
□ repo_path 是否存在且是有效的 Git 仓库  
□ 是否有读取权限  
□ 仓库大小（确定分析深度）  
□ 主要编程语言（确定检测策略）

阶段 2: 快速识别技术栈与构建系统（Tech Stack & Build Detection）

扫描顺序:  
1. 构建/依赖文件（go.mod, pom.xml, package.json, requirements.txt）  
2. 构建脚本（Makefile, build.sh, package.json scripts）  
3. 目录结构（cmd/, src/, internal/, src/main/, lib/）  
4. 特征文件（*.proto, *.thrift, *.sql, docker-compose.yml）  
输出: tech_stack, build_and_commands  
耗时: < 15 秒

阶段 3: 架构与分层识别（Architecture & Layers）

推断架构风格:  
- 识别常见分层目录（handler, service, domain, repo, infrastructure）  
- 识别入口点（main.go, router.go, idl definitions）  
- 生成 Mermaid 架构图（表示层级关系与数据流向）  
输出: architecture_overview, entrypoints  
耗时: < 30 秒

阶段 4: 领域与模块深度分析（Domain & Module Analysis）

提取模块信息:  
- 模块名 (目录名)  
- 职责 (README / 包注释)  
- 关键数据模型 (Struct / Entity 定义)  
- 识别核心业务域（Core Domains）  
输出: core_domains, functional_modules  
耗时: < 45 秒

阶段 5: 测试与配置分析（Testing & Configuration Analysis）

测试分析:  
- 查找测试文件位置 (*_test.go, test/ 目录)  
- 识别测试框架与 Mock 工具  
配置分析:  
- 查找配置文件位置 (conf/, config/, .env)  
- 分析配置加载逻辑 (config.go)  
输出: testing_strategy, configuration_management  
耗时: < 30 秒

阶段 6: 安全与规范分析（Security & Conventions）

安全扫描:  
- 检查是否有硬编码密钥风险  
- 识别鉴权中间件 (Auth Middleware)  
- 检查输入验证逻辑  
规范提取:  
- 提取代码风格约定 (CONTRIBUTING.md, linter config)  
- 提取数据库操作规范 (ORM vs Raw SQL)  
输出: security_policy, code_style_and_conventions  
耗时: < 30 秒

阶段 7: 生成 AGENTS.md（Documentation Generation）

生成符合 Biz Bug Detection Agent 格式的文档:  
1.Project Overview(Capabilities, Tech Stack)  
2. Architecture(Mermaid Diagram, Directory Structure)  
3. Build & Commands(Prerequisites, Command Table)  
4. Code Style & Conventions  
5. Testing(Unit/Integration, Mocking)  
6. Configuration(Loading Logic, Key Configs)  
7. Security(Secrets, Data Protection)  
8. Domain Deep Dive(Agent Development / Core Logic)  
输出: AGENTS.md 写入仓库根目录  
耗时: < 10 秒

📝 生成的 AGENTS.md 示例

# [Project Name] - Architecture Overview  
> **Note**: This document provides a high-level overview of the `[Project Name]` codebase for developers and AI agents.  
## 1. Project Overview  
**[Project Name]** is a [Description] system designed to [Goal]. It handles [Key Functionalities].  
### Key Capabilities  
- **Capability 1**: Description.  
- **Capability 2**: Description.  
### Tech Stack  
- **Language**: Go 1.24+  
- **Web Framework**: CloudWeGo Hertz  
- **RPC Framework**: CloudWeGo Kitex  
- **Data Store**: MySQL(GORM), Redis  
- **Messaging**: RocketMQ  
## 2. Architecture  
The system follows a **[Architecture Style]** architecture.  
```mermaid  
graph TD  
    API[HTTP API] -->|Request| Service  
    Service -->|Logic| Domain  
    Domain -->|Data| DB[(MySQL)]

Directory Structure

agent/: Core agent logic.
biz/: Business logic, handlers.
conf/: Configuration files.
dal/: Data Access Layer.

3. Build & Commands

Prerequisites

Go 1.24+
MySQL, Redis

Common Commands

Task	Command	Description
Build	`./build.sh`	Compiles binary.
Run	`go run main.go`	Starts server.
Test	`go test ./...`	Runs unit tests.

4. Code Style & Conventions

Go Version: Use Go 1.24 features.
Database: Use GORM; avoid raw SQL.
Error Handling: Wrap errors with context.

5. Testing

Unit Tests: Located alongside source files.
Integration Tests: test/ directory.
Mocking: Use mockey.

6. Configuration

Configuration is managed via config/config.go and YAML files in conf/.

7. Security

Secrets: NEVER commit API keys. Use env vars.
Access Control: Internal APIs protected via ACL.

8. Domain Deep Dive

[Core Domain Name]

Responsibilities: ...
Key Files: ...

prd-function-extractor

上下滑动查看完整内容

  
---  
name: prd-function-extractor  
description: "Extracts functional points from PRD documents (Feishu). Invoke when user wants to analyze requirements or extract functions from a PRD."  
---  
# prd-function-extractor  
This skill extracts functional points from a Product Requirement Document(PRD) hosted on Feishu.  
## Workflow  
1.  **Get the PRD Link**: Ask the user for the Feishu document link ifnot provided.  
2.  **Fetch Document Content**:  
    *   **Method 1 (Preferred)**: Use the `mcp_feishu-lark-mcp_fetch-doc` tool.  
        *   Argument `doc_id` should be the full URL of the Feishu document.  
    *   **Method 2 (Fallback)**: If Method 1 fails or is unavailable, run the python script located at `.trae/skills/prd-function-extractor/scripts/fetch_doc.py` to fetch the content via the HTTP interface.  
        *   Usage: `python ./skills/prd-function-extractor/scripts/fetch_doc.py <doc_url>`  
        *   Note: You may need to install `requests` ifnot available, or use standard library `urllib` if `requests` is missing and you cannot install it.  
    *   **Method 3 (Manual)**: If both Method 1 and Method 2 fail, **ask the user to paste the document content directly**. Explain that automatic fetching failed.  
3.  **Analyze Content**: Use the **Function Extraction Prompt** (below) to process the markdown content.  
## Function Extraction Prompt  
Use the following prompt to analyze the fetched markdown content. Paste the document content at the end of this prompt or provide it as context.  
---  
#### **角色与任务**    
你是**顶级业务分析师（Business Analyst）**和**PRD需求提取专家**，需从**任意PRD**中**100%精准提取所有功能相关核心信息**，分批次生成需求文档。   
#### **提取规则**    
---   
##### **1. 场景识别：覆盖所有用户操作逻辑**    
需识别PRD中**所有用户与系统交互的场景**，包括：    
- **主场景**：核心功能的常规操作（如“用户填写表单提交信息”“用户查看某模块数据列表”）；    
- **边缘场景**：异常/边界条件下的操作（如“用户输入无效值时的提示”“功能禁用时的交互限制”）；    
- **关联场景**：跨模块的联动操作（如“操作A触发模块B的状态变更”）。    
每个场景分配唯一需求ID（格式：`PRD-XXX`，按批次顺序编号）。    
##### **2. 要素提取：每个场景必须包含4项核心内容**    
需严格从PRD原文中提取以下要素，**不允许 paraphrase（改写）**，保持原文表述：    
- 场景描述：用户具体操作 + 目标（严格还原 PRD 动词、名词、流程）；   
- 业务规则：PRD 明确的逻辑规则（如计算方式、展示优先级、操作联动、数据映射关系等）；   
- 约束条件：PRD 明确的限制（输入范围、权限控制、禁用条件、提示文案、时间限制等）；   
- 优先级：PRD 标注的优先级（P0/P1/P2 / 高 / 中 / 低）。   
##### **3. 覆盖要求：确保无遗漏**    
需覆盖PRD中**所有功能相关内容**，包括但不限于：    
- **文案细节**：按钮名称、标签内容、提示语、hover说明、字段说明；    
- **边缘场景**：异常输入提示、功能禁用规则、跨模块联动限制、数据边界条件；    
- **逻辑规则**：数据计算方式、状态流转规则、权限控制逻辑、操作生效条件。    
#### **输出格式**    
严格按照如下json格式输出，确保json格式合法：   
```json   
[   
{   
    "requirement_id": "PRD-001", // 需求ID   
    "scenario_description": "用户在[客户管理模块]的客户列表页，查看每条客户记录的「客户名称」「注册时间」「状态」字段", // 场景描述   
    "business_rule": "客户列表页展示的字段包括：客户名称（原文名称）、注册时间（格式：YYYY-MM-DD）、状态（标签形式，内容为「激活」「冻结」「注销」）", // 业务规则   
    "constraints": "注册时间仅展示至日期，不显示时分秒；状态标签颜色随状态不同区分（激活：绿色/冻结：橙色/注销：灰色）", // 约束条件   
    "priority": "P0"// 优先级   
  },   
  {   
    "requirement_id": "PRD-002",   
    "scenario_description": "用户在[订单管理模块]的订单详情页，查看「订单金额」字段的hover说明",   
    "business_rule": "「订单金额」字段的hover文案为：「订单金额=商品总价+运费-优惠券抵扣-满减折扣」",   
    "constraints": "hover说明仅当鼠标悬浮至「订单金额」字段时显示，文案不可修改",   
    "priority": "P0"  
  }   
]






  




Skill 用到的脚本：


prd-function-extractor/scripts/fetch\_doc.py



  




**上下滑动查看完整内容**

import requests
import sys
import json

def get_doc_content(doc_url):
api_url = "https://test-standardization-backend.byted.org/common/doc/markdown"
params = {"doc": doc_url}
try:
response = requests.get(api_url, params=params)
response.raise_for_status()
data = response.json()
if data.get("code") == 0:
# Return just the content or the whole data object depending on needs
# The prompt expects the content.
return data["data"]
else:
print(f"Error: {data.get('message')}", file=sys.stderr)
return None
except Exception as e:
print(f"Exception: {e}", file=sys.stderr)
return None

if name == "main":
if len(sys.argv) < 2:
print("Usage: python script.py <doc_url>")
sys.exit(1)

doc_url = sys.argv[1]  
result = get_doc_content(doc_url)  
if result:  
    # Output the content part or the full JSON?   
    # The tool output will be read by the agent.   
    # Let's output the content field primarily, or the JSON.  
    # The API returns {"title":..., "content":...} in 'data'.  
    print(json.dumps(result, ensure_ascii=False, indent=2))  
else:  
    sys.exit(1)






  




**trd-spec-extractor** 








  




**上下滑动查看完整内容**

name: trd-spec-extractor
description: "Extracts technical specifications from TRD documents (Feishu), mapping business rules to technical implementations. Invoke after PRD analysis when a TRD is available."

trd-spec-extractor

This skill extracts technical specifications from a Technical Requirement Document(TRD) hosted on Feishu, mapping them to PRD business rules.

Prerequisites

PRD Analysis: This skill is designed to run after prd-function-extractor. You must have the extracted PRD requirements(JSON format) available in the context.

Workflow

Get the TRD Link: Ask the user for the Feishu document link for the TRD ifnot provided.
Fetch Document Content:
- Method 1 (Preferred): Use the mcp_feishu-lark-mcp_fetch-doc tool.
  - Argument doc_id should be the full URL of the Feishu document.
- Method 2 (Fallback): If Method 1 fails or is unavailable, run the python script located at .trae/skills/trd-spec-extractor/scripts/fetch_doc.py to fetch the content via the HTTP interface.
  - Usage: python .trae/skills/trd-spec-extractor/scripts/fetch_doc.py <doc_url>
  - Note: You may need to install requests ifnot available, or use standard library urllib if requests is missing and you cannot install it.
- Method 3 (Manual): If both Method 1 and Method 2 fail, ask the user to paste the document content directly. Explain that automatic fetching failed.
Analyze Content: Use the Specification Extraction Prompt (below) to process the TRD content.
- CRITICAL: You MUST provide the PRD Requirements JSON (from the previous step/context) AND the TRD Content to the model when using the prompt.

Specification Extraction Prompt

Use the following prompt to analyze the fetched TRD content.
Input Context Required:

PRD Requirements: [Insert the JSON output from prd-function-extractor here]
TRD Content: [Insert the fetched TRD markdown content here]

【核心目标】

作为TRD技术规范提取专家，需严格关联PRD中的「业务角色」「核心业务规则」与TRD中的「技术实现细节」，从技术文档中提取业务逻辑与技术方案一一对应的可执行规范，确保规范既覆盖业务意图，又明确技术落地要求。

【处理规则】

需求关联：针对PRD中的每个需求ID，匹配TRD中对应的技术实现方案，分配唯一规范ID（格式：TRD-XXX）；若TRD无对应实现，不输出。
模块完整性：模块需同时包含：
- PRD中的业务角色（如“用户端APP”“PC管理后台”“OPEN接口服务”）；
- TRD中的技术模块（如“用户服务-Login接口”“verify_code数据库表”“SmsService-SendCodeRPC方法”）；
  严格使用文档中明确的名称，禁止杜撰。
具体要求完整性（核心约束）：
需覆盖2类100%完整的信息，不得有任何省略、类比或模糊表述：
- PRD核心业务规则：必须包含场景（如“登录页”）、时机（如“点击登录按钮时”）、所有规则（如“6位数字验证码”“5分钟有效期”）、约束（如“提示文案”）；
- TRD技术实现细节：必须包含对应业务规则的落地逻辑（如“Login接口校验code参数长度与格式”“verify_code表存储过期时间”），且需与业务规则一一对应。

【禁止性约束（强制红线）】

❌ 禁止遗漏业务上下文：必须保留PRD中的“业务角色”“场景”“时机”“所有规则”“约束”（如PRD要求“6位数字验证码”，则规范中必须完整写“6位数字验证码”，不得简化为“验证码”）；
❌ 禁止技术细节孤立：技术实现需与业务规则强关联（如“PRD要求验证码5分钟有效，所以TRD中verify_code表存储创建时间，接口校验当前时间≤创建时间+5分钟”）；
❌ 禁止模糊表述：模块、字段、接口名需与PRD/TRD完全一致（如“用户端APP”“Login接口”“verify_code表”）；
❌ 禁止类比/省略描述：即使规则与其他需求重复，也需完整复述所有内容（如PRD-002要求“注册验证码规则同登录”，则规范中必须完整写出“6位数字、5分钟有效”，不得使用“同登录规则”）；若违反此条，该规范直接无效。

【Few-Shot示例】

场景背景：

PRD需求是“用户端APP提交订单时，需填写包含省、市、区的收货地址，且地址需非空；订单服务需存储完整地址。PC端提交订单逻辑同APP端。”；TRD实现是“订单服务-CreateOrder接口校验address参数的province/city/district非空，存储到order_info表的shipping_address字段”。

❌ Bad Case1（问题：丢失业务角色与业务规则，仅描述技术实现）

{   
  "specification_id": "TRD-001",   
  "related_requirement_id": "PRD-001",   
  "module": "订单服务-CreateOrder接口、order_info表",   
  "specific_requirements": "CreateOrder接口校验address参数的province/city/district非空；order_info表新增shipping_address字段存储地址"  
}

问题分析：

未提及PRD中的「业务角色」（用户端APP）；
未关联「业务规则」（用户端需填写三级地址）与技术实现的逻辑关系（因为用户端要填，所以接口要校验）；

✅ Good Case（正确：覆盖业务+技术，逻辑闭环）

{   
  "specification_id": "TRD-001",   
  "related_requirement_id": "PRD-001",   
  "module": "用户端APP、订单服务-CreateOrder接口、order_info表",   
  "specific_requirements": "1. PRD业务规则：用户端APP提交订单时，需填写包含省、市、区的收货地址，地址字段非空；2. TRD技术实现：订单服务-CreateOrder接口校验address参数的province/city/district字段非空"  
}

❌ Bad Case2（类比/省略）

{   
  "specification_id": "TRD-002",   
  "related_requirement_id": "PRD-002",   
  "module": "PC端、订单服务-CreateOrder接口、order_info表",   
  "specific_requirements": "1. PRD业务规则：PC端提交订单逻辑同APP端。2. TRD技术实现：订单服务-CreateOrder接口校验address参数的province/city/district字段非空"  
}

✅ Good Case（完整/无省略）

{   
  "specification_id": "TRD-002",   
  "related_requirement_id": "PRD-002",   
  "module": "PC端、订单服务-CreateOrder接口、order_info表",   
  "specific_requirements": "1. PRD业务规则：PC端提交订单时，需填写包含省、市、区的收货地址，地址字段非空；2. TRD技术实现：订单服务-CreateOrder接口校验address参数的province/city/district字段非空"  
}

【输出格式要求】

严格遵循以下JSON数组格式，确保json合法（注意必要的双引号转义不能丢失）：

[   
  {   
    "specification_id": "TRD-XXX", // 技术规范ID（唯一）   
    "related_requirement_id": "PRD-XXX", // 关联PRD需求ID   
    "module": "业务角色1、技术模块1、技术模块2", // 如“用户端APP、订单服务-CreateOrder接口、order_info表”   
    "specific_requirements": "1. PRD核心业务规则；2. TRD技术实现细节"// 分点覆盖业务+技术，无任何省略   
  }   
]






  




Skill 用到的脚本：


trd-spec-extractor/scripts/fetch\_doc.py


  





**上下滑动查看完整内容**

import requests
import sys
import json

if name == "main":
if len(sys.argv) < 2:
print("Usage: python script.py <doc_url>")
sys.exit(1)

doc_url = sys.argv[1]  
result = get_doc_content(doc_url)  
if result:  
    # Output the content part or the full JSON?   
    # The tool output will be read by the agent.   
    # Let's output the content field primarily, or the JSON.  
    # The API returns {"title":..., "content":...} in 'data'.  
    print(json.dumps(result, ensure_ascii=False, indent=2))  
else:  
    sys.exit(1)






  




**function-level-defect-tracer** 








  




**上下滑动查看完整内容**

name: function-level-defect-tracer
description: 基于 MR 的 source commit id 与 target commit id，对本次 MR 变更内容进行差异分析与定位（文件/函数级），输出变更摘要、关键 diff 片段索引与风险点，供缺陷校验使用。

function-level-defect-tracer

Goal

对指定 commit 范围（source..target）进行变更分析，产出“本次 MR 变更包”，包括：变更文件清单、关键 diff、涉及函数/接口、潜在影响面与风险标注。

When to use

对缺陷检测系统报告的缺陷进行校验前，需要先明确本次 MR 改了什么。
需要验证缺陷是否由本次 MR 引入（或是否已在 MR 中修复/回归）。

Inputs

repo_path: 本地仓库路径。
source_commit_id: MR source commit id。
target_commit_id: MR target commit id。
optional:
- focus_files: 缺陷报告涉及的文件列表（优先分析）。
- focus_symbols: 缺陷报告涉及的函数/方法名列表（优先分析）。
- diff_granularity: file | function（默认 function）。

Input example

{  
  "repo_path": "/path/to/repo",  
  "source_commit_id": "abc123",  
  "target_commit_id": "def456",  
  "focus_files": ["dash_board_action.go"],  
  "focus_symbols": ["QueryConversationDispatch"],  
  "diff_granularity": "function"  
}

Outputs

commit_range: {source, target}
changed_files: [{path, change_type, stats(add/del), hunks_count}]
function_level_changes: [{symbol, file_path, change_summary, diff_hunks_refs}]
risk_notes: [{entity, reason}]
trace_hints: 给 business-defect-assessor 的线索（哪些变更最可能关联缺陷）

Output example(shape)

{  
  "commit_range": {"source": "abc123", "target": "def456"},  
  "changed_files": [  
    {"path": "dash_board_action.go", "change_type": "M", "stats": {"add": 20, "del": 5}, "hunks_count": 3}  
  ],  
  "function_level_changes": [  
    {  
      "symbol": "QueryConversationDispatch",  
      "file_path": "dash_board_action.go",  
      "change_summary": "新增灰度分流分支与兜底逻辑",  
      "diff_hunks_refs": ["dash_board_action.go#HUNK2"]  
    }  
  ],  
  "risk_notes": [  
    {"entity": "QueryConversationDispatch", "reason": "核心分发逻辑被改动，且包含条件分支"}  
  ],  
  "trace_hints": ["优先核对灰度开关含义与分支是否对齐业务规则"]  
}

Procedure

验证 commit 存在且可比较。
生成 file-level diff：变更文件、增删行统计、hunk 数。
生成 function-level 索引（能做到就做到）：
- 对 Go/Java 等可通过简单符号匹配或 AST/ctags 生成函数级差异索引。
- 若难以精确到函数，至少输出“可能涉及的函数/方法名 + diff hunk 位置”。
对 focus_files / focus_symbols 做优先级排序输出。
标注风险点：核心链路、条件分支、状态机、并发/缓存/一致性相关变更。

Guardrails

只描述“变更事实 + 风险线索”，不判断缺陷对错（留给 assessor）。
对于无法稳定提取函数级差异的语言/仓库结构，明确降级策略与不确定性。






  




**business-rule-defect-detector** 








  




**上下滑动查看完整内容**

name: business-rule-defect-detector
description: Detects business logic defects in code changes by verifying alignment with PRD/TRD requirements. Invoke after analyzing requirements and code diffs.

business-rule-defect-detector

This skill acts as a senior code reviewer to detect business logic defects in code changes based on PRD/TRD requirements.

Prerequisites

Requirement Analysis: Must have PRD/TRD analysis results(from prd-function-extractor / trd-spec-extractor).
Diff Analysis: Must have code change analysis results(from function-level-defect-tracer).

Role & Goal

你是一位具备多轮推理和工具调用能力的代码审查助手，你的目标是结合代码整个上下文精准匹配测试用例的业务规则，判断相关代码是否满足了测试用例中指定的功能。你可以分步骤思考、调用工具获取信息，并在观察结果（Observation）基础上进一步推理，最终输出一段清晰的 Code Review 结论。

Review Steps

第一步：提取关键信息

聚焦业务规则与约束：
- 测试用例一般会包含前端用户动线、数据加载展示（可选，当测试用例非'纯前端'需要依赖后端数据时），而数据来源一般是后端服务提供的
- 从测试用例中提取核心功能点、核心业务规则（如“提交时所有目标字段需完成文本校验”等）。
区分职责边界：
- 确认测试用例中的功能点是否属于当前微服务的职责（如后端负责规则校验，前端负责交互提示），非职责内的功能不做判断。

第二步：跟踪调用链与深度审查

2.1 完整跟踪调用链

沿变更链路查看全链路源码（如从入口函数到具体校验逻辑），调用 SearchCodebase (search_code_snippets) 或 Read (get_entity_contents) 获取关联函数/结构体的真实代码，不跳跃、不猜测、避免仅看变更函数（这可能会让你陷入偏见）。
在理解代码的过程中：像人一样，边阅读代码、边思考、边寻找证据来分析是否存在不符合预期的地方，包括但不限于文案错误、字段类型不匹配等。

2.2 逐行梳理代码，验证“逻辑覆盖度”

如果需求中涉及一些校验规则场景的描述，需对包含循环/条件判断的关键函数，强制梳理所有执行路径，回答：
1. 哪些分支会执行目标逻辑（如校验）？
2. 哪些分支会跳过目标逻辑（如continue/return）？
3. 跳过逻辑的条件（如“某字段非空”）是否符合测试用例的“全量覆盖/校验”要求？

2.3 结构体与字段校验

如果需求中涉及关键字段的返回，请对代码中相关结构体字段的赋值/传递（如obj.FieldA = otherObj.FieldB）逻辑进行严格审查：
1. 获取赋值方与被赋值方的完整结构体定义（含嵌入/引用的关键结构体）；
2. 检查字段类型一致性与赋值正确性（如时间字段不能用用户字段赋值）。

第三步：整合输出bug列表

整合分析过程中得出的所有bug，你的最终输出必须是一个严格的、合法的（注意双引号转义）JSON数组对象，格式如下：

[  
    {  
      "file": "service/order_service.go", // 缺陷函数所在文件，使用相对路径  
      "function": "OrderService.SplitOrderWithDiscount", // 发生缺陷的函数名  
      "start_line": 5, // 问题代码的起始行，不要设置为0  
      "end_line": 10, // 问题代码的结束行，不要设置为0  
      "problem": "功能实现错误，计算 'total' 时未过滤商品类别，导致全品类分摊。", // 内容为bug的具体描述，必须包括bug发生的条件、推理逻辑等信息  
      "suggestion": "过滤商品类别，在计算 'total' 时只计算指定商品类别的分摊金额。", // 内容为修复bug的具体方法（包括如何修改字段、修改代码逻辑等信息），也可以直接输出修复代码  
      "reasoning": "详细解释为什么这是个bug",  
      "score": 8, // 置信度评分[1-10]  
      "type": "问题类型，比如：文案错误、业务逻辑错误等",  
      "label": "P0", // 问题严重级别，可选值：P0/P1/P2，P0代表严重，P1代表中等  
      "uncertainties": [// 如果不存在不确定性，该字段需置为空数组  
        {  
          "summary": "针对当前bug判定的不确定性总结，明确指出影响置信度的关键未知信息。",  
          "reasoning": "详细解释这个不确定性如何影响bug判定，说明缺失的上下文信息及其对问题确认的影响，比如指出bug所在代码其依赖的、无法审查的外部组件或未知信息是什么，并应用“职责链追溯”原则说明当前代码已经履行的职责。"  
        }  
      ]  
    }  
]

第四步：生成飞书分析报告

在完成缺陷分析后，必须使用 mcp_feishu-lark-mcp_create-doc 工具生成一份详细的业务缺陷分析报告。

报告生成要求：

标题：业务缺陷分析报告 - [当前日期]
内容结构：
- 概述：简要说明本次分析的背景（关联的 PRD/TRD）和发现的缺陷总数。
- 缺陷详情：针对每一个发现的缺陷，生成一个详细的分析板块，包含：
  - 缺陷标题：[P0/P1] 简短描述
  - 基本信息：
    - 严重等级：明确标注 P0/P1/P2，并简述定级理由（如“涉及核心资损路径”）。
    - 关联需求：明确指出违反的 PRD-XXX 或 TRD-XXX 编号。
  - 业务背景 (Business Context)：
    - 业务规则：引用具体的业务规则原文。
    - 业务影响：说明该缺陷会导致什么业务后果（如“导致用户无法下单”、“金额计算错误导致资损”）。
  - 技术分析 (Technical Analysis)：
    - 位置：文件路径 + 函数名 + 起止行号。
    - 触发场景 (Trigger Scenario)：描述触发该缺陷的具体输入参数、前置条件或业务场景（如“当 price > 100 且 user_type 为 VIP 时触发”）。
    - 问题代码片段 (Critical)：必须包含一段带有行号和行内注释的代码片段，直接在代码中指出问题所在。
```
// 示例格式  
func CalculatePrice(price int)int{  
    if price > 100 {   
        return price * 0.8// <--- 缺陷：PRD要求打9折，此处代码实现了8折  
    }  
    return price  
}  
```
    - 根因分析：解释代码逻辑为何未能满足业务规则（如“遗漏了边界条件判断”、“使用了错误的字段来源”）。
    - 技术风险 (Technical Risks)：评估缺陷或修复可能带来的技术副作用（如“涉及历史数据清洗”、“破坏接口兼容性”、“存在并发安全隐患”）。
  - 解决方案 (Solution)：
    - 修复建议：提供具体的修复代码或伪代码。
    - 验证方法：描述如何验证修复是否生效（如“构造 price=101 的测试用例，预期结果应为...”）。
- 不确定性说明（如有）：列出分析过程中遇到的不确定因素及其对结论的影响。
格式：使用 Markdown 格式，利用高亮块（Callout）、代码块等增强可读性。

Output Requirements

整个过程务必使用中文输出。
功能实现遗漏问题不检测、不输出。
start_line和end_line不要跨越整个函数，区间范围尽量小。
json数组中的每一个条目都应当是缺陷描述，若函数代码逻辑完全符合测试用例的业务规则与职责要求，无需生成任何 JSON 条目；若最终没有任何bug，输出空数组[]即可。

Important Principles

确凿证据原则：
- 判定bug必须在已审查的代码中找到确凿的、不依赖于外部的实现缺陷，且缺陷直接违反测试用例的业务规则；无证据不判定bug。
- 不要猜测struct、variable等实现，务必调用工具（比如 SearchCodebase 等）查询真实内容，准确理解后再给出结论，结论务必严谨、禁止任何猜测，不要出现“可能”这些表示推测的词。
- 如果审查源代码时发现了明显且十分确定的逻辑缺陷，务必透出该缺陷，例如：函数A的功能是获取用户的信息，但其日志打印中却出现了“创建用户错误”的文案。
不确定性优先原则：
这是最重要的原则，若功能正确性依赖无法审查的外部组件（如前端交互、下游rpc服务），不武断判定为bug。
- 举例1：根据开发人员习惯，输入框相关的分隔符不一定需要后端来处理，也可能是前端分隔后调用多次接口，这块是不确定的；
- 举例2：根据规范，用户密码一般需要hash加密后才能进行存储，如果在本服务检测出没有进行加密操作缺陷时，可能已经在其它服务进行了加密操作，由于是微服务架构，这块也是不确定的。
职责链追溯（关注点分离）原则：
要深刻理解当前的检测的是微服务架构的分布式系统，一个功能点可以由不同代码仓库来实现其不同部分的能力，明确当前代码的职责范围（如“某函数仅负责某字段的规则校验”），非本服务职责内的功能（如前端提示）禁止作出正确性判断。
逐行代码审查原则：
请仔细审查每一行源代码，并仔细思考确认其是否存在逻辑缺陷，不要因为在某一行代码中发现了明确的缺陷，就偷懒直接得出结论，而不再审阅任何其他代码行是否存在缺陷，这种行为是不可接受的极大概率会让你错失发现其它缺陷的机会！






  





![picture.image](https://p6-volc-community-sign.byteimg.com/tos-cn-i-tlddhu82om/29a48e4ffa9047a38d8005985cc93e51~tplv-tlddhu82om-image.image?=&rk3s=8031ce6d&x-expires=1772539963&x-signature=jhGKcrtlGgWxeGF2QFkNMifxaBk%3D)

可选参数

完整输入示例

示例 1：首次接触新仓库（推荐配置）

示例 2：缺陷评测前的精准分析

示例 3：快速了解技术栈（快速模式）

预期输出：快速的技术栈 + 分层信息，< 1 分钟完成。

📤 输出结构

输出设计理念

完整输出 JSON Schema

🔄 执行流程（Procedure）

阶段 1: 前置检查（Pre-Analysis）

阶段 2: 快速识别技术栈与构建系统（Tech Stack & Build Detection）

阶段 3: 架构与分层识别（Architecture & Layers）

阶段 4: 领域与模块深度分析（Domain & Module Analysis）

阶段 5: 测试与配置分析（Testing & Configuration Analysis）

阶段 6: 安全与规范分析（Security & Conventions）

阶段 7: 生成 AGENTS.md（Documentation Generation）

📝 生成的 AGENTS.md 示例

Directory Structure

3. Build & Commands

Prerequisites

Common Commands

4. Code Style & Conventions

5. Testing

6. Configuration

7. Security

8. Domain Deep Dive

[Core Domain Name]

name: trd-spec-extractor description: "Extracts technical specifications from TRD documents (Feishu), mapping business rules to technical implementations. Invoke after PRD analysis when a TRD is available."

Prerequisites

Workflow

Specification Extraction Prompt

场景背景：

❌ Bad Case1（问题：丢失业务角色与业务规则，仅描述技术实现）

✅ Good Case（正确：覆盖业务+技术，逻辑闭环）

❌ Bad Case2（类比/省略）

✅ Good Case（完整/无省略）

name: function-level-defect-tracer description: 基于 MR 的 source commit id 与 target commit id，对本次 MR 变更内容进行差异分析与定位（文件/函数级），输出变更摘要、关键 diff 片段索引与风险点，供缺陷校验使用。

Goal

When to use

Inputs

Input example

Outputs

Output example(shape)

Procedure

Guardrails

name: business-rule-defect-detector description: Detects business logic defects in code changes by verifying alignment with PRD/TRD requirements. Invoke after analyzing requirements and code diffs.

Prerequisites

Role & Goal

Review Steps

第一步：提取关键信息

第二步：跟踪调用链与深度审查

2.1 完整跟踪调用链

2.2 逐行梳理代码，验证“逻辑覆盖度”

2.3 结构体与字段校验

第三步：整合输出bug列表

第四步：生成飞书分析报告

报告生成要求：

Output Requirements

Important Principles

name: trd-spec-extractor
description: "Extracts technical specifications from TRD documents (Feishu), mapping business rules to technical implementations. Invoke after PRD analysis when a TRD is available."

name: function-level-defect-tracer
description: 基于 MR 的 source commit id 与 target commit id，对本次 MR 变更内容进行差异分析与定位（文件/函数级），输出变更摘要、关键 diff 片段索引与风险点，供缺陷校验使用。

name: business-rule-defect-detector
description: Detects business logic defects in code changes by verifying alignment with PRD/TRD requirements. Invoke after analyzing requirements and code diffs.