企业官网建设流程全解析

1. 配置文件的核心机制：先搞懂它在整个工具链里的位置

不少人拿到 Claude Code 这类命令行 AI 编程工具，第一件事就是甩给它一个任务让它跑起来，能用，但总觉得差点意思——Agent 对项目背景一无所知，每次都要你从头交代目录结构、技术栈、注意事项，聊到第三轮它就把前面的约束忘得差不多了，又回到“通用程序员”的平水准。

这时候就该轮到项目级配置文件上场了。

项目级配置文件，通俗点说就是给 AI 助手写一份“入职手册”。你在.claude/目录里放好规则文件，在项目根目录写好CLAUDE.md，Agent 每次基于这个项目开始工作时，都会先把这些内容加载进上下文，相当于它一上班就先读完了公司的规章制度、项目架构说明和代码风格规范。你不用在每次对话里重复“我们用的是 Python 3.11 + FastAPI + PostgreSQL，请遵循 PEP8”，它自己就知道。

这套设计解决的核心问题有三个：上下文一致性、批量复用、团队共享。

• 上下文一致性：Agent 每次启动都是一个新的会话，没有记忆。配置文件就是它的外部记忆，确保不管谁在那个目录下启动会话，看到的都是同一套项目约束。
• 批量复用：不用每次重复输入项目背景说明，配置一次全项目生效，遇到跨目录操作时也能保持一致的行为逻辑。
• 团队共享：配置文件可以提交到 Git 仓库里，全组成员共用一套规则。新成员接手项目时，Agent 的行为基线不会因为个人使用习惯不同而跑偏。

如果你之前只用过全局配置，也就是~/.claude/CLAUDE.md那一层，那你其实一直是在给所有项目写同一份手册。只要换一个技术栈完全不同的仓库，全局配置里的“我们是 Python 项目”就会变成噪音甚至误导。项目级配置的意义就在于把“公共规则”和“项目专属规则”拆开，各管各的。

提示：项目级配置的读取优先级高于全局配置。也就是说全局配置里写了“默认用 pipenv 管理依赖”，但你的项目配置里写了“本项目使用 uv”，Agent 会以项目配置为准。这一点后面讲到多层级配置模型时还会细说。

2. 配置文件放哪、优先级怎么定：先搞清楚加载机制再动手

很多教程上来就贴字段示例，但你先别急着复制，路径搞错了一切白搭。Claude Code 的配置加载遵循一套清晰的层级规则，理解了这个，你才知道每个文件该写什么、不该写什么。

2.1 项目级配置的标准目录结构与文件形态

项目级配置主要由两个部分组成：

一是根目录下的CLAUDE.md指令文件。这个文件是项目文化、技术约束、开发约定的集中地，Agent 在项目内工作时会反复引用它。名字是固定的，不要自作主张改成PROJECT.md或者AGENT.md，工具认的是CLAUDE.md这个文件名。

二是.claude/目录。这个目录下可以放多个配置文件：

.claude/ ├── settings.json # 工具行为配置：权限、模型参数、自动批准规则 ├── CLAUDE.md # 目录级指令文件（可选） ├── commands/ # 自定义斜杠命令目录 │ ├── review.md # /review 命令的实现文件 │ └── test.md # /test 命令的实现文件 ├── hooks/ # 事件钩子脚本目录 └── agents/ # 子 Agent 行为定义目录（视工具版本而定）

其中settings.json是核心的 JSON 配置文件，负责控制工具行为层面的内容：哪些操作需要人工确认、模型参数怎么调、环境变量怎么注入。CLAUDE.md则负责“软性”的指令和项目说明，比如技术栈描述、代码风格偏好、常见任务流程。

2.2 多层级配置模型与优先级规则

Claude Code 的配置遵循从全局到项目的多层加载逻辑，优先级可以简单记为：目录级 > 项目级 > 全局级，同一层级下越靠近当前工作目录的配置越优先。

具体来说有这几层：

