Phy Large Codebase Workflow — Phy 大型代码库工作流程

大型代码库工作流指南 核心原则 上下文是最稀缺的资源。 成功 = 分而治之 + 并行处理 + 持久内存。

项目基础架构设置 项目/ ├── CLAUDE.md # 全局指令 (<10k 字) ├── .claudeignore # 排除 node_modules、dist 等 ├── .claude/ │ ├── rules/ # 模块化规则文件 │ │ ├── backend.md │ │ ├── frontend.md │ │ └── testing.md │ ├── skills/ # 可重用的工作流 │ ├── agents/ # 自定义子代理 │ └── commands/ # 自定义斜杠命令

CLAUDE.md 规则 仅包括 Claude 无法从代码中推断出的内容 Monorepo：拆分 47k → 9k 字 = 大幅提高性能 每个规则： "删除此规则会导致错误吗？" 否 → 删除它

代码地图策略 减少会话启动成本 问题：每个新会话，Claude都会探索代码库 → 浪费 50%+ 上下文。 解决方案：预生成代码地图，Claude 读取 md 文件而不是探索。

推荐结构 .claude/ ├── CLAUDE.md # 简洁指令 └── codemaps/ # 预生成的代码地图 ├── architecture.md # 总体架构 ├── api-endpoints.md # API 列表 ├── components.md # 组件关系 └── data-flow.md # 数据流图

示例：architecture.md # 架构概述

入口点

• src/index.ts → 应用程序启动
• src/api/routes.ts → 所有 API 路由

核心模块

| 模块 | 路径 | 目的 | |--------|------|---------| | Auth | src/auth/ | JWT + 会话管理 | | API | src/api/ | REST 端点 | | DB | src/db/ | Prisma + 迁移 |

关键文件（先读这些）

• src/types/index.ts → 所有共享类型
• src/config.ts → 环境配置
• src/utils/ → 共享实用程序

常见模式

• 所有 API 处理程序在 src/api/handlers/ 中
• 中间件链：auth → validate → handler
• 错误格式： { error: string, code: number }

自动生成代码地图（一次性） claude -p "分析此代码库并创建综合代码地图。输出到 .claude/codemaps/architecture.md。包括：

• 入口点
• 模块职责
• 首先阅读的关键文件
• 数据流
• 常见模式"

在 CLAUDE.md 中引用 # CLAUDE.md

代码库快速入门

在探索之前阅读这些： @.claude/codemaps/architecture.md @.claude/codemaps/api-endpoints.md

命令

• pnpm dev - 启动开发服务器
• pnpm test - 运行测试

结果 新会话：读取 2-5k 标记（md 文件） 无代码地图：探索 50k+ 标记 10 倍上下文节省

保持代码地图更新 # 在重大重构后，重新生成 claude -p "更新 .claude/codemaps/architecture.md 基于当前代码库结构"

会话策略 每个会话一个目标 # 错误：一个会话中有多个无关任务 # 正确：明确目标，然后 /clear 之间的任务 claude # "将 auth 中间件迁移到 v2" /clear claude # "向 API 添加速率限制"

关键命令 命令 何时使用 /clear 任务之间（强制） /compact 在 70% 上下文容量时 --continue 恢复上一个会话 --resume 从历史记录中选择

工作流：探索 → 计划 → 编码 → 提交

• 探索（计划模式）

"读取 /src/auth 并了解会话处理" 只读，不修改代码

• 计划

"我想添加 OAuth。哪些文件需要更改？创建详细计划。" 输出到 SPEC.md 或 plan.md

• 实现（正常模式）

"从计划中实现 OAuth 流程。编写测试，运行测试，修复失败。" 始终提供验证：测试、截图、预期输出

• 提交

"提交具有描述性消息并打开 PR"

子代理策略（大型项目的关键） 为什么使用子代理 每个子代理都有独立的上下文窗口 不会污染主会话 可以并行运行 7 个

使用模式 # 调查 "使用子代理调查身份验证如何处理令牌刷新" # 并行审查 "使用子代理同时运行安全扫描器、样式检查器和测试覆盖率" # 验证 "使用子代理审查此代码以查找边缘情况"

内置子代理类型 代理 目的 访问 Explore 代码搜索、理解 只读 Plan 架构设计 只读 security-reviewer 安全审计 读取、Grep、Glob code-reviewer 代码审查 读取、Grep、Glob

使用 Git 工作树的并行开发 # 创建独立工作树 git worktree add ../project-auth feature/auth git worktree add ../project-api feature/api # 在每个工作树中运行单独的 Claude 会话 # 会话 A：重构 auth # 会话 B：构建 API # 会话 C：编写测试

编写者/审查者模式 会话 A 编写代码 会话 B 使用干净的上下文审查（避免自我偏见）

批处理和自动化 # 批量迁移文件 for file in $(cat files.txt); do claude -p "将 $file 从 React 迁移到 Vue。返回 OK 或 FAIL。" --allowedTools "Edit,Bash(git commit:*)" done # CI 集成 claude -p "分析此 PR 以查找安全问题" --output-format json

要避免的反模式 反模式 症状 解决方案 每个会话重新探索 50% 的上下文丢失 在启动时 预生成代码地图