企业官网建设流程全解析

1. 项目概述：一个为LLM开发而生的“组织记忆”系统

如果你和我一样，每天都在和Claude Code、Cursor、Gemini CLI这些AI编程工具打交道，那你一定遇到过这样的困境：每次开启一个新项目，或者换一台机器，那些好不容易调教出来的、能让AI写出高质量代码的“魔法指令”和规则，又得从头再来一遍。更头疼的是，团队协作时，每个人的AI助手都遵循着不同的“行事准则”，导致代码风格、安全规范、测试习惯千差万别，Review起来简直是一场灾难。

ai-config这个项目，就是为了终结这种混乱而生的。它不是一个简单的配置文件合集，而是一套基于本体论驱动的LLM开发智能体配置系统。它的核心思想非常迷人：将那些在真实开发事故中形成的、血泪教训般的规则，视为“组织的伤疤组织”——只有当一个错误重复发生时，才增加一条规则来防止它再次发生。所有规则都沉淀在一个名为AGENTS.md的单一文件中，然后通过一个构建脚本，自动生成适配 Claude Code、Cursor、Gemini CLI、Codex CLI 等不同工具的专属配置文件。

简单来说，它解决了几个核心痛点：配置漂移（不同工具间规则不一致）、知识孤岛（个人经验无法团队共享）、以及安全风险（AI无意中写出包含硬编码密钥或危险路径的代码）。它通过“单一信源”和“默认安全”的设计，让AI真正成为可预测、可协作、高产的开发伙伴，而不是一个需要你不断纠正的、充满不确定性的黑盒。

2. 核心设计哲学与架构解析

2.1 “组织伤疤组织”哲学：从实战中生长的规则

ai-config最颠覆性的理念在于其规则的生成方式。它明确反对“预先设计”一长串理想化的规则清单。作者认为，冗长的规则列表只会被忽视——尤其是中间的部分。这背后有学术研究的支撑：LLM在处理长上下文时，会可靠地关注开头和结尾，而中间部分的信息则显著衰减（即“迷失在中间”现象）。

因此，项目的哲学是：规则即伤疤。每一条被加入AGENTS.md的规则，都必须源于一次真实的、重复发生的开发事故或低效模式。例如，只有当AI第二次写出rm -rf /some/important/path这样的危险命令时，才会增加一条“禁止使用未经验证的绝对路径进行删除操作”的规则。这种机制确保了规则的每一条都是高价值、高相关性的，避免了规则膨胀和无效噪音。

这种哲学在实践中意味着：

1. 启动成本极低：你不需要一开始就构思一个完美的规则集。从一个几乎空白的AGENTS.md开始，在开发中遇到问题，再针对性添加。
2. 规则高度可信：每一条规则背后都有一个（或一系列）具体的“战争故事”，团队成员在理解规则时，也能同步理解其背后的上下文和重要性，遵守意愿更强。
3. 动态演进：规则库会随着团队和项目成长而自然演进，淘汰过时的，强化关键的，始终保持精炼和有效。

2.2 单一信源与最小化暴露面

这是保障一致性和可维护性的两大技术支柱。

单一信源指的是所有规则的权威版本只存在于根目录的AGENTS.md文件中。开发者只能编辑这个文件。项目提供的build.sh脚本，其核心职责就是读取这个“真理之源”，然后根据各AI工具（Claude Code, Cursor等）的配置语法和结构要求，生成对应的、可直接使用的配置文件。

这样做的好处显而易见：

• 消除漂移：不可能出现Claude遵守规则A，而Cursor遵守规则B的情况。所有工具都源自同一套核心逻辑。
• 简化维护：修改规则时，只需在一处进行。build.sh会帮你同步到所有地方。
• 便于版本控制：整个团队的AI行为准则，可以像代码一样进行Code Review、Diff和追溯。

最小化暴露面则是对“迷失在中间”问题的工程应对。它要求AGENTS.md本身必须保持简短，并将最重要的规则前置。这强迫规则制定者进行优先级排序和精炼表达。一个冗长、不分轻重的规则列表，其大部分内容对LLM而言是无效的。因此，ai-config倡导使用简短、有力的规则来塑造AI的判断力，而非事无巨细的说明书。

2.3 本体论驱动与默认安全

