AI 帮你写代码之前，先给它准备一间“办公室”——AI 辅助开发项目上下文管理（一）
引言：为什么 AI 也需要“一间办公室”？
如果你让一个刚入职的工程师立刻开始改代码，却不给工位、不给项目文档、不告诉他“这个项目是什么、代码在哪里、应该遵守什么规范”，结果会怎样？
AI 也一样。
2025 年之后，AI 编码工具（Cursor、Claude Code、GitHub Copilot、OpenAI Codex、Windsurf 等）已经从“偶尔帮忙补全一行代码”进化到“可以独立完成修改、测试、提交”的程度。但能力越强，对项目上下文的依赖就越重。
所谓“项目上下文”，就是 AI 理解一个项目所需的全部背景信息：
- 这个项目是做什么的？
- 技术栈是什么？
- 代码怎么组织？
- 构建、测试、部署分别用什么命令？
- 哪些能做、哪些绝对不能做？
这些信息原本散落在 README、会议纪要、群聊记录、老员工的大脑里。在 AI 辅助开发时代，我们需要把它们整理成一套结构化的“文件体系”——也就是本文要讲的 AI 工作区上下文管理。
你可以把它理解为：在让 AI 帮你写代码之前，先给它准备一间配置齐全的办公室。
一、AI 工作区是什么？
1.1 一句话定义
AI 工作区 = 一个项目为了让 AI 编码代理（Coding Agent）高效、安全、稳定工作而设计的文件与目录体系。
它不是某个工具专属的功能，而是跨工具、跨项目的通用工程实践。
1.2 传统开发 vs AI 辅助开发的文档需求
| 维度 | 传统开发 | AI 辅助开发 |
|---|---|---|
| 文档主要读者 | 人 | 人 + AI |
| 信息载体 | README、Wiki、群聊、会议 | 结构化文件 + 自然语言指令 |
| 更新频率 | 项目启动/上线时更新 | 持续演进，与代码同步 |
| 执行依赖 | 人阅读后手动执行 | AI 可直接读取并执行 |
| 出错成本 | 较低，人可兜底 | 较高，AI 可能“一本正经地做错” |
在 AI 辅助开发中，文件不再是“写给人看的说明”，而是可以直接被 AI 消费的指令集。文档写得好不好，直接决定 AI 是“帮手”还是“帮倒忙”。
1.3 一个类比：AI 工作区 = 新员工的“入职大礼包”
想象你正在给一位远程入职的资深工程师准备资料包。你需要给他：
- 公司介绍 → 让他知道公司在做什么（对应 README.md）
- 员工手册 → 告诉他怎么工作、遵循什么规范（对应 AGENTS.md）
- 办公室地图 → 让他知道各部门、各文件在哪里（对应项目结构）
- 项目蓝图 → 让他理解为什么这样设计、下一步做什么（对应项目方案）
AI 工作区做的，就是给 AI 准备这样一份大礼包。
二、四大核心文件：任何 AI 工作区的起点
在深入复杂结构之前，先把握四个最基础、最高频的概念：
| 文件/概念 | 核心受众 | 核心作用 | 类比 |
|---|---|---|---|
| README.md | 人类开发者（AI 也会参考） | 项目是什么、怎么跑起来 | 项目“门面说明书” |
| AGENTS.md | AI 编码代理 | 怎么工作、遵循什么规范 | 给 AI 的“员工手册” |
| 项目结构 | 人 + AI | 目录组织、模块划分 | 项目“骨骼与地图” |
| 项目方案 | 人决策层 + AI 全局理解 | 为什么这样设计、怎么落地 | 项目“蓝图与施工图纸” |
2.1 README.md：面向人的“门面说明书”
README.md 是项目的标准入口文档，回答的是：
- 这个项目是什么？
- 用了什么技术栈？
- 怎么安装、怎么运行？
- 怎么参与贡献？
关键提醒：README 不要塞满给 AI 的执行指令。官方建议把 agent 专属的内容放到 AGENTS.md 里，保持 README 对人的友好性。
2.2 AGENTS.md：面向 AI 的“员工手册”
AGENTS.md 是 AI 辅助开发领域最重要的新兴标准之一。
- 2025 年 8 月：OpenAI 将源于 Codex 实践的 AGENTS.md 作为开放格式正式发布（该格式由 OpenAI 首创，并与 Amp、Google Jules、Cursor、Factory 等多方协作演进）
- 2025 年 12 月：OpenAI 将 AGENTS.md 捐赠／贡献给 Linux 基金会下属的 Agentic AI Foundation（AAIF 由 OpenAI、Anthropic、Block 联合创立）
- 截至 2026 年：已被 60,000+ 开源项目采用，兼容 20+ 种主流 AI 编码工具与代理（如 Copilot、Cursor、Codex、Windsurf、Gemini CLI、Jules、Factory、Amp 等）
它通常包含：
- 项目概览
- 构建和测试命令
- 代码风格与命名规范
- 安全注意事项
- 提交和 PR 规范
一句话总结：README 告诉人“这是什么”，AGENTS.md 告诉 AI“怎么做”。
2.3 项目结构：AI 的“空间认知”基础
项目结构决定了 AI 能不能快速定位文件、理解模块边界、判断“新功能该放在哪”。
一个清晰的项目结构应该：
- 按功能/领域划分目录，而不是按文件类型堆叠
- 命名一致（统一 kebab-case 或 PascalCase）
- 层级不过深（一般 4-5 层以内）
- 在 README 或 AGENTS.md 中说明目录用途
2.4 项目方案：防止 AI “自由发挥”的锚点
项目方案（Technical Design / Project Plan）回答的是：
- 为什么选这个技术栈？
- 系统架构是什么样的？
- 数据模型和 API 怎么设计？
- 分几个阶段落地？
AI 没有“隐性知识”——它不知道你上周开会讨论了什么、为什么放弃 A 选择 B。项目方案把这些背景显性化，防止 AI 在代码里“自由发挥”。
三、文件生态：不止 AGENTS.md
随着 AI 工具越来越多，辅助文件也形成了一个完整生态。除了 AGENTS.md，常见的还有：
| 类别 | 代表文件 | 作用 |
|---|---|---|
| 项目规则 | AGENTS.md 、CLAUDE.md、.cursor/rules/\*.mdc、.github/copilot-instructions.md |
告诉 AI 怎么工作 |
| 本地覆盖 | CLAUDE.local.md（官方）、AGENTS.override.md（社区命名惯例） | 个人定制；命名仅为约定，须加入 .gitignore 才不入库 |
| AI 上下文忽略 | .aiignore、.claudeignore、.cursorignore | 控制 AI 读取范围，保护敏感数据、减少无关上下文 |
| 版本控制忽略 | .gitignore、.git/info/exclude | 控制文件是否入库；是"本地覆盖文件"不提交 Git 的真正前提 |
| 技能文件 | SKILL.md |
可复用的专项任务模板 |
| 工具连接 | .mcp.json |
连接外部工具和 API |
| 可复用提示 | .claude/commands/\*.md、.github/prompts/\*.prompt.md |
自定义命令模板 |
| 项目文档 | README.md、docs/architecture.md、ADR |
提供背景上下文 |
⚠️ 三点提醒
① 两类 ignore，目的不同，别混。 .claudeignore 管的是 AI 读不读，.gitignore 管的是 Git 收不收。想让 *.local.md 不进仓库，靠的是 .gitignore，而不是 .claudeignore。
② 原生"覆盖"＝就近优先，不是 *.override.md 命名。 AGENTS.md 的分层靠目录嵌套：代理自动读取目录树里离被编辑文件最近的那份，冲突时就近者胜出。优先级递进为：父目录 AGENTS.md → 子目录 AGENTS.md（就近胜出）→ 对话中的显式指令（最高）。*.override.md 只是社区命名惯例，并非规范机制。
③ "自动不提交"并不普适，多数情况要手动加。 只有同时满足 CLAUDE_CODE_NEW_INIT=1 + 运行 /init + 选择 personal 选项时，Claude Code 才会自动把 CLAUDE.local.md 写进 .gitignore；其余情况都得自己手动加。
这个生态就像一座冰山：
- 水面上：README.md、AGENTS.md，人人都会接触
- 水面下：工具专属规则、技能文件、忽略文件、MCP 连接等，决定了 AI 能不能稳定、安全、高效地工作
四、协作关系：这些文件是怎么一起干活的？
用一个简单的层次图来理解：
信息流向是：
- 项目方案提供全局设计依据
- AGENTS.md 提炼出 AI 执行规则
- README.md 补充项目和运行信息
- 项目结构提供空间和导航基础
四者协同，AI 才能既理解“为什么”，又知道“怎么做”，还明白“东西在哪”。
五、落地优先级：从 0 到 1 怎么开始？
你不需要一次性搭建完整工作区。以下是推荐的渐进路线：
| 优先级 | 行动 | 理由 |
|---|---|---|
| P0 | 创建 AGENTS.md |
覆盖面最广，对 AI 输出质量影响最直接 |
| P0 | 建立清晰的项目结构 | AI 和人类共同依赖的基础 |
| P1 | 维护 README.md |
项目基本规范，AI 也会参考 |
| P1 | 编写项目方案（至少含架构选型和核心约束） | 防止 AI 偏离技术方向 |
| P2 | 添加工具专属配置（CLAUDE.md、.cursor/rules 等） | 利用特定工具的高级特性 |
| P2 | 配置忽略文件 | 保护敏感数据，减少噪音 |
| P3 | 编写 SKILL.md、配置 .mcp.json | 复用工作流，连接外部工具 |
六、本系列预告
AI 工作区的知识体系可以归纳为三大块：
- 基础概念 —— README、AGENTS.md、项目结构、项目方案
- 生态全景 —— 官方标准、工具配置、技能文件、忽略文件
- 全自动化设计 —— 从“AI 辅助人”到“AI 自主工作”
本系列计划用 7 篇文章讲完：
- 第 1 章：AI 工作区大纲介绍（本文）
- 第 2 章：核心双文件——README.md 与 AGENTS.md
- 第 3 章：AGENTS.md 官方标准深度解读
- 第 4 章：辅助文件生态全景
- 第 5 章：项目结构与项目方案设计
- 第 6 章：全自动化智能体工作区的 8 层架构
- 第 7 章：实操落地——从 MVP 到完整工作区
写在最后
AI 辅助开发不是“把需求丢给 AI 就行”，而是一场工程化协作方式的重构。
你的工作区文件质量，就是 AI 能理解的上限。
下一章，我们会详细拆解工作区里最重要的两份文件——README.md 与 AGENTS.md——帮你写出一份“人看着舒服、AI 读着明白”的项目入口文档。
如果这篇文章对你有帮助，欢迎点赞、在看、转发。也欢迎在评论区分享各自在使用AI工作的经验
汇聚全球AI编程工具，助力开发者即刻编程。
更多推荐
8
0- 0
已为社区贡献1条内容
所有评论(0)