• 全局层：~/.claude/CLAUDE.md和~/.claude/settings.json。这是个人偏好层，适合放通用规则，比如“所有代码注释用中文”、“提交信息遵循 Conventional Commits”。这一层与具体项目无关。
• 项目层：项目根目录的CLAUDE.md和.claude/settings.json。这一层放项目通用信息，比如项目是什么、用什么语言、核心模块怎么组织、构建命令是什么。
• 目录层：任意子目录下的.claude/CLAUDE.md（或经由配置指定的子目录指令文件）。这一层适合按模块定制规则，比如backend/.claude/CLAUDE.md里强调后端接口规范，frontend/.claude/CLAUDE.md里强调组件命名和样式规范。

这个优先级模型解决了一个很实际的问题：不用在一个文件里塞下所有规则。很多人一开始喜欢把全部约束堆在根目录的CLAUDE.md里，结果文件越写越长，Agent 的上下文被无效信息拖累，反而影响判断质量。正确的做法是分层、分流，把通用的放上层，把专属的放到底层。

2.3 为什么优先使用项目级配置而不是全局配置

我在实际使用中见过不少反例：有人把某个项目的细节写进了全局配置，结果跑其他项目时 Agent 时不时冒出上上个项目的“常识”，看起来像是上下文污染。全局配置应该只保留那些真正跨项目通用的东西，比如你的语言偏好、编码风格底线、禁用的操作方法。

项目级配置则完全以仓库为单位隔离。你可以在 A 项目里配置“使用 pnpm 作为包管理器、禁止直接修改 lock 文件”，在 B 项目里配置“使用 npm、允许升级依赖”，两者互不干扰。Agent 只加载当前工作目录对应的配置，不会串味。

3. 核心字段逐项拆解：把 Agent 调教成项目老兵

现在开始动真格的了。下面我把项目级配置文件里的核心字段逐个拆开讲，从职责、写法到实际效果，尽量让你看完就能直接“抄作业”。

3.1CLAUDE.md项目说明区：这才是真正的灵魂

很多人以为CLAUDE.md就是写给 Agent 看的 README，其实不完全对。README 是给人看的，重点是帮助人类快速了解和使用项目；而CLAUDE.md是给 Agent 看的“操作手册”，重点是让它知道在这个项目里怎么行为、怎么决策、怎么避免踩坑。

一个有效的CLAUDE.md通常包含以下模块：

项目概览：用 3-5 句话说明项目做什么、技术栈是什么、核心目录怎么划分。别写长，Agent 每次读取这部分都会消耗上下文预算，写太长等于浪费它的“脑容量”。

常用命令：启动命令、测试命令、构建命令、代码检查命令。这些是 Agent 最频繁需要执行的操作，写清楚它就不用猜了。

代码风格与约束：命名规范、文件组织规范、数据库访问方式、禁止使用的模式。这块写得越具体，Agent 生成的代码越贴近你的预期。

工作流说明：比如“改动数据库 schema 需要先写迁移脚本”“新增 API 需要同步更新接口文档”“提交前必须运行全部测试”。这些流程性约束是通用模型不知道的，只能靠配置告诉它。

核心架构约定：比如“后端采用三层架构，Repository 层禁止直接暴露给 Controller 层”“状态管理统一使用 X 库，禁止引入新的状态管理依赖”。

我见过写得好的CLAUDE.md和写得差的，差别不在于长度，而在于是否聚焦在“Agent 容易犯错的地方”。比如一个 Python Web 项目，与其写“请写高质量代码”这种空话，不如写：

### 数据库访问 - 所有查询必须通过 Repository 层，禁止在 Service 中直接调用 ORM 的 session。 - 新增查询必须先评估是否命中索引，必要时通过 EXPLAIN 验证执行计划。 - 禁止使用 N+1 查询模式，涉及列表页时使用 lazy load 或 selectin load 优化。 ### API 响应格式 - 所有接口必须包装在统一响应结构里：{ code, message, data }。 - 分页接口必须包含 total、page、page_size 三个字段，禁止自定义分页格式。

这种写法等于直接告诉 Agent：哪些操作是红灯区，哪些模式是本项目的铁律。它生成代码时就不容易跑偏。

