Map legacy project

Map Legacy Project

为刚接手的老项目生成一整套 AI 协作基础设施。核心目标不是“让 AI 一把改完”，而是先把项目资料扒清楚，让人能理解、能兜底、能检查，再让 AI 在后续改造中尽量改对。

优先做单个项目的原子认知：先建立这个仓库自己的架构、接口、数据模型、依赖和运行约定，再在 summary 里标记跨仓库、跨微服务或业务链路需要二阶段梳理的地方。

allowed-tools

使用最小必要工具：

• 读取与搜索：Read、rg、find、sed、head、tail、wc
• Git 只读：git status --short、git log --oneline、git diff --name-only、git diff --stat
• 结构化分析：必要时用短小的只读 python3 脚本解析路由、依赖、模型、SQL 或 DOT/SVG 文本
• 写入：仅用 apply_patch 写入本 skill 指定的基础设施资产
• 图表：可直接生成 SVG，或先写 Mermaid/DOT 再转为 SVG；最终产物必须是 .svg

禁止：

• 不要安装依赖、联网拉包、启动/停止服务、运行迁移或改数据库
• 不要修改业务源码、测试源码、生产配置、密钥文件或数据库迁移
• 不要输出 API key、token、password、secret 等密钥值；只允许输出变量名、文件路径和风险类型
• 不要生成其他 agent 生态的专属资产，除非用户明确要求兼容

可写产物边界

默认只创建或更新这些基础设施资产：

• docs/architecture.svg
• docs/module-deps.svg
• docs/external-deps.svg
• docs/api-list.md
• docs/data-model.md
• docs/data-model-er.svg
• AGENTS.md
• .agents/skills/docs-auto-sync/SKILL.md
• 最终 summary；如果用户要求落盘，保存为 docs/ai-infra-summary.md

如果目标文件已存在：

• docs/ 下同名资产可以更新，但要先读旧文件并保留仍然正确的信息。
• 如果 AGENTS.md 已存在且明显有人维护，不要直接覆盖；生成 AGENTS.generated.md，并在 summary 标记“需要人工合并”。
• 如果 .agents/skills/docs-auto-sync/SKILL.md 已存在且 name: docs-auto-sync，可以更新；否则生成 .agents/skills/docs-auto-sync/SKILL.candidate.md 并标记人工确认。

执行总流程

按顺序执行，每一步完成后自检，不合格就只修正本流程生成的资产。

1. 项目探测

先静态扫描项目边界和技术栈：

pwd
find . -maxdepth 3 \( -name 'README*' -o -name 'AGENTS.md' -o -name 'pom.xml' -o -name 'build.gradle*' -o -name 'package.json' -o -name 'pyproject.toml' -o -name 'requirements*.txt' -o -name 'go.mod' -o -name 'Cargo.toml' -o -name 'docker-compose*.yml' -o -name 'docker-compose*.yaml' -o -name 'Dockerfile' \) -print
git status --short 2>/dev/null || true
git log --oneline --max-count=30 2>/dev/null || true

识别并记录：

• 项目类型：单体、多模块、前后端分离、微服务聚合仓库、脚手架或库
• 主要语言和框架：Java/Spring、Node、Python、Go、Rust、前端框架等
• 入口和模块：启动类、Controller/Router、Service、Repository/DAO、任务、配置、前端入口
• 数据层：JPA/MyBatis/SQLAlchemy/Prisma/TypeORM、SQL 文件、Flyway/Liquibase/Alembic、数据库初始化脚本
• 运行方式：README、compose、Dockerfile、package scripts、Maven/Gradle task
• 敏感配置：只记录变量名和文件，不记录值

2. 生成三张全景图

确保 docs/ 存在，然后生成：

docs/architecture.svg

画分层架构图。每个核心模块写一句话职责。

最低要求：

• UI/API/后台任务/数据存储/中间件/外部服务分层清楚
• 如果是前后端分离，明确前端、网关/API、后端服务、存储之间的调用方向
• 如果是 Java/Spring，突出 Controller、Service、Repository/Mapper、Domain/Entity、Config/Security/Scheduler
• 如果是非 Java 项目，使用该项目真实框架命名，不强行套 Spring 术语

docs/module-deps.svg

画内部模块依赖图。

最低要求：

• 只展示项目内部模块，不把所有第三方包画进去
• 箭头方向统一为“调用方/导入方 → 被依赖方”
• 循环依赖用红色标出
• 对大项目先聚合到包/模块级，不要画到每个类导致不可读

docs/external-deps.svg

画对外依赖图，分三类并用不同颜色：

• 关键依赖：语言/框架/核心库，例如 Spring Boot、Spring AI、MyBatis、React、Vite、Flask
• 中间件：数据库、Redis、MQ、对象存储、向量库、注册中心、网关
• 外部 API：模型服务、OAuth、支付、短信、地图、搜索、企业内部 HTTP 服务

只展示服务名、变量名和用途，不展示密钥值。

3. 梳理接口清单

生成 docs/api-list.md。

通用要求：

• 按模块分组
• 区分对外接口和内部接口；无法确定时标记“需要确认”
• 每个接口列：方法、路径、说明、主要入参、返回结构
• 如果返回类型是 list[CategoryEntity]、Page[UserVO]、Response[T] 这类包装类型，要展开说明具体数据结构
• 标记认证/权限、分页、上传、下载、SSE/WebSocket/流式返回等特殊行为

技术栈识别：

