企业官网建设流程全解析

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/里到底装什么？以我维护的一个真实后端项目为例（技术栈是 .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 Unauthorized：API 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/目录就是这件事的起点。