注意：CLAUDE.md不是越长越好。它能被完整加载的比例是有限的，太长会导致后面的内容被截断，反而起不到约束作用。我建议把整份文件控制在 100-150 行以内，核心规则优先靠前放。

3.2settings.json基础配置：权限、模型与自动批准

除了CLAUDE.md这种“软指令”，项目级配置还应关注settings.json里的“硬行为”配置。这块直接决定 Agent 在项目里的操作边界。

一个比较完整的settings.json示例：

{ "model": "claude-sonnet-4-5", "permissions": { "defaultMode": "acceptEdits", "allow": [ "Bash(npm run lint)", "Bash(npm run build)", "Bash(git status)", "Read(**)", "Edit(**)", "WebFetch(domain:docs.**)" ], "deny": [ "Bash(npm run delete:* )", "Write(/tmp/**)" ], "additionalDirectories": [], "disableBash": false }, "env": { "NODE_ENV": "development", "DEBUG": "api:*", "SKIP_AUTH_FOR_TEST": "true" }, "runInTerminal": false }

拆开来看：

model 字段：指定这个项目默认使用哪个模型版本。不同版本的模型擅长领域和上下文长度有差异。如果是纯前端项目，可能适合更侧重代码生成的版本；如果是数据密集的分析任务，选择强推理型号。全局没指定或命令行没加参数时，以项目配置为准。

permissions.defaultMode：这是所有工具类操作的基础闸门。可选模式主要有：

permissions.allow 和 permissions.deny：这是权限细粒度控制的重点。

allow列表里可以精确到具体的命令，格式是Bash(具体命令)。比如Bash(npm run lint)表示 Agent 不需要询问就可以直接运行 lint 命令。Edit(**)表示允许编辑任意文件。WebFetch(domain:docs.**)表示允许访问 docs 域下的网页。

deny列表则是一票否决。比如Bash(npm run delete:*)这种高危命令直接禁掉，Agent 就算想执行也会被拦下来。我特别建议在deny里加上删除类命令和危险系统操作，因为你永远不知道 Agent 会把命令参数拼成什么样。

env 字段：注入环境变量。有些测试环境需要特定的环境变量才能跑通，与其在每次对话里手动 export，不如直接写进配置，Agent 每次启动自动带上。

3.3 自定义斜杠命令与目录级配置：让常用操作一键触发

项目里会有一些高频操作，比如“跑全量测试”“检查代码风格”“生成迁移脚本”。如果每次都打字让 Agent 去做，既慢又容易因表达差异得到不同结果。更可靠的方式是把这些操作固化成自定义斜杠命令。

自定义命令放在.claude/commands/目录下，文件名就是命令名。比如创建一个review.md：

--- description: 执行完整的代码评审流程 argument-hint: 指定评审范围（可选） --- 请对当前分支相对主分支的变更执行代码评审： 1. 先运行 `git diff main...HEAD` 查看变更内容 2. 检查是否存在安全隐患、逻辑错误、性能瓶颈 3. 对照项目 CLAUDE.md 中的代码规范逐项核对 4. 输出评审结论时，每一条问题必须给出文件路径、行号和修改建议 5. 按照严重程度分级整理：阻断性问题 / 建议优化 / 风格微调

这样在项目里输入/review就能触发一个标准化的评审流程。好处是评审的维度、输出格式、严重程度分级每次都保持一致，不会因为 Agent 当时心情不同而改变套路。

目录级配置的原理也类似。在backend/.claude/CLAUDE.md里写清楚“后端代码必须经过三层架构拆分、禁止在 Controller 里写业务逻辑”，在frontend/.claude/CLAUDE.md里写“组件文件用 PascalCase 命名、样式使用 CSS Modules”。这样 Agent 在不同目录下切换工作时，会自动加载对应目录的“地方法规”。

4. 权限与安全配置的工程化落地：从能用进阶到可控

