1. 聊天框一关上下文就归零团队协作里最贵的浪费你有没有算过这样一笔账同一个项目新开一个 AI 会话你要重新交代一遍技术栈、目录结构、命名规范、哪些文件不能动、接口返回格式长什么样。交代完AI 终于能干活了。第二天换个同事接手或者你自己换台机器这套交代又得从头来一遍。问题不在于 AI 不够聪明而在于上下文没有落盘。它活在聊天框里窗口一关就蒸发它活在你脑子里换个人就断线它活在一个越堆越长的CLAUDE.md里塞到几千行自己都不想翻AI 每次全量加载还烧 token、抓不住重点。这就是团队协作里最隐蔽也最贵的浪费知识没有沉淀成资产每次协作都在重复支付“重新交代”的成本。更麻烦的是口径漂移——同一件事今天你这么说明天同事那么说AI 给出的实现风格天天变代码 review 时才发现两套逻辑打架。治本的办法其实很朴素把这些上下文从聊天框和脑子里搬出来放进仓库和代码一起 commit、一起演化、一起 review。落到目录上就是给仓库开一个.ai/目录。这篇要交付的东西很具体一套可以直接复制的.ai/目录骨架、一段让 AI 帮你收敛现有上下文的初始化提示语、以及用 git 验证目录真的纳入版本控制的操作步骤。适合谁适合任何用 AI 辅助写代码、并且不止一个人在同一个仓库里干活的团队。哪怕你只有一个人只要项目活得够久这套东西同样省事。先说清楚一件事.ai/不是谁拍脑袋发明的野路子。CLAUDE.md、.cursor/rules、GEMINI.md、AGENTS.md这些约定文件本质都是“把规则放进仓库”。其中AGENTS.md是多家厂商共建的开放标准已经被大量开源项目采用。.ai/要做的是在这条路上再往前一步——从“一个文件”走到“一个分门别类的目录”。2. 为什么单文件 CLAUDE.md 撑不住从 AGENTS.md 到 .ai/ 目录的演进很多人第一反应是我塞一个大CLAUDE.md不就行了试过的人都知道单文件很快会撑爆。下面这张表是我自己踩过坑之后总结的对照你可以直接拿去评估自己的项目。单文件的问题具体表现目录怎么解装不下硬规矩 任务 领域知识 流程全挤一起几千行自己都不想读每块各管一摊职责清晰职责混改个任务模板跟领域知识挤一处改一行牵全身分别演化互不干扰检索难AI 每次全量加载一个大文件又烧 token 又抓不住重点按需加载用到哪块读哪块协作差两个人同时改同一个文件冲突不断不同目录不同人维护冲突面小拆成目录就两样关键好处每块各管一摊、能分别演化按需加载、用到哪块读哪块。这才撑得住长期协作。那.ai/里到底装什么以我维护的一个真实后端项目为例技术栈是 .NET但这套结构跟语言无关目录大致是这么分工的.ai/ ├── rules/ # 给 AI 的硬规矩怎么写、什么不能碰、什么必须先确认 ├── tasks/ # 把口头需求编译成的任务单带验收清单 ├── domains/ # 各业务域的领域知识这块代码到底在干什么 ├── flows/ # 关键流程怎么走的说明 ├── prompts/ # 固化下来、反复要用的提示词模板 └── README.md # 总规则文件串起这套目录该怎么用AI 干活就照这套来接个需求先编译成tasks/里的任务单改完代码再回头同步对应的domains/、flows/文档。需求进来、代码出去、知识库跟着一起长。最实在的好处是每开一个新会话AI 都能照这套目录快速恢复上下文、按统一口径干活你不用每次从头交代。这里要区分一下市面上 dotai 这类工具。它们大多解决的是“同步”——把一份规则分发到 Cursor、Claude、Gemini 各家的位置很有用。但它们没解决“治理”——这套规则本身会不会过期、谁来维护、怎么防它腐化。.ai/目录 版本控制恰好把治理这件事接上了规则和代码同源谁改的、什么时候改的、为什么改git log 里全有。如果你用的是 Claude Code它天然认CLAUDE.md用 Codex 或 Cursor认AGENTS.md。.ai/目录不跟这些约定冲突反而可以做一个“总入口”在CLAUDE.md或AGENTS.md里写一句“详细规则见.ai/README.md”把 AI 引到目录里按需读取。这样既兼容各家工具又避免了单文件膨胀。3. 可复制配置.ai/ 目录骨架 初始化提示语 接入参数这一节给你三样可以直接拿走的东西目录骨架的落地命令、初始化提示语模板、以及把 AI 工具接进来的配置片段。3.1 落地目录骨架在仓库根目录执行一次性把骨架建出来mkdir -p .ai/rules .ai/tasks .ai/domains .ai/flows .ai/prompts touch .ai/README.md然后往.ai/README.md里写总规则告诉 AI 这套目录怎么用。下面是我实际在用的模板你可以直接改# .ai/ 目录使用说明 本目录存放给 AI 协作的上下文与代码一同纳入版本控制。 ## 目录职责 - rules/ 硬规矩编码规范、禁止事项、必须先确认的操作 - tasks/ 任务单需求编译后的执行清单带验收标准 - domains/ 领域知识各业务域在做什么、关键实体与约束 - flows/ 流程说明关键链路怎么走、涉及哪些模块 - prompts/ 提示词模板反复使用的固定提示语 ## 使用约定 1. 新会话开始时先读本文件再按任务类型读取对应子目录。 2. 修改代码后同步更新受影响的 domains/ 与 flows/ 文档。 3. 新增硬规矩写入 rules/不要堆进本文件。3.2 初始化提示语模板现有上下文乱成一团从哪起步把下面这段提示语丢给 AI让它帮你收敛。注意别一次求全先搭起来。我用 AI 辅助开发但给 AI 的上下文现在很散一部分在聊天记录里 一部分塞在一个越来越长的 CLAUDE.md或 .cursorrules里还有一些只在我脑子里。 我想把它们收敛进一个 .ai/ 目录、纳入版本控制。 别动业务代码先帮我做两件事 1. 扫一遍当前项目和我现有的规则文件把散落的上下文按类型归一归 哪些是给 AI 的硬规矩、哪些是任务、哪些是领域知识、哪些是流程说明、 哪些是可复用的提示词模板。 2. 据此给我一个 .ai/ 目录的初始骨架列出该建哪些子目录、每个目录放什么、 建议先从哪几个建起不必一次到位并把我现有 CLAUDE.md 里的内容 拆分、归位到对应目录。 只输出骨架方案 归位建议先别替我写每个文件的具体内容。它给的是起步骨架不是终态。该建哪些目录、先从哪几个起、现有内容怎么拆你结合项目拍板。.ai/是跟着项目长出来的不是一次设计完的。3.3 把 AI 工具接进来如果你用 Claude Code在仓库根目录的CLAUDE.md里加一行指向.ai/# 项目 AI 协作规则 详细规则、任务单、领域知识见 .ai/README.md按需读取对应子目录。如果你用 Codex 或 Cursor认AGENTS.md同样加一句# AGENTS 本项目 AI 上下文统一存放于 .ai/ 目录入口见 .ai/README.md。如果你通过 API 方式接入模型比如在脚本或自建工具里调用需要配好三件套Base URL、API Key、Model ID。以 TaoToken 为例配置片段如下{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model_id: claude-sonnet-4-20250514 }API Key 在控制台的 API Keys 页面生成模型 ID 按你实际要用的填。把这段配置放进你的工具配置文件里就能让脚本也读到.ai/里的上下文。需要说明的是.ai/目录本身跟用哪家模型无关它只是把上下文落盘换模型、换工具都不影响。4. 验证请求用 git 确认 .ai/ 真的进了版本控制骨架建好、提示语跑完下一步是验证它真的被 git 管起来了。这一步很多人会漏结果.ai/躺在本地没提交同事拉代码根本看不到。先看状态git status你应该能看到.ai/下的文件出现在未跟踪列表里。如果没看到检查是不是被.gitignore误伤了——有些项目的.gitignore会写.*把点开头的目录全忽略掉。用这条命令确认git check-ignore -v .ai/README.md如果输出里有匹配规则说明被忽略了去.gitignore里加一行!.ai/放行。确认没被忽略后添加并提交git add .ai/ git commit -m chore: 初始化 .ai/ 目录沉淀 AI 协作上下文提交完用这条命令验证文件确实进了版本库git ls-files .ai/正常应该列出.ai/README.md以及你建的各子目录下的文件。如果只列出目录没列出文件说明空目录没被跟踪——git 不跟踪空目录往每个子目录里放一个.gitkeep或实际的说明文件即可touch .ai/rules/.gitkeep .ai/tasks/.gitkeep .ai/domains/.gitkeep .ai/flows/.gitkeep .ai/prompts/.gitkeep git add .ai/ git commit -m chore: 补齐 .ai/ 子目录占位再验证一次git ls-files .ai/这次应该能看到所有子目录下的文件。到这里.ai/就正式成为仓库资产的一部分了。同事 clone 下来AI 一读.ai/README.md就能恢复上下文不用你再口头交代。如果你想让 AI 直接基于这套上下文干活可以在模型对话里先贴.ai/README.md的内容再提需求。实测下来AI 给出的实现风格和项目规范的一致性会明显提升因为它不用猜了。5. 常见报错排查401、local proxy failed、reading choices、OAuth把.ai/接进工具链的过程中报错基本集中在这几类。下面按真实报错逐条对照。401 UnauthorizedAPI Key 没配、配错、或者过期。先确认配置文件里的api_key字段填的是控制台生成的完整密钥没有多余空格。如果你用的是环境变量检查变量名有没有拼错。401 基本就是认证没过跟.ai/目录本身无关但会挡住你验证上下文的效果。local proxy failed / connection refused工具在本地起了代理层但代理没起来或者端口被占。检查你的工具配置里base_url是不是写成了https://taotoken.net/api注意结尾不要多加斜杠。如果工具要求走本地代理确认代理进程在跑、端口没冲突。Error reading choices / choices 字段为空这类报错通常出现在响应解析阶段说明请求发出去了、也回来了但返回结构跟工具预期的不一致。常见原因是model_id填了一个不存在的模型名或者请求体格式不对。对照你的工具文档确认model_id是有效值请求体里messages字段结构正确。OAuth 相关报错如果你用的是 Claude Code 这类带 OAuth 登录的工具报错可能出在登录态过期或回调地址不匹配。先退出重新登录确认账号状态正常。如果工具支持 API Key 模式切到 API Key 模式往往更省事配置就是上一节那三件套Base URL、Key、Model ID。排查顺序建议固定下来先确认认证401 类再确认网络与地址proxy 类最后确认请求体与模型名choices 类。.ai/目录的问题不在这几类里它属于“文件有没有进 git”用第 4 节的git ls-files验证即可。另外提醒一句.ai/里不要放密钥、token、生产库连接串这类敏感信息。它是进版本控制的一旦提交就留在历史里了。规则、任务、领域知识、流程、提示词模板可以放凭证类一律走环境变量或密钥管理。6. 把上下文当资产从 API Keys 到接入文档的落地路径.ai/目录建起来只是第一步真正让它产生价值的是持续维护需求进来编译成任务单代码改完同步领域文档新规矩写进 rules。这套动作跟写代码一样纳入日常 review。如果你还没开始建议的落地顺序是先在仓库根目录建.ai/骨架跑一遍初始化提示语把现有CLAUDE.md的内容拆进去提交然后让团队里每个人下次开 AI 会话时先读.ai/README.md。跑一两周你会发现“重新交代项目”的时间明显下降。要动手的话先去控制台生成 API Key再对照接入文档把工具配好。密钥在 API Keys 页面拿接入细节看文档模型能力可以先在模型对话里试。如果团队要长期用 AI 编码、跑 Agent 任务Coding Plan 会更划算。上下文是资产资产就该进版本控制。.ai/目录就是这件事的起点。