Back to Agent

AI Native 大型代码库开发工作流

名称

AI Native 大型代码库开发工作流

分类

skill

路径

skill/ai-native-large-codebase-workflow.md

描述

面向大型、多 repo、多模块协作项目的通用 Agent 工作流。用于先定位代码图谱、沉淀 Change Spec、控制上下文预算、拆分执行单元，并通过自动化测试和 review 闭环验证。

AI Native 大型代码库开发工作流

边界声明

本 skill 是通用工程化工作流，不定义任何产品定位、产品方向、业务范围或验收细节。

业务目标、使用场景、优先级、验收标准、约束条件都必须由业务方或需求提供方输入。Agent 只负责把这些输入转化为可执行、可验证、可交接的工程任务。

适用场景

当任务具备以下任一特征时启用：

  • 涉及大型代码库、多 repo、多 package 或跨模块调用。
  • 需求来自业务方描述、现有使用流程、问题反馈或跨模块改动，尚未明确改动文件。
  • 同时涉及多个技术层，例如界面层、服务层、数据层、接口契约、配置、权限或监控。
  • 单次会话上下文可能过长，需要拆分 session 或 sub-agent。
  • 用户希望产出可复用的 spec、方案、测试闭环，而不是只改一处代码。

不适用于非常明确的小改动，例如“把某个文案从 A 改成 B”。

核心原则

  1. 先定位，再实现 不要直接从需求跳到改代码。先找到入口、依赖、契约和必须修改的文件。

  2. wiki 做索引，代码做真相 repowiki、RAG、搜索结果只用于定位。最终判断必须回到当前分支源码、类型、测试和配置。

  3. 先 contract，再并行 跨技术层或多模块任务，必须先统一接口契约，再拆 session 或 sub-agent。

  4. 上下文是预算 只把决策信息留在主上下文。搜索结果、日志、候选文件用完后压缩进 spec 或丢弃。

  5. 输出必须可验证 每次实现都要绑定测试、构建、接口调用、页面检查、日志或监控中的至少一种验证方式。

标准流程

1. 需求澄清

先用最少问题确认任务边界。

必须明确：

  • 业务方或使用方要验收的目标是什么。
  • 本次要做什么，不做什么。
  • 是否涉及兼容性、权限、灰度、国际化、埋点、缓存或其他项目级约束。
  • 成功验收标准是什么。

如果信息不足，但可以安全默认，直接声明默认假设并继续。

2. 代码图谱定位

按最短路径检索，不做全量阅读。

优先顺序：

  1. 使用入口：页面、路由、命令、任务流、外部调用或系统事件。
  2. 调用入口：组件、状态、hooks/composables、API client、SDK 或任务调度。
  3. 接口契约：route/controller、DTO/schema、错误码、权限或协议定义。
  4. 实现入口：service/domain/model/repository、job、handler 或 adapter。
  5. 数据与配置：table、migration、feature flag、env、cache 或配置项。
  6. 测试入口：unit、integration、e2e、fixture、mock。

输出应控制在“必须读”和“可能相关”两类，不要把无关文件塞进上下文。

3. 产出 Change Spec

在动代码前生成一份短 spec，后续 session 和 sub-agent 都以它为准。

# Change Spec

## Goal
一句话说明业务方或使用方要验收的目标。

## Scope
- In:
- Out:

## Entry Points
- Client/UI layer:
- Service/API layer:
- Data/config:
- Tests:

## Current Behavior
当前实现如何工作，引用关键文件和函数。

## Target Behavior
目标行为、边界条件、异常处理。

## Contract
- Request:
- Response:
- Error:
- Permission:

## Files
- Must change:
- Likely change:
- Read only:

## Validation
- Type/lint:
- Unit:
- Integration:
- E2E/manual:

## Open Questions
仍需确认的问题。

4. 拆分执行

根据任务复杂度选择执行方式。

任务类型 推荐方式
单模块小改动 一个 session 直接完成
跨模块但同一技术栈 主 session 维护 spec，局部实现
多技术层联动 先产出 contract spec，再按责任边界拆 session
多 repo 或复杂排查 Explorer 定位，Worker 实现，Reviewer 审查
长任务上下文接近上限 compact 后用 spec 继续，不携带完整聊天历史

拆分时必须给每个 agent 明确：

  • 负责范围。
  • 禁止修改范围。
  • 输入 spec。
  • 预期输出格式。
  • 必须运行或说明无法运行的验证。

5. 实现约束

实现时遵循项目已有模式。

  • 优先复用现有组件、工具函数、类型、错误处理和测试结构。
  • 不引入新依赖，除非 spec 明确需要。
  • 不做无关重构。
  • 不把临时定位信息写进代码注释。
  • 不为了让测试通过而弱化类型、删除断言或跳过用例。

6. 验证闭环

实现后至少执行与变更相关的一种验证。

常见顺序：

  1. Typecheck 或编译。
  2. Lint。
  3. 相关单测。
  4. 相关集成测试。
  5. 关键入口或接口手动验证。
  6. 失败日志回读并修复。

如果验证失败，先判断是实现问题、测试 fixture 问题、环境问题还是既有问题。不要直接跳过。

7. Review 与交付

最终输出只保留高信号信息：

  • 改了什么。
  • 为什么这么改。
  • 跑了什么验证。
  • 还有什么风险或未覆盖项。

不要粘贴大量 diff、搜索结果或完整日志。

上下文预算规则

主上下文只保留：

  • Change Spec。
  • 已确认的 contract。
  • 必须修改的文件摘要。
  • 当前失败日志的最小片段。
  • 最新验证结果。

以下内容用完即丢或压缩：

  • 大量搜索结果。
  • 候选文件列表。
  • 完整日志。
  • 已排除方案。
  • 旧的中间推理。

当上下文明显膨胀时，先更新 Change Spec，再 compact 或拆 session。

Sub-agent 输出模板

每个 sub-agent 返回时使用以下格式：

## Scope
本 agent 负责什么。

## Findings
- 关键发现 1
- 关键发现 2

## Changes
- 修改文件:
- 行为变化:

## Validation
- 已运行:
- 结果:
- 未运行及原因:

## Risks
- 仍需主 agent 注意的问题。

禁止事项

  • 禁止把 wiki 或 RAG 结果当作最终事实。
  • 禁止在 contract 未统一前并行实现前后端。
  • 禁止把大量搜索结果直接塞给主 agent 汇总。
  • 禁止通过删除测试、放宽类型、吞掉错误来制造“通过”。
  • 禁止在未说明风险的情况下跨 repo 做大范围重构。