配置文件的另一个大头是权限与安全。很多个人开发者在这一块完全是默认配置跑到底，能用，但细想一下会冒冷汗——默认配置下 Agent 是有蛮大的操作自主权的，你要是没设好边界，它可能在你不注意的时候执行了删库级别的命令。

4.1 按权限梯度设计项目配置：我的四档方案

用了一段时间后，我总结出一个四档权限策略，大家可以根据项目信任度对号入座：

第一档：完全手动确认（适合新项目、不了解 Agent 项目）

{ "permissions": { "defaultMode": "acceptEdits", "allow": [ "Read(**)", "Bash(git status)", "Bash(git diff)", "Bash(ls **)" ] } }

只放开读取类操作和安全的 Git 查询命令，所有写操作都要人工确认。这样 Agent 能读代码、能给你建议，但不会擅自动手改。适合第一次接手的项目，先让它理解代码再说。

第二档：常规开发（适合日常迭代的稳定项目）

{ "permissions": { "defaultMode": "acceptEdits", "allow": [ "Edit(**)", "Read(**)", "Bash(npm run lint)", "Bash(npm run test)", "Bash(git add **)", "Bash(git commit -m *)", "Bash(uv run pytest **)", "Bash(tsc --noEmit)" ] }, "deny": [ "Bash(git push **)", "Bash(npm run deploy)**" ] }

编辑和常规构建命令自动放行，push 和部署这类影响外部系统的操作拦下来确认。这是我最常用的配置，效率和安全性平衡得正好。

第三档：高信任模式（适合熟悉的老项目、纯本地开发）

{ "permissions": { "defaultMode": "bypassPermissions" }, "deny": [ "Bash(git push **)", "Bash(rm -rf **)", "Bash(git reset --hard **)" ] }

所有操作自动执行，只对极少数高危命令设禁区。这个模式的效率确实高，但请务必只在沙箱环境或完全本地、无外部影响的项目里用。

第四档：CI 环境禁用（适合自动化流水线）

项目根目录下放一个.claude/settings.local.json或者通过环境变量控制，在 CI 环境里将交互权限关闭、禁用所有 Bash 操作。AI 编码工具在 CI 环境里不应该有执行权限，只允许它输出代码建议和 diff。

4.2 网络请求与数据外发控制：一个容易忽视的漏洞

说一个很多人踩过的坑：默认配置下，Agent 是可以发起外部网络请求的。只要你给了WebFetch权限，它就能去访问外部网页。如果项目代码里恰好有生产环境的密钥或内网地址，Agent 在分析代码时可能无意间把这些信息带进对外请求的上下文中。

虽然工具本身有隐私保护设计，但工程上仍建议在项目配置里做一层显式控制：

{ "permissions": { "allow": [ "WebFetch(domain:docs.**)", "WebFetch(domain:api.**)" ], "deny": [ "WebFetch(**)", "WebFetch(domain:*.example.com)" ] } }

意思是：只允许访问文档域名下的页面，其他外网请求全部禁止。另外，像数据库密码、API 密钥这类敏感信息，强烈建议通过env字段注入而不是写死在配置里，并且把.claude/settings.local.json这种可能含私密信息的文件加进.gitignore。

4.3 多项目管理时的权限模板与团队规范化

如果你的团队有多个项目，每个项目写一套权限配置会显得很冗余。我的建议是搞一个配置基线模板：把一个经过充分验证的settings.json文件作为标准模板提交到一个内部仓库，各项目复制后按需删减。

同时，配置文件的变更应该走代码评审流程。我在配置里加一条约定，让 Agent 在修改任何权限相关配置前必须停下来等待人工确认：

### 权限变更约束 - 修改 .claude/settings.json 中 permissions 相关的任何字段，必须先输出变更对比，说明为什么要放宽或收紧权限，等待用户明确确认后再执行。 - 禁止在没有人工确认的情况下将 defaultMode 从 acceptEdits 升级为 bypassPermissions。

这条规则能防止一个尴尬的场景：你自己手滑让 Agent“优化一下配置”，结果它默默把权限全打开了。

5. 常见问题与排查技巧实录：踩过的坑帮你填平了

