用途
codebase-analysis 是一个「分析发现」技能，定位为分析发现专家，目标是通过迭代调查循环，找出并记录代码库中的模式、规则和接口。
适用场景包括：分析业务规则与领域逻辑；发现代码库中的技术模式；调查安全、性能或集成相关区域；将发现记录到合适位置；执行「发现 → 文档 → 评审」的发现循环。
核心原则
分析是迭代的。每个循环都建立在此前的发现之上。应增量式地发现——每个循环只处理一个区域。
分析循环模式
每个循环包含三个阶段：
1. 发现阶段
- 顺序处理分析区域
- 根据缺失的信息，识别所有需要的活动
- 始终并行启动多个专家代理进行调查
- 在收到用户反馈后，识别新的研究需求
2. 文档阶段
- 根据研究结果更新文档
- 纳入用户反馈
- 应用特定类别的文档规则
- 只聚焦当前正在处理的区域
3. 评审阶段
- 向用户呈现所有代理的发现，包括：每个代理的完整回复（而非摘要）、冲突信息或建议、基于研究提出的内容、需要用户澄清的问题
- 呈现已发现的内容和仍存的问题
- 在进入下一循环前等待用户确认
循环检查清单：每个循环需自问是否已识别该区域所有需要的活动、是否已并行启动专家代理、是否按类别规则更新文档、是否呈现了完整的代理回复（而非摘要）、是否在下一循环前获得用户确认、是否还有更多区域需要调查、应继续还是等待用户输入。
分析区域与文档归类
- 业务分析：从代码库提取业务规则，研究领域最佳实践，识别校验与工作流模式，记录到 docs/domain/
- 技术分析：识别架构模式，分析代码结构与设计模式，审查组件关系，记录到 docs/patterns/
- 安全分析：识别安全模式与漏洞，分析认证与授权方式，审查数据保护机制，记录到 docs/patterns/ 或 docs/domain/
- 性能分析：分析性能模式与瓶颈，审查优化方式，识别资源管理模式，记录到 docs/patterns/
- 集成分析：分析 API 设计模式，审查服务通信模式，识别数据交换机制，记录到 docs/interfaces/
文档结构
所有分析发现归入对应类别：
docs/ ├── domain/ # 业务规则、领域逻辑、工作流 ├── patterns/ # 技术模式、架构方案 └── interfaces/ # 外部 API 契约、服务集成
文档决策标准
仅当以下全部条件满足时才将内容写入输出：
- 可复用——模式/接口/规则在 2 处及以上使用，或明显可复用
- 非显而易见——不是标准实践（REST、MVC、CRUD）
- 不重复——先检查已有文档：grep -ri "keyword" docs/structured
不应记录的内容
- 元文档（SUMMARY.md、REPORT.md、ANALYSIS.md）
- 标准实践（REST API、MVC、CRUD）
- 一次性实现细节
- 当应更新已有文档时产生的重复文件
代理委派进行发现
为调查启动专家代理时，使用如下结构：
FOCUS: [具体发现活动]
- 要查找什么信息
- 要识别什么模式
- 要提取什么规则
EXCLUDE: [范围外区域]
- [无关区域]：范围外
- 文档：推迟到文档阶段
CONTEXT: [调查背景]
- 分析区域：[业务/技术等]
- 此前的发现：[若上一循环有任何发现]
OUTPUT: 结构化发现，包括：
- 关键发现
- 识别出的模式
- 需要澄清的问题
- 建议
SUCCESS: 所有发现均有证据支撑并已记录 TERMINATION: 发现完成或受阻
循环进度跟踪
使用 TodoWrite 跟踪循环，例如：
Cycle 1: Business Rules Discovery
- [ ] Launch discovery agents
- [ ] Collect findings
- [ ] Document in docs/domain/
- [ ] Review with user
Cycle 2: Technical Patterns Discovery
- [ ] Launch discovery agents
- [ ] Collect findings
- [ ] Document in docs/patterns/
- [ ] Review with user
发现结果呈现格式
每个发现循环后：
🔍 Discovery Cycle [N] Complete
Area: [Analysis area] Agents Launched: [N]
Key Findings:
- [Finding with evidence]
- [Finding with evidence]
- [Finding with evidence]
Patterns Identified:
- [Pattern name]: [Brief description]
- [Pattern name]: [Brief description]
Documentation Created/Updated:
- docs/[category]/[file.md]
Questions for Clarification:
- [Question about ambiguous finding]
- [Question about conflicting information]
Should I continue to [next area] or investigate [finding] further?
分析总结格式
所有循环完成时：
📊 Analysis Complete
Summary:
- Cycles completed: [N]
- Areas analyzed: [List]
- Documentation created: [Count] files
Documentation Created:
- docs/domain/[file1.md] - [Brief description]
- docs/patterns/[file2.md] - [Brief description]
- docs/interfaces/[file3.md] - [Brief description]
Major Findings:
- [Critical pattern/rule discovered]
- [Important insight]
- [Significant finding]
Gaps Identified:
- [Area needing further analysis]
- [Missing documentation]
Recommended Next Steps:
- [Action item]
- [Action item]
输出格式
报告分析进度时：
🔍 Analysis Progress
Current Cycle: [N] Area: [Analysis area] Phase: [Discovery / Documentation / Review]
Activities:
Findings So Far:
- [Key finding 1]
- [Key finding 2]
Next: [What's happening next]
快速参考
- 循环模式：发现 → 文档 → 评审 →（重复）
- 并行优先：始终并行启动多个代理进行调查
- 适当归类：业务规则 → docs/domain/；技术模式 → docs/patterns/；外部集成 → docs/interfaces/
- 需要用户确认：进入下一循环前获得用户确认
- 基于此前循环构建：每个循环累积此前发现的上下文
限制
具体的安装方式、适用平台、支持的模型以及收费信息暂未提供。