本体论驱动是ai-config在技术深度上的体现。它将“模型”、“模式”、“知识图谱”视为一等公民。这意味着，规则不仅仅是“不要做什么”，更是教会AI理解你项目领域的概念、关系和约束。

例如，在一个电商项目中，你的AGENTS.md里除了通用的编程规则，可能还会定义：

• 概念：User（用户）、Product（商品）、Order（订单）。
• 关系：UserplacesOrder；OrdercontainsProduct。
• 约束：Order.totalAmount必须等于其包含的所有Product.price之和。

当AI在为你编写与订单相关的代码时，这些内化的本体知识会引导它生成结构更正确、业务逻辑更严谨的代码，比如自动在计算总价时关联商品表，而不是写死一个数字。这相当于为AI注入了领域模型的“常识”。

默认安全是一条不容妥协的底线规则。它明确禁止在代码、配置或注释中出现任何硬编码的路径、API令牌、密码或密钥。ai-config的规则会强制AI在需要此类敏感信息时，必须使用环境变量、配置文件（排除在版本控制外）或安全的密钥管理服务。这从根源上避免了敏感信息意外泄露到代码仓库的风险。

2.4 测试驱动开发内嵌

TDD（测试驱动开发）被直接作为一条核心原则写入哲学。要求“每个函数都必须附带测试”，并遵循“红→绿→重构”的循环。这不是一个建议，而是通过规则让AI强制执行的开发纪律。

当AI根据你的需求生成一个函数时，ai-config的规则会驱动它同时生成该函数的单元测试框架（例如，使用Jest、pytest等）。这带来了多重好处：

1. 提升代码质量：AI在编写实现代码时，就必须思考如何验证它，这通常会催生出更清晰、可测试的接口设计。
2. 生成即文档：测试用例本身就是函数用法的最佳示例。
3. 保障重构安全：当后续AI或开发者修改代码时，已有的测试套件能立即验证功能是否被破坏。

3. 项目结构深度剖析与生成逻辑

让我们深入ai-config的目录树，理解每个部分的作用和build.sh的生成逻辑。

ai-config/ ├── AGENTS.md # 【唯一编辑点】所有规则的源头 ├── build.sh # 【构建引擎】读取AGENTS.md，生成一切 ├── claude/ # Claude Code专属配置区（生成） │ ├── CLAUDE.md # 主规则文件，由AGENTS.md转换而来 │ ├── settings.json # Claude Code编辑器设置（模型、钩子、状态栏） │ ├── agents/ # 8个专家子智能体定义 │ ├── hooks/ # 会话钩子（如：注入上下文、管理状态） │ └── commands/ # 自定义斜杠命令（如/-review, /-ship） ├── cursor/ # Cursor专属配置区（生成） │ ├── user-rules.md # 用于粘贴到Cursor设置中的规则文本 │ └── rules/ │ └── global.mdc # 用于项目级.cursor/rules/文件夹的规则文件 ├── gemini/ # Gemini CLI专属配置区（生成） │ └── GEMINI.md # 适配Gemini CLI语法的规则文件 └── codex/ # Codex CLI专属配置区（生成） └── AGENTS.md # 适配Codex CLI语法的规则文件

核心文件解析：

1. AGENTS.md：这是整个系统的“大脑”。其内容结构通常遵循“哲学声明 -> 核心原则 -> 具体规则 -> 本体定义”的格式。build.sh脚本会解析此文件的Markdown结构，识别出章节、列表和代码块，然后根据目标工具进行转译。

2. build.sh：这是系统的“编译器和链接器”。它的工作流程如下：

   • 解析：读取AGENTS.md，将其内容结构化。
   • 转换：针对每个工具目录（claude, cursor, gemini, codex），应用对应的“模板”或转换规则。
     • 对于Claude Code：CLAUDE.md需要符合其特定的规则语法（可能包括# Rule标题、## When、## Then等部分）。agents/目录下的每个子智能体文件（如ontologist.md,modeler.md）可能对应AGENTS.md中的不同章节或标签。
     • 对于Cursor：需要生成两种格式。user-rules.md是纯文本，用于粘贴到GUI设置中；global.mdc是Cursor原生规则文件格式，包含YAML前端元和规则内容。
     • 对于CLI工具（Gemini, Codex）：通常生成一个简单的Markdown文件，因为这些工具通常在会话开始时通过-f或--instruction-file参数加载整个文件作为系统提示词。
   • 生成：在对应的工具目录下创建或更新所有文件。
   • 钩子安装：自动设置Git的pre-push钩子。这个钩子至关重要：它会在你执行git push前检查AGENTS.md是否有更改。如果有，它会自动运行build.sh重新生成所有配置文件，并检查这些生成的文件是否已被提交。如果未提交，它会阻止推送，确保版本库中的生成文件永远与AGENTS.md的修改同步。