配置这事，理论上讲得再清楚，实际一跑还是会遇到各种幺蛾子。我把自己用下来的高频问题和排查经验整理成一段实录，你们直接对号入座。

5.1 Agent 完全不理会CLAUDE.md里的规则

这个问题最气人——配置写了一大堆，Agent 好像一个字没看见。排查路径按顺序来：

• 先确认文件位置对不对。根目录的指导文件路径必须是CLAUDE.md，不是claude.md，不是CLAUDE.MD，不是README.md。大小写错误是新手最常见的原因。
• 确认当前会话的工作目录是否在项目根目录下。如果你从别的目录启动会话，Agent 加载的可能是另一个项目的配置。
• 确认文件编码是 UTF-8 无 BOM。如果文件里混入了特殊字符或编码问题，解析器可能读取失败。
• 检查全局配置里是否有冲突规则。比如全局配置写了“默认执行 A 方案”，项目配置写了“执行 B 方案”，优先级规则应该是项目级覆盖全局级，但如果你在全局配置里用了强指令词，可能会影响 Agent 的判断。

排查时可以在对话里直接问它：“项目配置文件里对数据库访问的约束是什么？”如果它能准确复述出来，说明加载成功；如果说不上来，说明加载链路有问题。

5.2 配置生效了，但行为跟预期不符

这种情况更隐蔽——规则是加载进去了，但 Agent 的理解和你的本意有偏差。问题通常出在措辞上。

比如你写“代码质量要高”，在 Agent 看来这是一句空话，因为“高”没有量化标准。你写“所有函数必须有类型标注，禁止使用 any”它就能明确执行。

另一个常见原因是规则互相矛盾。你写了“优先使用函数式编程”，后面又写“统一使用类封装业务逻辑”，Agent 会进入两难。排查时把这些规则当代码看，检查是否存在逻辑冲突、边界模糊、优先级不明确。

我也建议在CLAUDE.md里加一句冲突仲裁规则：

当本文件中的规则出现冲突时，按以下顺序裁决： 1. 涉及数据安全的规则优先于一切规则 2. 涉及性能优化的规则优先于风格偏好 3. 后文规则优先于前文规则 4. 具体场景规则优先于通用规则

这样 Agent 面对规则冲突时，有一套明确的仲裁逻辑。

5.3 权限放得太宽或太紧，怎么平衡

放得太宽的典型症状是：Agent 在你说“帮我跑一下测试”时，顺手执行了git push，然后你看着终端发愣。放得太紧的典型症状是：Agent 每读一个文件都要弹确认框，你点确认点到手酸。

我的建议是分两步调：

第一步，先把所有操作设为手动确认模式，然后在实际使用中记录高危操作清单。运行一周，你会很清楚 Agent 在正常工作中会触发哪些操作。

第二步，根据记录把那些高频、低风险、有明确命令形态的操作加入allow列表。比如Bash(npm run test)是安全的，Bash(npm install **)需要确认，Bash(rm -rf **)必须禁掉。

这样逐步把权限列表训练成适合你项目节奏的形态，而不是照抄别人的配置。

5.4 多成员团队使用不同版本工具导致配置不兼容

团队协作时这个坑特别现实：有人工具版本新一点，支持的新配置项多了；有人版本旧，遇到不认识的关键字就直接忽略。结果同样的项目配置，在不同成员手里行为不一样。

解决思路是在配置文件头部注明最低版本要求：

--- requires: 2.0.0 description: 项目级配置与工具行为约束 ---

同时在settings.json里加一个version字段标识配置版本号：

{ "version": "1.2.0", "model": "claude-sonnet-4-5", ... }

工具版本和配置版本双轨管理，升级工具前先看配置是否兼容，配置变更走一次评审流程。这听起来有点重，但项目大了、人多了，这种规范化能省掉大量“在我电脑上是好的”之类的问题。

5.5 配置文件的“上下文税”——太长反而坏事

