代码库理解与影响分析

---
name: codebase-understanding-and-impact-analysis
description: 在动代码之前，先搞清"改哪里、影响谁、有什么风险"。用于新变更立项、接手陌生模块、评估修改波及面。产出 `变更/<id>/影响分析.md`。
---

# 代码库理解与影响分析

## 何时使用

- 接到一个新变更 / 需求，需要先摸清现状。
- 接手陌生代码或跨模块修改。
- 修复缺陷前，评估"改这一处会不会碰坏别处"。
- 任何**改动前**的时刻：本技能是流水线的第一站。

## 不可跳过的前置

1. 读 `.agents/context/代码地图.md`、`模块边界.md`、`领域模型.md` —— 建立全局观。
2. 读 `.agents/rules/架构边界.md`、`API与兼容性规则.md` —— 明确红线。
3. 查 `.agents/memory/经验与陷阱.md`、`常见排查路径.md` —— 看别人踩过的坑。

## 输入

- 变更说明（`变更/<id>/变更说明.md`）或一句需求描述。
- 产品输入（`产品输入/`），如相关。
- 真实代码库。

## 步骤

1. **定位入口**：根据需求关键词，在代码库里找到入口（路由 / 命令 / 事件 / API handler）。
2. **画出调用链**：从入口向下追 2–3 层，标出经过的模块、服务、函数。
3. **识别契约面**：这次改动是否触碰 API、事件、DB Schema、共享类型、前端 props？逐一列出。
4. **列出影响面**（分类，别混在一起）：
   - **代码**：哪些文件 / 模块要改，哪些只读不改但要回归。
   - **契约**：API / 事件 / Schema 是否变更；是否破坏兼容。
   - **数据**：是否涉及数据迁移、回填、删改。
   - **用户**：可见行为变化？UI 变化？默认值变化？
   - **依赖**：是否要升级 / 新增第三方库。
   - **运行**：配置、环境变量、权限、资源用量是否变化。
5. **标风险等级**：对每项影响标注 高 / 中 / 低，并写明理由。
6. **列出待确认问题**：不清楚的地方**不要猜**，明确写出"需向用户/负责人确认"。
7. **给出建议路径**：最小可行改动范围 + 推荐实现顺序（粗粒度）。

## 输出

写入 `变更/<id>/影响分析.md`（用 `.agents/templates/变更/影响分析.md`）。同时在对话中给出**不超过 15 行**的摘要：改哪里、影响面、最大风险、待确认项。

## 检查清单

- [ ] 至少画出一条从入口到出口的调用链。
- [ ] 影响面按「代码 / 契约 / 数据 / 用户 / 依赖 / 运行」六类分列。
- [ ] 每项风险都有等级和理由。
- [ ] 所有不确定项都写进了"待确认问题"，没有默默假设。
- [ ] 发现 `.agents/context/` 与真实代码不一致时，已记录待修正。

## 边界与禁止

- **禁止**在本阶段写业务代码（这不是实现步骤）。
- **禁止**臆测模块职责：以 `.agents/context/` 和真实代码为准，冲突时以代码为准并标记。
- **禁止**跳过风险分析直接给实现方案——那是下一个技能（`变更实现计划`）的事。
- 涉及数据删除 / 生产环境时，**必须**在影响分析中显式标注"不可逆"并提示需用户确认。