---
id: 20260715-codegraph-before-impact-analysis
title: 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文
created: 2026-07-15
updated: 2026-07-15
status: candidate
scope: global
category: agent-workflows
confidence: medium
last_verified: 2026-07-15
promotion_target: none
projects:
  - oppein-react-component
tags:
  - codegraph
  - impact-analysis
  - dependency-context
  - agent-workflows
---

# 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文

## Trigger

项目启用了 CodeGraph，且任务涉及跨包、跨目录或跨组件理解，调用链排查，重构、重命名、删除，或修改共享 API、类型、导出、hooks、服务接口和工具；也适用于需要评估回归范围或应补充哪些测试的任务。

## Context

当前项目的执行提示词将 CodeGraph 定位为影响分析的第一层上下文：先用代码关系索引缩小依赖范围，再回到源码、构建配置和精确文本核验，修改共享代码后再检查受影响文件和测试。这个流程既避免在陌生功能区盲目通读，也避免把图谱结果误当成完整事实。

## Evidence

- 2026-07-15：用户要求将当前项目的 CodeGraph 使用提示词沉淀到复利工程。
- `oppein-react-component/AGENTS.md:23-58`：记录了 CodeGraph 的触发条件、`status`/`sync` 规则、`explore`/`query`/`node`/`impact`/`callers`/`callees`/`affected` 的选择，以及源码核验和常规质量验证边界。
- 当前项目存在 `.codegraph/` 本地代码关系索引；该提示词明确要求首次使用时先检查索引状态。

## Root cause

已验证：代码关系图适合发现静态依赖、调用方和潜在影响范围，但不能可靠覆盖动态路径、字符串引用、构建配置和实现细节；索引过期时，图谱结论也可能失真。因此图谱只能用于缩小范围，不能单独证明“没有调用方”或“没有影响”。

推断：把 CodeGraph 放在影响分析前段，并固定接上源码核验与变更后测试范围检查，可以减少漏查共享调用方和遗漏回归测试的风险。

## Preferred action

1. 任务首次需要 CodeGraph 时先运行 `codegraph status`；仅在索引不是最新时运行 `codegraph sync`。不要自行执行 `init`、`index` 或 `uninit`，除非用户明确要求，或索引缺失且无法继续完成任务。
2. 按问题选择最小工具链：陌生模块用 `codegraph explore "<需求或模块>"`；查定义用 `codegraph query "<符号>"`，再用 `codegraph node "<符号>"` 阅读实现和调用链；修改共享 API 前用 `codegraph impact "<符号>"`，必要时补充 `callers` 和 `callees`。
3. 以图谱结果缩小源码阅读和搜索范围；修改前直接阅读相关实现，并用 `rg` 核对动态路径、字符串引用、构建配置和精确文本。
4. 共享代码修改完成后运行 `codegraph sync`，再用 `codegraph affected <改动文件>` 找出需要补充或执行的测试，最后仍按项目约定执行 lint、类型检查、构建和针对性测试。

## Boundaries

- 只有在项目启用 CodeGraph 且索引或对应 MCP 工具可用时，才直接套用这些命令；其他项目需先确认其工具和命令语义。
- 用户已指定文件和行，且只是局部文案、注释、格式或显然不影响外部行为的小改动，以及单文件、无公共接口变化的机械性修复，可以跳过 CodeGraph。
- CodeGraph 不能替代源码核验、`rg` 搜索、lint、类型检查、构建或测试；不要仅凭图谱结果断言不存在调用方或影响。

## Failed approaches

- 只依据图谱结果判断影响范围，会遗漏动态引用、配置驱动路径和未被索引覆盖的文本关系。
- 直接执行 `sync`、`init` 或 `index` 而不先检查状态，会增加不必要的索引操作，并可能偏离项目约定。

## Promotion record

- Not promoted. 当前只有 `oppein-react-component` 的一份项目证据；待在另一项目或独立场景复用并验证后，再考虑提升为全局 guidance、skill 或可执行检查。