3. Claude Code 的扩展生态：ai-config为 Claude Code 提供了远超简单规则的支持，这是一个完整的增强套件：

   • agents/：定义了8个专家子智能体。例如，“本体学家”智能体专注于从代码中提取和验证领域模型；“建模师”智能体擅长设计数据库模式和API接口。你可以在对话中通过特定方式激活它们，获得更深度的专业协助。
   • hooks/：会话钩子脚本。例如，可以有一个钩子在每次新会话开始时，自动将当前项目的技术栈和架构图作为上下文注入，让AI从一开始就“了解”项目。
   • commands/：自定义斜杠命令。如/-ship可能触发一个流程：运行测试、检查代码风格、生成提交信息、并创建Pull Request草案。/-review则可能对当前变更进行深度代码审查和安全扫描。
   • statusline.sh：一个可执行的脚本，集成到Claude Code的状态栏，实时显示当前活跃的智能体或上下文状态。

注意：build.sh的--symlink参数是一个高级用法。它不复制文件，而是创建符号链接。这意味着你对~/ai-config/claude/CLAUDE.md的修改会实时反映在~/.claude/CLAUDE.md。这适合单用户、多环境同步，但在团队协作中，通常推荐复制模式，以确保每个成员使用的都是经过构建和提交的确定版本。

4. 全平台配置实战与避坑指南

4.1 基础安装与初始化

第一步是获取并构建这个配置系统。

# 1. 克隆仓库到用户主目录下的一个固定位置，便于全局引用 git clone https://github.com/PR0CK0/ai-config.git ~/ai-config cd ~/ai-config # 2. 执行构建脚本。这一步是关键，它会生成所有工具目录并安装Git钩子。 ./build.sh

执行./build.sh后，你应该仔细查看终端输出。一个正确的构建过程通常会：

• 显示正在清理或创建claude/,cursor/等目录。
• 显示从AGENTS.md生成各个配置文件的步骤。
• 最后提示 Git 的pre-push钩子已安装成功。

实操心得：建议在首次安装后，立即对AGENTS.md做一次微小修改（比如加个注释），然后尝试git commit和git push。你会看到pre-push钩子被触发，自动重新构建并提示你添加生成的文件。这个“冒烟测试”能确保整个自动化流水线是畅通的。

4.2 配置 Claude Code：从基础规则到完整工作流

Claude Code 是目前ai-config支持最全面的工具，配置分为两个层级。

层级一：仅规则（快速入门）如果你只想先试试核心规则，只需复制生成的主规则文件。

cp ~/ai-config/claude/CLAUDE.md ~/.claude/CLAUDE.md

重启 Claude Code 后，这些规则就会生效。你会立刻感受到AI代码建议风格的变化，例如更强调测试、避免安全反模式等。

层级二：完整套件（推荐）要解锁全部能力，包括专家智能体、钩子和斜杠命令，需要完整部署。

# 复制主规则 cp ~/ai-config/claude/CLAUDE.md ~/.claude/CLAUDE.md # 复制编辑器设置（可能包含模型偏好、钩子开关等） cp ~/ai-config/claude/settings.json ~/.claude/settings.json # 复制智能体、钩子、命令三个核心目录 cp -r ~/ai-config/claude/agents ~/.claude/ cp -r ~/ai-config/claude/hooks ~/.claude/ cp -r ~/ai-config/claude/commands ~/.claude/ # 确保状态栏钩子脚本有执行权限 chmod +x ~/.claude/hooks/statusline.sh

配置验证与深度使用：