前面提过CLAUDE.md不宜太长，这里我再补充一个真实场景。有人往CLAUDE.md里写了全文 300 行的规范，涵盖了编码规范、数据库规范、接口规范、部署规范、测试规范、Git 规范……每一条看起来都有道理，但问题是 Agent 的上下文窗口是有限的，配置太长不仅消耗预算，而且关键规则会被大量次要规则稀释，Agent 在生成代码时反而抓不住重点。

我的建议是给指导文件做分层拆分：

• 顶层CLAUDE.md：只写项目最核心的 10 条硬性规范，每条不超过两行。
• 子目录的.claude/CLAUDE.md：把各模块的专属规范下沉到对应目录。
• 详细规范文档：放docs/目录，在顶层配置里用“需要时查阅 docs 下的 XXX 文档”这种引用方式，而不是全文粘贴。

这样既保证了核心规则的强约束力，又让扩展规范按需加载，不会一次性占满上下文。

5.6 动态规则：一次配置跑不遍所有场景

最后补一个高级玩法：有些项目存在明显的“模式切换”场景，比如同样是后端项目，开发模式和生产模式的操作边界不一样；同样是接口开发，新增普通 CRUD 接口和写支付回调接口的注意事项完全不同。

对于这类场景，可以用 Agent 运行时读取的额外指令文件来做动态切换。比如在.claude/下建一个production-checklist.md：

### 生产环境变更检查清单 - 所有生产环境代码变更必须通过代码评审 - 涉及数据库变更的操作必须先模拟执行迁移脚本回滚方案 - 所有新增的环境变量必须记录配置说明 - 必须更新接口文档和部署文档

然后在项目CLAUDE.md里约定：当用户提到“准备生产变更”或“发布前检查”时，读取.claude/production-checklist.md并逐项核对。

本质上这是把技能扩展文件作为项目级配置体系里的“可插拔模块”，需要有它的时候才加载。跟把全文塞进指导文件相比，这个方案在上下文使用效率和灵活性上都要好不少。

6. 一套可以直接参考的项目级配置模板

前面把原理和坑都讲透了，最后给一套可以直接用的模板。我做了一个模拟项目 X 的配置样例，技术栈是 Python FastAPI + Vue 3 + PostgreSQL，你们可以根据自己的技术栈替换。

6.1 项目根目录的CLAUDE.md参考模板

# 项目 X 开发手册 ## 项目概览 项目 X 是一个面向企业客户的数据分析平台，提供数据接入、清洗、可视化和报告生成功能。 后端采用 Python 3.11 + FastAPI，前端采用 Vue 3 + TypeScript + Vite，数据库使用 PostgreSQL 15。 monorepo 结构：/backend 和 /frontend 两个子项目。 ## 常用命令 - 启动后端开发服务：`cd backend && uv run uvicorn app.main:app --reload` - 启动前端开发服务：`cd frontend && pnpm dev` - 后端测试：`cd backend && uv run pytest` - 前端测试：`cd frontend && pnpm test` - 代码检查（后端）：`cd backend && uv run ruff check .` - 代码检查（前端）：`cd frontend && pnpm lint` ## 代码风格与硬性约束 - 后端禁止在 Service 层直接拼 SQL，所有查询必须走 Repository 层。 - 所有 API 响应必须使用统一格式：`{ code, message, data }`。 - 前端组件命名使用 PascalCase，样式统一使用 CSS Modules，禁止使用全局 CSS。 - 禁止使用 `any` 类型绕过 TypeScript 类型检查。 - 所有时间字段统一使用 ISO 8601 格式存储和传输。 ## 工作流约束 - 新增或修改数据库字段，必须同步生成 Alembic 迁移脚本。 - 提交代码前必须运行对应模块的测试，禁止提交存在失败测试的代码。 - 涉及第三方 API 接入时，必须先检查环境变量配置说明文档，确认密钥来源。 - 修改核心数据模型时，必须先在对话中说明变更影响范围，等确认后再动手。 ## 依赖管理 - 后端依赖统一通过 uv 管理，禁止手动修改 pyproject.toml 中的依赖版本。 - 前端依赖统一通过 pnpm 管理，禁止直接修改 package.json 的版本号。

