一个人带一队 AI 干活，听起来像科幻片，但把 Claude Code 的工作区配好之后，这已经是我每天打开终端就看到的工作状态。这篇文章不聊什么宏大叙事，就讲讲我手里这个 AI 工作区的全貌：从目录结构、模型接入，到多个 AI 角色之间怎么分工协作，能直接抄作业的部分我都尽量写出来。适合正在用 Claude Code、或者刚打算用它管理复杂项目的人，哪怕你是第一次听说“AI agent”概念，看完也能知道这东西到底能替你扛多少活。

1. 一个人带一队 AI：为什么要搭一个“工作区”

1.1 单人团队的核心痛点

我先说一个很现实的问题：如果你只是偶尔让 AI 帮你改一小段代码，那随便开个对话框就够了；但当你一个人要维护一个完整项目，需要 AI 帮你做需求分析、写代码、跑测试、查资料、写文档，这时候单个聊天窗口根本不够用。

原因很简单。每一次跟 AI 的长对话，背后都是一整段上下文。你跟它讲“这个模块要重构”，它记住了，但等你看完别的东西回来，再问它“刚才那个方案你怎么想的”，它已经忘了大半。上下文一乱，AI 就会开始一本正经地胡说八道——不是它蠢，是你没给它一个“稳定的工作环境”。

这就是工作区存在的意义。它不是简单的“把项目代码放在某个文件夹里”，而是一整套指挥系统：让 AI 知道自己在干什么、项目规则是什么、哪些工具可以用、哪些任务该找哪个“同事”帮忙。说得直白点，Claude Code 工作区就是给 AI 小队立规矩的地盘。

1.2 工作区不是文件夹，是一套“指挥系统”

我见过不少人，以为往项目里塞一个CLAUDE.md文件就算配置了工作区，结果 AI 该乱跑还是乱跑。实际上，一个完整的工作区至少包含四层东西：

第一层是项目规则，也就是CLAUDE.md这类记忆文件，告诉 AI 这个项目用什么语言、什么风格、哪些目录不能动；第二层是工具与权限，限定 AI 能用哪些命令、不能在哪些路径上操作；第三层是角色列表，也就是 subagent（子代理）定义，相当于你手里有几个“外包专员”，各有各的擅长方向；第四层是模型接入与上下文策略，决定这队 AI 用哪个大脑、上下文空间怎么分配。

这套东西配好之后，你的工作方式会从“跟 AI 聊天”变成“管理一队 AI”。你不再需要事无巨细地交代每一步，只需要下发任务、验收结果、在它们跑偏的时候拉一把。

1.3 为什么偏偏是 Claude Code

现在终端里的 AI 编程工具不少，各有各的拥趸。我选 Claude Code 当“领队”，主要是看中三点：

第一，它是终端原生的。我所有项目本来就是 git + 终端的工作流，AI 直接在终端里跑，能复用我已有的工具链，不用把代码搬到另一个编辑器里干活。第二，它对长任务和代码库的理解比较强。改一个大项目时，它能把跨文件的影响面盘清楚，而不是盯着一个文件硬写。第三，它的工作区机制足够灵活，可以通过配置把多个角色揉进同一个项目里，这正好戳中我“一个人带一队 AI”的需求。

当然，工具这东西各有偏好，但不管你用哪家的 agent，工作区的设计思路都是通用的。下面这些配置思路，换成其他同类工具也能参考。

2. 工作区核心配置：目录、规则与模型接入

2.1 先搞清楚 .claude 目录里到底放什么

Claude Code 在项目根目录下会有一个.claude/目录，这是整个工作区的心脏。我按自己的使用习惯，把它分成几个块：

.claude/ ├── CLAUDE.md # 项目总规则、记忆、行为边界 ├── settings.json # 权限、模型、环境变量等运行配置 ├── commands/ # 自定义斜杠命令，比如 /review、/todo └── agents/ # subagent 定义，每个角色一个 .md 文件

这个结构不是写死的，但你最好按“规则—配置—命令—角色”四个维度去组织。我见过有人把什么都塞进一个超大的CLAUDE.md，结果 AI 每次读规则要消耗大量上下文，还没开始干活就快把窗口用完了。规则文件只写“稳定不变”的东西，容易变的放 settings，这是很关键的一条经验。

另外说一句：CLAUDE.md放在项目根目录，除了.claude/里那一份，你还可以在子目录里放局部的CLAUDE.md，专门约束某个子模块的规则。AI 进入那个目录工作时会自动加载，相当于给每个子项目单独发了一本“员工手册”。

2.2 CLAUDE.md 怎么写：不是写作文，是立规矩