1. 验证智能体：在Claude Code聊天框中，尝试输入@Ontologist或@Modeler并加上你的问题。如果配置成功，AI会以该专家角色的口吻和知识深度来回应你。
2. 验证斜杠命令：在聊天框输入/，查看下拉列表是否出现了-check,-ship,-review等自定义命令。尝试对一个文件修改后使用/-review。
3. 检查状态栏：观察Claude Code窗口底部状态栏，看是否有来自statusline.sh脚本的动态信息（如当前项目类型、活跃规则集）。

常见问题一：斜杠命令不生效这可能是因为commands/目录下的命令定义文件格式不正确。打开~/.claude/commands/下的一个文件（如review.md），检查其结构。一个典型的命令文件需要包含TRIGGER（触发词）、DESCRIPTION（描述）和PROMPT（实际发送的提示词）等部分。确保这些部分符合Claude Code的插件文档要求。

常见问题二：钩子脚本未执行检查~/.claude/settings.json文件，确认其中正确引用了钩子脚本的路径。例如，应该有这样一段配置：

{ "hooks": { "sessionStart": "~/.claude/hooks/session-start.sh" } }

同时，确保被引用的.sh文件具有可执行权限 (chmod +x)。

4.3 配置 Cursor：全局与项目级规则

Cursor 的配置方式非常灵活，支持全局生效和按项目覆盖。

全局配置（一劳永逸）这是最常用的方式。你只需要打开 Cursor，进入Settings -> Rules for AI，然后将~/ai-config/cursor/user-rules.md文件中的全部内容复制粘贴进去，保存即可。此后，在任何项目中用Cursor打开，AI都会遵守这套规则。

项目级配置（精细控制）对于某些有特殊要求的项目（比如一个遗留项目有独特的代码风格，或者一个研究项目需要不同的规则），你可以为其设置专属规则。

# 在项目的根目录下执行 mkdir -p .cursor/rules cp ~/ai-config/cursor/rules/global.mdc .cursor/rules/

Cursor会优先使用项目根目录.cursor/rules/下的规则，如果不存在，则回退到全局规则。这实现了完美的“默认全局，特例覆盖”策略。

注意事项：Cursor的规则语法 (global.mdc) 是一种自定义格式，通常包含YAML头（定义名称、优先级等）和后面的规则正文。build.sh已经帮你完成了从通用AGENTS.md到这种特定格式的转换。你不应该直接手动编辑global.mdc，而应始终通过修改AGENTS.md并重新构建来更新它。

4.4 配置命令行工具：Gemini CLI 与 Codex CLI

对于习惯在终端工作的开发者，ai-config同样提供了支持。

配置 Gemini CLIGemini CLI 通常通过--instruction-file参数来加载长上下文指令。

# 创建Gemini CLI的配置目录（如果不存在） mkdir -p ~/.gemini # 复制生成的规则文件 cp ~/ai-config/gemini/GEMINI.md ~/.gemini/GEMINI.md

之后，你可以在启动Gemini CLI时这样使用：

gemini --instruction-file ~/.gemini/GEMINI.md "帮我写一个Python函数来解析JSON"

更高效的做法是将其封装成一个Shell别名（alias）或函数（function），放在你的~/.bashrc或~/.zshrc中：

alias my-gemini='gemini --instruction-file ~/.gemini/GEMINI.md'

配置 Codex CLI (OpenAI)Codex CLI（或类似的OpenAI CLI工具）配置方式类似。

# 全局配置：复制到用户主目录，作为默认指令集 cp ~/ai-config/codex/AGENTS.md ~/AGENTS.md # 然后在使用时引用，例如： openai --system-instruction "$(cat ~/AGENTS.md)" --prompt "Write a React component..." # 项目级配置：复制到项目根目录 cp ~/ai-config/codex/AGENTS.md ./AGENTS.md

4.5 高级技巧：项目指针与团队协作

ai-config提供了一个巧妙的“指针”模式，用于处理那些不能或不想直接复制配置文件的情况。

# 在项目根目录创建一个“指针”文件 echo "READ ~/ai-config/AGENTS.md BEFORE ANYTHING" > AGENTS.md

这个文件本身就是一个强大的指令。当你或你的队友在任何AI工具中打开这个项目时，这个位于根目录的AGENTS.md文件会被优先读取。里面的内容直接告诉AI：“在做任何事之前，先去阅读~/ai-config/AGENTS.md这个全局规则文件。” 这相当于在所有项目间建立了一个轻量级、动态的链接，确保它们都指向最新的、统一的规则源。