这份文件的核心是好执行——每一条规则都具体到“怎么做”而不是“应该怎样”。

6.2.claude/settings.json权限模板

{ "model": "claude-sonnet-4-5", "permissions": { "defaultMode": "acceptEdits", "allow": [ "Read(**)", "Edit(**)", "Bash(uv run pytest **)", "Bash(uv run ruff check **)", "Bash(pnpm test **)", "Bash(pnpm lint)", "Bash(git status)", "Bash(git diff)", "Bash(git diff --cached)", "Bash(git log **)", "Bash(git branch **)", "Bash(git fetch **)", "Bash(uv run alembic upgrade head)", "WebFetch(domain:docs.**)" ], "deny": [ "Bash(rm -rf **)", "Bash(git push **)", "Bash(git reset --hard **)", "Bash(psql **)" ], "additionalDirectories": [ "../shared-lib" ] }, "env": { "PYTHONPATH": "./backend", "NODE_ENV": "development" } }

这个配置的思路是：高频且安全的操作全部自动放行，影响远程仓库、数据库的危险操作一律拦截。additionalDirectories告诉 Agent 可以读取项目目录之外的shared-lib共享库，别卡在项目边界上。

6.3 子目录级配置示例：前后端各自立规矩

backend/.claude/CLAUDE.md：

# 后端目录专属规范 - 必须遵循三层架构：router -> service -> repository。 - Controller 层禁止包含业务逻辑，只负责参数校验和响应封装。 - Repository 层禁止返回 ORM 实体，必须转换成 DTO 再返回给上层。 - 所有数据库查询必须验证索引使用情况，新增查询需要附带 EXPLAIN 结果。 - 数据库事务统一使用依赖注入的方式管理，禁止手动 begin/commit。

frontend/.claude/CLAUDE.md：

# 前端目录专属规范 - 组件文件按功能特性组织，禁止按文件类型组织目录。 - 状态管理使用 Pinia，禁止引入 Redux 或其他状态库。 - API 请求统一通过 api 目录下的封装函数发出，禁止在组件内直接写 fetch。 - 所有列表页必须处理 loading、error、empty 三种状态。 - 路由配置统一维护在 router/index.ts，新增页面必须同步更新路由。

这套配置的优点是：Agent 在根目录下工作时，同时加载根目录和后端目录的规范；一旦进入frontend/目录干活，它会自动把前端规范带上，切换到对应语境。

7. 把配置当作团队资产来运营：最后的实践心得

配置写完不是终点，而是运营的起点。我见过太多团队配置文件提交到仓库里之后就成了“化石”文件，半年没人动过，里面的技术栈描述早就过时了，命令也跑不起来了。

我的习惯是把配置文件当作活文档来维护：

每次技术栈升级、目录结构调整、工作流变更，第一时间同步更新对应层的配置。项目里引入新的代码规范，及时沉淀到指导文件里。自定义命令清单每季度过一遍，删除没人用的，补充高频的新操作。甚至可以让 Agent 自己来维护：定期让它检查配置文件与项目实际状态是否一致，输出差异报告。

另外一个容易被忽略的点是配置文件的代码评审质量。CLAUDE.md里的规则一旦写错，Agent 会在整个项目生命周期里持续执行错误规则，影响面比一个 bug 大得多。所以凡是改指导文件，我都会带着“这条规则 Agent 能否准确理解执行？是否有歧义？是否与其他规则冲突？”这三个问题来审。

至于配置文件的演进方向，我现在比较关注的就是基于项目类型的配置模板化：同一个技术栈的项目，基础配置有七八成是通用的，沉淀成模板后，新项目只需改掉项目专属部分就能快速上手。这样既能保证质量基线，又能避免每个项目从零写配置的重复劳动。

配置这件事，本质上是把你对项目的理解和要求，转译成 Agent 能读懂、能执行的规则。转译得越准确，你花在纠偏和返工上的时间就越少。希望这篇内容能帮你少走我当年走过的那些弯路。