很多第一次用的人喜欢把CLAUDE.md写成“自我介绍”——“你是 Claude，一个 AI 助手”。这完全是浪费。真正有效的写法是把它当成“新员工入职手册”，要包含三类信息：

一是硬性边界。比如“禁止修改vendor/目录下的任何文件”“数据库迁移文件必须经过我确认”“所有对外接口变更必须更新 README”。AI 是执行力很强的员工，你不写边界，它就会很勤快地把不该碰的文件改了。

二是惯用写法。比如项目里的错误处理规范、命名习惯、测试怎么写。这些事你挨个项目交代很累，写在规则里之后，AI 每次都会自带这些背景知识。

三是项目地图。比如“核心业务逻辑在app/services/，公共工具在lib/utils/，测试在tests/”，让 AI 一进来就知道该去哪找东西。

我自己的经验是：每条规则尽量一句话说完，不要写长段落。AI 处理短句规则的效果比处理长篇大论稳定得多。还有一条很实用的技巧——规则数量控制在 30 条以内，太多之后 AI 容易“选择性失忆”，反而不知道该遵守哪条。

2.3 模型接入：官方 API、第三方兼容接口、本地模型

Claude Code 默认走 Anthropic 官方接口，但工作区里很可能需要接不同的“大脑”。我的做法是通过settings.json里的env字段统一管理环境变量，而不是散落在 shell 里。

{ "env": { "ANTHROPIC_MODEL": "claude-sonnet-4-5", "ANTHROPIC_BASE_URL": "https://api.xxx.com/v1", "ANTHROPIC_AUTH_TOKEN": "sk-xxx" } }

这里有个很容易踩的坑：如果你搭了第三方兼容接口，要确认它是 Anthropic 协议格式还是 OpenAI 协议格式。Claude Code 默认说 Anthropic 的语言，强行把 OpenAI 格式的接口塞进来，大概率会在请求头或者消息格式上栽跟头。对策也简单——要么选经过适配的网关，要么像我用本地模型时那样，在前面加一层协议转换的网关服务，把 OpenAI 兼容的本地端点翻译成 Claude Code 认识的协议。

以调用 LM Studio 里的本地模型为例，我常用的链路是：

# 1. LM Studio 启动本地推理服务，默认暴露在 1234 端口 # 2. 用一个协议转换网关指向 LM Studio export ANTHROPIC_BASE_URL="http://localhost:4000" # 网关地址 export ANTHROPIC_AUTH_TOKEN="local" # 本地网关通常不校验 token export ANTHROPIC_MODEL="qwen3-coder"

这样做的好处是，同一个工作区可以随时在不同模型之间切换，只需要改settings.json里的env，不用改代码，也不用重新打开项目。坏处是本地模型的推理速度、指令遵循能力跟云端旗舰模型有差距，所以我把本地模型定位成“干杂活”的角色——批量重命名、格式整理、生成测试数据这类体力活儿，放在本地跑又便宜又私密；真正需要深度理解代码的任务，还是切回旗舰模型。

2.4 上下文管理：窗口再大也经不起乱塞

不少教程爱吹“1M 上下文”，听起来挺吓人，好像什么都能往里装。可真在项目里干活就知道，上下文窗口再大，也是个有限资源。你塞进去一整个仓库的代码，AI 真正“专注”的注意力反而会被稀释，回答质量会肉眼可见地下降。

我的上下文管理原则有三条：

第一，能用规则文件承载的信息就不在对话里重复。项目规范写在CLAUDE.md里，AI 需要时会主动读，而不是我每次在 prompt 里啰嗦一遍。第二，任务按时切分，做完一个阶段就/clear开新会话。旧会话的结论沉淀成文件，新会话从文件续接，而不是硬拖着一个二万字的对话继续聊。第三，让 subagent 去“外挂记忆”。某个角色需要的背景知识写进它的定义文件里，它每次被调用时自动加载，不占用主会话的空间。

Claude Code 自带/compact这类自动压缩功能，上下文快满时会自动提炼重点继续干活。我个人的经验是：别等它自动触发，感觉对话超过一小时，主动手动压缩一次，提前把关键决策写进记忆文件，这比自动压缩更可控。

3. 从零搭建多角色 AI 团队：配置实操

3.1 安装与初始化环境

安装本身不复杂，我当前用的环境是 macOS + VS Code + 终端并存，但 Claude Code 核心是终端工具，所以重点说终端里的配置。

# 安装（任选一种方式） npm install -g @anthropic-ai/claude-code # 验证是否装好 claude --version

装完之后先在项目目录里跑一次claude，它会自动引导你完成登录/鉴权。这里我要特别强调一个我一直坚持的习惯：不要直接往系统环境变量里写 key，尤其不要把 key 提交到 git 仓库。正确做法是把密钥写进项目里的.claude/settings.json，并且确保.gitignore忽略掉有可能泄露的文件。团队项目还可以用更安全的密钥管理服务，让 Claude Code 通过环境读取——方法很多，但底线是“密钥不进 git”。