团队协作工作流：

1. 中央仓库：团队维护一个内部的ai-config仓库分支。
2. 个人克隆：每个成员克隆该仓库到本地（如~/team-ai-config）。
3. 更新与同步：当团队决定新增或修改一条规则（基于新的“伤疤”）时，在中央仓库的AGENTS.md中修改，提交PR，经过Review后合并。
4. 个人拉取与构建：成员定期git pull更新本地仓库，并运行./build.sh。
5. 配置更新：根据上述指南，更新各自的Claude Code、Cursor等工具的配置。
6. 指针文件：在共享的项目中，使用“指针文件”模式，确保所有成员和CI环境都引用同一套最新规则。

这套流程将AI辅助开发的规范纳入了标准的工程管理流程，使其成为团队知识资产的一部分。

5. 自定义与扩展：打造你自己的智能体规则库

ai-config开箱即用，但其真正威力在于你可以根据自己团队的技术栈、文化和痛点进行深度定制。

5.1 编辑你的 AGENTS.md

打开~/ai-config/AGENTS.md，你会看到一个初始的框架。你的编辑应遵循其哲学：

1. 从问题开始：不要凭空编造规则。在接下来的开发中，留意AI犯的重复性错误或产生的低效模式。
2. 精炼表述：用最简短的语言描述规则。例如：“永远为数据库查询添加超时设置。”、“绝不在日志中记录完整的用户对象，仅记录ID。”
3. 分类组织：使用Markdown二级标题 (##) 来对规则进行分类，例如：

   ## 安全规则 - 禁止硬编码任何形式的密钥、令牌、密码。 - 所有用户输入在用于数据库查询前必须进行参数化处理或转义。 ## 代码质量规则 - 每个导出的函数/类都必须有对应的单元测试。 - 函数长度不应超过50行，如果超过，必须考虑拆分。 - 优先使用具名导入（`import { something }`）而非默认导入。 ## 项目特定规则（针对你的项目） - 本项目使用 `axios` 作为HTTP客户端，禁止使用 `fetch` 或 `request`。 - 所有状态管理必须使用Zustand，禁止直接使用React Context或Redux。

4. 添加本体定义：在文件后部，可以增加一个“本体”章节，定义你的领域概念。

   ## 领域本体（针对电商项目） - **实体**：Customer（顾客）， Product（产品）， Cart（购物车）， Order（订单）， Payment（支付）。 - **关系**：Customer `has one` Cart; Cart `contains many` Product; Order `is created from` Cart; Order `has one` Payment。 - **约束**：Order.status 的流转必须是：pending -> paid -> shipped -> delivered，不能跳过或回退。

5.2 扩展智能体与钩子（Claude Code）

ai-config为Claude Code预留了强大的扩展能力。

创建自定义专家智能体： 在~/ai-config/claude/agents/目录下，你可以创建新的.md文件，例如performance-guru.md。文件内容可以这样写：

# 角色：性能优化专家 你是一个专注于系统性能、数据库查询优化和前端渲染效率的专家。你精通性能剖析工具，对算法复杂度敏感，并且总是能提出可量化的优化建议。 ## 核心原则 1. **测量优先**：在建议任何优化前，先询问或要求查看性能剖析数据（如Chrome DevTools Lighthouse报告、后端APM指标）。 2. **瓶颈驱动**：专注于解决最大的性能瓶颈，避免过早和微观优化。 3. **权衡意识**：任何优化都需考虑其复杂度、可维护性和收益的权衡。 ## 典型任务 - 分析慢查询，建议索引或查询重写。 - 审查前端组件，指出不必要的重渲染和内存泄漏风险。 - 设计缓存策略。

保存后，运行./build.sh，这个新的智能体就会被同步到你的~/.claude/agents/目录，在Claude Code中通过@performance-guru即可召唤。

编写自定义会话钩子： 钩子脚本可以在特定事件（如会话开始、文件打开）时自动运行。例如，创建一个~/.claude/hooks/project-context.sh：

#!/bin/bash # session-start 钩子：在Claude Code新会话开始时，自动注入项目上下文 PROJECT_ROOT="$1" # Claude Code会传入项目根目录路径 if [ -f "$PROJECT_ROOT/package.json" ]; then echo "## 项目上下文已自动加载" echo "**技术栈：**" cat "$PROJECT_ROOT/package.json" | grep -E '"name"|"version"|"dependencies"' | head -5 echo "" fi if [ -f "$PROJECT_ROOT/README.md" ]; then echo "**项目摘要（来自README）：**" head -10 "$PROJECT_ROOT/README.md" fi

然后在settings.json中配置这个钩子。这样，每次新对话，AI都会先看到这些关键信息。

5.3 适配其他AI开发工具

ai-config的架构是开放的。如果你使用的工具不在默认支持列表（如VS Code with Continue.dev、Windsurf等），你可以扩展build.sh脚本。

1. 分析目标工具的配置格式：研究该工具如何接受自定义指令或规则。是JSON配置文件？还是一个特定的Markdown文件？
2. 创建转换逻辑：在build.sh脚本中，添加一个新的函数，例如generate_for_continue_dev()。这个函数负责读取解析后的AGENTS.md内容，并将其转换为目标工具所需的格式。
3. 添加生成目录和步骤：在脚本的目录创建和主生成逻辑中，加入对新工具的支持。

这需要一些Shell脚本和文本处理的知识，但build.sh中已有的为Claude、Cursor生成逻辑就是最好的参考模板。通过这种方式，你可以将ai-config的“单一信源”哲学扩展到几乎任何AI编程环境。

6. 故障排除与效能评估

即使配置正确，在实际使用中也可能遇到问题。以下是一些常见情况的排查思路。

症状：AI似乎完全忽略了规则。

• 检查1：配置文件位置：确认生成的文件被复制到了正确的目录。特别是~/.claude/、~/.cursor/rules/这些路径是否准确。一个常见错误是复制到了/home/user/.claude但当前用户的家目录是/Users/username。
• 检查2：工具重启：Claude Code、Cursor等工具通常在修改配置文件后需要完全重启（不仅仅是刷新标签页）才能加载新配置。
• 检查3：规则冲突：如果你在工具的GUI设置里也手动添加了规则，可能会与文件加载的规则冲突。检查工具的设置界面，看是否有多个规则源，尝试暂时禁用GUI中的规则，只保留文件规则进行测试。
• 检查4：规则语法：打开生成的工具特定配置文件（如CLAUDE.md），检查其语法是否符合该工具的要求。可以尝试在工具中手动输入一条最简单的规则进行测试，以排除工具本身的问题。

症状：Git pre-push 钩子没有运行。

• 检查1：钩子文件权限：确保~/ai-config/.githooks/pre-push文件具有可执行权限 (chmod +x)。
• 检查2：Git配置：运行git config core.hooksPath查看Git的钩子目录是否被正确指向了~/ai-config/.githooks。build.sh应该设置了这一点。如果没有，可以手动设置：git config core.hooksPath ~/ai-config/.githooks。
• 检查3：手动测试钩子：在仓库中运行~/ai-config/.githooks/pre-push，看是否有错误输出。

如何评估ai-config带来的效果？量化AI辅助开发的改进是困难的，但可以从以下几个维度定性观察：

1. 代码审查负担：团队在PR中发现的、由AI引入的常见低级错误（如安全漏洞、风格不一致）是否显著减少？
2. 上下文切换成本：新成员或新项目接入时，是否需要反复向AI解释相同的基础规则和项目规范？
3. AI建议的采纳率：AI生成的代码、测试、提交信息，是否更频繁地可以被直接或稍作修改后使用，而无需推倒重来？
4. 团队认知负荷：关于“代码该怎么写”的争论是否减少了？因为规则已经内化到了AI这个“自动执行器”中。

我个人在深度使用类似的配置系统数月后，最深刻的体会是：它最大的价值不在于防止错误，而在于塑造一致性。它让AI从一个才华横溢但性格乖张的实习生，变成了一个深刻理解团队文化和项目规范、值得信赖的资深搭档。当你不再需要为括号换行、导入排序、测试遗漏这些琐事而分心时，你才能真正专注于解决那些真正复杂、有趣的工程问题。ai-config提供的，正是这样一套将团队智慧“编译”进AI工作流的底层基础设施。