yuxuanhui
91861565bb
- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
64 lines
4.0 KiB
Markdown
64 lines
4.0 KiB
Markdown
---
|
|
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 或可执行检查。
|