跑通之后，第一件事就是在项目根目录初始化规则文件：

claude # 进入交互界面后，可以用 /init 生成初始 CLAUDE.md # 也可以直接用编辑器新建 .claude/CLAUDE.md

3.2 定义自己的“外包小队”：subagent 实战

单人带一队 AI，最有价值的就是 subagent 机制。它相当于定义一批召之即来的“专项外包人员”，每个都专注一个细分领域。我在一个项目里常驻这几个角色：

• 资深审查员：只读代码、找问题，不直接改代码；
• 重构专员：专门做重命名、拆分函数、抽取公共模块这类结构性调整；
• 测试工程师：负责写测试、跑测试、汇总失败用例；
• 文档写手：负责 README、注释、变更日志；
• 调研情报员：负责查文档、查 API 用法，把结论总结回来。

每个角色就是一个 markdown 文件，放在.claude/agents/下。简化版长这样：

--- name: reviewer description: 资深代码审查员，负责从正确性、安全和可维护性角度审查代码改动，只输出审查结论，不修改代码 tools: Read, Grep, Glob model: claude-sonnet-4-5 --- 你是一位有 10 年经验的资深代码审查员。收到代码改动后，按以下顺序审查： 1. 先理解改动意图，再检查实现是否与意图一致 2. 检查边界条件：异常输入、空值、并发场景 3. 检查安全风险：注入、越权、敏感信息泄露 4. 检查可维护性：命名、结构、重复代码 输出格式： - 问题清单（按严重程度排序） - 修改建议 - 结论：通过 / 需修改后再审 绝对不要直接修改代码文件，你的职责是审查和提建议。

定义好之后，我在主对话里调用它干活，就像喊一个外包同事：

@reviewer 请审查一下刚才 refactor-billing 分支上的全部改动

它就会按自己的规则去读代码、输出审查意见，主对话的上下文不会跟着膨胀。这种“专人专事”的做法，让整个工作区的效率上了一个档次。

3.3 用任务列表做编排：把大项目拆成流水线

带一队 AI 干大活，最忌讳的是“一起上”。多个 AI 同时改同一批文件，结果就是互相覆盖、git 冲突满天飞。我的做法是：在主对话里用 todo 列表做编排，把任务串成流水线。

一个典型的重构流程长这样：

- [ ] 阶段 1：由重构专员拆分 payment_service.py，拆分结果逐文件列出 - [ ] 阶段 2：由测试工程师为拆分后的模块补单元测试 - [ ] 阶段 3：由资深审查员审查全部改动，输出问题清单 - [ ] 阶段 4：我确认后，由文档写手更新 README 和 API 文档

每完成一个阶段，我都会在对话里推进下一步，并让 AI 把阶段性结论写进项目里的.claude/记忆文件。新阶段开工前，我要先确认前一个阶段的产物真实存在、测试真的通过——AI 偶尔会“幻视”自己跑过测试，实际根本没跑。这个坑后面细说。

3.4 权限与安全设置：别让它乱跑命令

默认情况下，Claude Code 执行命令前会问你“是否允许”。一个人带了那么多 AI 角色，如果每个角色执行每条命令都要你点头，那你的“管理工作量”就大了。但反过来，如果放权放得太狠，AI 可能执行危险命令。

我的做法是分层授权：

{ "permissions": { "allow": [ "npm run test", "git status", "git diff", "ls" ], "deny": [ "rm -rf", "git push --force" ], "ask": [ "npm install", "git commit" ] } }

这套配置的逻辑很简单：高频、低风险的操作直接允许；危险操作直接拒绝，连问都不问；有风险但有时必须做的操作保留“每次询问”。实际操作中我还会把deploy、migrate这类影响生产环境的命令放进 deny 列表，非要执行时手动到终端里跑。这是我对“AI 干活”最基本的底线：可以替你写代码，但关键生产动作必须掌握在人手里。

4. 高频坑位与排查速查表

4.1 鉴权报错：403、organization disabled 这类问题怎么定位

用 Claude Code 最常撞见的就是鉴权类报错。常见提示里有这么一句：your organization has disabled claude subscription access for claude code。第一次遇到容易慌，其实这类提示的意思是“当前使用的账号/组织没有开 Claude Code 的访问权限”，属于组织策略限制，不是代码问题。

排查步骤我总结成一个固定套路：