• Java/Spring：扫描 @RestController、@Controller、@RequestMapping、@GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping、OpenAPI/Swagger 注解、DTO/VO/Record
• Node：扫描 Express/Fastify/Nest/Next API route、controller、router
• Python：扫描 Flask/FastAPI/Django route/view/schema
• Go/Rust：扫描常见 router 注册、handler、DTO/schema

4. 梳理数据模型

生成：

• docs/data-model.md
• docs/data-model-er.svg

以 DB 层为准，优先级：

1. 迁移脚本和建表 SQL
2. ORM 实体和映射
3. DTO/schema/entity
4. 代码查询关系和索引

docs/data-model.md 至少包含：

• 数据来源说明
• 枚举值
• 持久化模型：字段、类型、可空、主键、外键/逻辑外键、默认值、一句话说明
• DTO/VO/schema：字段、类型、用途，说明它们不一定等于数据库表
• 已发现的不一致：例如 model 与 migration 默认值不一致、逻辑外键没有数据库级约束

docs/data-model-er.svg 至少包含：

• 核心表/实体
• 主键和关键外键/逻辑外键
• 主要关系方向
• 对未声明数据库级 FK 的关系做“逻辑外键”标记

5. 自洽检查与修正

对照以下材料做一致性审查：

• docs/architecture.svg
• docs/module-deps.svg
• docs/external-deps.svg
• docs/api-list.md
• docs/data-model.md
• docs/data-model-er.svg
• 源码、配置、README

必须检查：

• 图中的模块是否在代码中存在
• 接口清单中的路径/方法是否能回到代码
• 数据模型是否以 DB 层为准
• 外部依赖是否来自依赖文件、配置或真实调用点
• docs 之间是否互相矛盾
• 是否意外输出了密钥值

如果发现问题，只修正本流程生成的资产。不要为了让文档自洽去修改业务代码。

6. 生成 AGENTS.md

基于 docs/ 下产物生成项目根目录 AGENTS.md。

要求：

• 控制在 300 行以内
• 不复制 docs/ 里的长内容，只链接到相关文档
• 包含这些章节：
  • 项目定位
  • 核心架构
  • 关键模块
  • 关键约定
  • 怎么跑
  • 禁区
  • 历史包袱
• “禁区”和“历史包袱”固定写“待 Robert 补充”
• 使用 Codex 语境，不写 Claude 专属说明

如果已有 AGENTS.md 且看起来有人维护，生成 AGENTS.generated.md 并在 summary 里说明需要人工合并。

7. 生成项目局部 docs-auto-sync skill

生成 .agents/skills/docs-auto-sync/SKILL.md。

要求：

• name: docs-auto-sync
• 中文 description，说明触发场景和产出
• 只读不写
• allowed-tools 最小化：Read、Grep/rg、find、sed、head、tail、wc、Git 只读命令
• 核心规则：只报告不一致，不自动修正
• 报告维度：API 文档、数据模型、依赖配置、架构图、README/AGENTS
• 输出表格：严重级别、类型、发现、事实来源、受影响文档、建议决策

不要生成其他 agent 生态的 docs-auto-sync 副本，除非用户明确要求兼容。

8. 生成最终 summary

最后输出 summary；如果用户要求落盘，保存为 docs/ai-infra-summary.md。

summary 必须包含：

• 每个产出文件的路径
• 每份资产的主要内容概括
• 自检中修正了哪些问题
• 仍需人工确认的地方
• 对多模块、微服务、前后端分离、无法确认的接口/数据关系的判断说明
• 后续建议：优先使用 docs-auto-sync 做增量文档漂移审计

不同场景适配

Java / Spring 项目

优先扫描：

• pom.xml、build.gradle*
• src/main/java/**
• src/main/resources/**
• @SpringBootApplication
• @RestController、@Controller
• @RequestMapping、@GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping
• @Entity、@Table、MyBatis mapper XML/interface
• Flyway/Liquibase/SQL 初始化脚本

前后端分离项目

分别识别：

• 前端路由、页面、状态管理、请求封装、构建脚本
• 后端 API、鉴权、中间件、服务层、数据层
• 网关或 Nginx 代理路径

图里要明确外部入口、前后端边界、API 前缀和部署关系。

多模块或微服务仓库

优先按模块生成原子认知：

• 每个模块职责一句话
• 模块之间依赖方向
• 外部依赖按模块归属
• 跨服务业务链路如果无法从单仓库确认，在 summary 标记“需要二阶段业务链路梳理”

不要一次性把多个仓库的源码混在一起生成大图；先每个项目生成自己的资产。

非 Java 项目

降级使用真实技术栈：

• Python：Flask/FastAPI/Django route、SQLAlchemy/Alembic、Celery/RQ
• Node/TS：Express/Fastify/Nest/Next API、Prisma/TypeORM/Sequelize、package scripts
• Go：router、handler、service、repository、sqlc/gorm/migrations
• Rust：router、handler、service、sqlx/diesel/migrations

不要强行使用 Java/Spring 术语。

质量门槛

完成前确认：

• 三张 SVG 都可读，颜色/箭头/图例清楚
• API 清单能追溯到代码
• 数据模型以 DB 层为准
• 外部依赖不泄露密钥值
• AGENTS.md 不超过 300 行
• docs-auto-sync 是只读报告型 skill
• summary 明确人工确认事项

如果某项无法确认，不要假装确认；在产物和 summary 中标记“需要确认”。