1. 先确认当前实际用的是哪个 key、哪个账号。很多人环境变量里残留了旧 key，导致请求根本没走到预期账号；
2. 检查组织后台里 Claude 相关权限是否对当前账号开放；
3. 确认ANTHROPIC_BASE_URL指向正确，如果用了第三方或本地网关，报鉴权错很可能不是账号问题，而是网关的 key 配错了；
4. 最后再看命令行日志：claude --debug或打开 verbose 日志，看具体是哪一层的鉴权失败。

按这个顺序排查，90% 以上的鉴权问题五分钟内都能定位到根因。顺便说一句，我遇到最多的其实不是账号权限，而是环境变量互相覆盖——shell 里一个 key，settings.json里又一个 key，最终生效的是其中某一个，指向的账号还没权限，就会报出各种奇怪错误。

4.2 subagent 不干活：工具权限与隐藏依赖

有时候你明明定义好了 subagent，喊它干活它却“只读不改”，或者干脆说“我没有权限”。这时候八成不是它偷懒，而是定义文件里的tools字段没给够。

每个 subagent 能用的工具是白名单制，它在自己的规则文件里声明要用哪些工具。比如重构专员需要Edit、Write这类写文件的工具，审查员只需要Read、Grep、Glob。我遇到过最尴尬的一次：给“测试工程师”只配了读工具，结果它看完代码说“建议补充测试”，完全不写测试——不是它不想，是它工具列表里压根没有Write。

解决办法也很简单，角色定义文件里把工具列全，同时在settings.json的权限配置里给该角色放行相关命令。我习惯在定义文件里加一句“如果你缺少执行任务所需的工具，请明确告知，不要尝试用工具有限的方式硬做”——这句话能让 AI 在权限不足时主动曝光问题，而不是憋着干成半吊子。

4.3 模型换着用：风格丢失与参数调优

如果你像我一样经常在工作区里切换“大脑”，一定会发现一个现象：同一个任务，换了个模型，产出风格完全不一样。原来负责审查的角色切到本地小模型之后，审查意见明显变浅，甚至开始说套话。

我目前的调优思路是双轨制：对质量要求高的角色（资深审查员、重构专员）固定用旗舰模型，不轻易切；对批量杂活（重命名、格式整理、生成测试数据）才允许切到本地模型或廉价接口。同时，角色定义文件里要写清楚“输出标准”，比如审查员必须输出“问题清单 + 严重程度 + 修改建议”，不管背后是哪个模型，这个模板不能变。

还有一个小技巧：第三方兼容接口的模型名称要写对。不同网关对模型名的映射规则千奇百怪，写错一个字母，请求可能直接失败，或者悄悄给你换到默认模型——你以为在用 Qwen，实际在跑一个低配底座，效果能好才怪。

4.4 多会话并行：怎么避免“三个 AI 改同一个文件”

一个人带一队 AI，最刺激的时刻就是开了好几个终端会话，每个会话各带一个角色，分头并行干活。这套玩法效率很高，但翻车也很快。我踩过最大的坑就是：三个会话同时改同一个模块，改完一看，互相覆盖得面目全非。

现在我的并行策略是“文件级隔离”：在每个会话开工前，先明确这个会话的“势力范围”，在 prompt 里指定它只能碰哪些文件，其他一律只读。

本次任务你只能修改 src/billing/ 目录下的文件。 其他目录的文件一律只读，资料整理可以读，但不许写。 需要跨目录改动时，停下来告诉我，由我协调。

配套措施是开工前先git checkout一个新分支，每个会话用独立分支，最后我来合并裁决。这样即使某个角色跑偏，影响也局限在分支内，不会拖垮主干。经过几轮教训，我现在对并行 AI 的态度是：能串行就串行，非要并行必须画清边界。

4.5 一些我坚持了很久的习惯（个人向）

最后分享几条我已经固化成肌肉记忆的操作习惯。

第一，任何 AI 告诉我“已经完成”的任务，涉及关键文件的，我必须亲眼扫一眼 diff。不是我信不过 AI，是 AI 的“完成”和我的“完成”之间经常隔着一层理解偏差。第二，每天的 AI 会话结束后，花两分钟把当天的重要决策写进CLAUDE.md或者项目里专门的DECISIONS.md。这是给未来的自己和未来的 AI 留遗产，比任何“记忆功能”都可靠。第三，定期检查 subagent 定义文件，看看哪些角色已经不需要了，哪些角色的描述跟实际用途不一致。工作区是活的东西，不是配一次就完事的。

带一队 AI 干活，本质上是在建设一套“人机协作的小型组织”。一开始我也不知道该给它多少权限、该定义几个角色、该在哪一步停下自己动手，全靠一次次跑偏和踩坑试出边界。你要问我什么最重要，我的答案不是工具，也不是模型，而是“边界感”——知道哪些事完全可以交给 AI，哪些事必须自己拍板。把这条想清楚，你的工作区才能越用越顺。