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这样的危险命令时才会增加一条“禁止使用未经验证的绝对路径进行删除操作”的规则。这种机制确保了规则的每一条都是高价值、高相关性的避免了规则膨胀和无效噪音。这种哲学在实践中意味着启动成本极低你不需要一开始就构思一个完美的规则集。从一个几乎空白的AGENTS.md开始在开发中遇到问题再针对性添加。规则高度可信每一条规则背后都有一个或一系列具体的“战争故事”团队成员在理解规则时也能同步理解其背后的上下文和重要性遵守意愿更强。动态演进规则库会随着团队和项目成长而自然演进淘汰过时的强化关键的始终保持精炼和有效。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订单。关系UserplacesOrderOrdercontainsProduct。约束Order.totalAmount必须等于其包含的所有Product.price之和。当AI在为你编写与订单相关的代码时这些内化的本体知识会引导它生成结构更正确、业务逻辑更严谨的代码比如自动在计算总价时关联商品表而不是写死一个数字。这相当于为AI注入了领域模型的“常识”。默认安全是一条不容妥协的底线规则。它明确禁止在代码、配置或注释中出现任何硬编码的路径、API令牌、密码或密钥。ai-config的规则会强制AI在需要此类敏感信息时必须使用环境变量、配置文件排除在版本控制外或安全的密钥管理服务。这从根源上避免了敏感信息意外泄露到代码仓库的风险。2.4 测试驱动开发内嵌TDD测试驱动开发被直接作为一条核心原则写入哲学。要求“每个函数都必须附带测试”并遵循“红→绿→重构”的循环。这不是一个建议而是通过规则让AI强制执行的开发纪律。当AI根据你的需求生成一个函数时ai-config的规则会驱动它同时生成该函数的单元测试框架例如使用Jest、pytest等。这带来了多重好处提升代码质量AI在编写实现代码时就必须思考如何验证它这通常会催生出更清晰、可测试的接口设计。生成即文档测试用例本身就是函数用法的最佳示例。保障重构安全当后续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语法的规则文件核心文件解析AGENTS.md这是整个系统的“大脑”。其内容结构通常遵循“哲学声明 - 核心原则 - 具体规则 - 本体定义”的格式。build.sh脚本会解析此文件的Markdown结构识别出章节、列表和代码块然后根据目标工具进行转译。build.sh这是系统的“编译器和链接器”。它的工作流程如下解析读取AGENTS.md将其内容结构化。转换针对每个工具目录claude, cursor, gemini, codex应用对应的“模板”或转换规则。对于Claude CodeCLAUDE.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的修改同步。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配置验证与深度使用验证智能体在Claude Code聊天框中尝试输入Ontologist或Modeler并加上你的问题。如果配置成功AI会以该专家角色的口吻和知识深度来回应你。验证斜杠命令在聊天框输入/查看下拉列表是否出现了-check,-ship,-review等自定义命令。尝试对一个文件修改后使用/-review。检查状态栏观察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-geminigemini --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.md4.5 高级技巧项目指针与团队协作ai-config提供了一个巧妙的“指针”模式用于处理那些不能或不想直接复制配置文件的情况。# 在项目根目录创建一个“指针”文件 echo READ ~/ai-config/AGENTS.md BEFORE ANYTHING AGENTS.md这个文件本身就是一个强大的指令。当你或你的队友在任何AI工具中打开这个项目时这个位于根目录的AGENTS.md文件会被优先读取。里面的内容直接告诉AI“在做任何事之前先去阅读~/ai-config/AGENTS.md这个全局规则文件。” 这相当于在所有项目间建立了一个轻量级、动态的链接确保它们都指向最新的、统一的规则源。团队协作工作流中央仓库团队维护一个内部的ai-config仓库分支。个人克隆每个成员克隆该仓库到本地如~/team-ai-config。更新与同步当团队决定新增或修改一条规则基于新的“伤疤”时在中央仓库的AGENTS.md中修改提交PR经过Review后合并。个人拉取与构建成员定期git pull更新本地仓库并运行./build.sh。配置更新根据上述指南更新各自的Claude Code、Cursor等工具的配置。指针文件在共享的项目中使用“指针文件”模式确保所有成员和CI环境都引用同一套最新规则。这套流程将AI辅助开发的规范纳入了标准的工程管理流程使其成为团队知识资产的一部分。5. 自定义与扩展打造你自己的智能体规则库ai-config开箱即用但其真正威力在于你可以根据自己团队的技术栈、文化和痛点进行深度定制。5.1 编辑你的 AGENTS.md打开~/ai-config/AGENTS.md你会看到一个初始的框架。你的编辑应遵循其哲学从问题开始不要凭空编造规则。在接下来的开发中留意AI犯的重复性错误或产生的低效模式。精炼表述用最简短的语言描述规则。例如“永远为数据库查询添加超时设置。”、“绝不在日志中记录完整的用户对象仅记录ID。”分类组织使用Markdown二级标题 (##) 来对规则进行分类例如## 安全规则 - 禁止硬编码任何形式的密钥、令牌、密码。 - 所有用户输入在用于数据库查询前必须进行参数化处理或转义。 ## 代码质量规则 - 每个导出的函数/类都必须有对应的单元测试。 - 函数长度不应超过50行如果超过必须考虑拆分。 - 优先使用具名导入import { something }而非默认导入。 ## 项目特定规则针对你的项目 - 本项目使用 axios 作为HTTP客户端禁止使用 fetch 或 request。 - 所有状态管理必须使用Zustand禁止直接使用React Context或Redux。添加本体定义在文件后部可以增加一个“本体”章节定义你的领域概念。## 领域本体针对电商项目 - **实体**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 Codeai-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脚本。分析目标工具的配置格式研究该工具如何接受自定义指令或规则。是JSON配置文件还是一个特定的Markdown文件创建转换逻辑在build.sh脚本中添加一个新的函数例如generate_for_continue_dev()。这个函数负责读取解析后的AGENTS.md内容并将其转换为目标工具所需的格式。添加生成目录和步骤在脚本的目录创建和主生成逻辑中加入对新工具的支持。这需要一些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)。检查2Git配置运行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辅助开发的改进是困难的但可以从以下几个维度定性观察代码审查负担团队在PR中发现的、由AI引入的常见低级错误如安全漏洞、风格不一致是否显著减少上下文切换成本新成员或新项目接入时是否需要反复向AI解释相同的基础规则和项目规范AI建议的采纳率AI生成的代码、测试、提交信息是否更频繁地可以被直接或稍作修改后使用而无需推倒重来团队认知负荷关于“代码该怎么写”的争论是否减少了因为规则已经内化到了AI这个“自动执行器”中。我个人在深度使用类似的配置系统数月后最深刻的体会是它最大的价值不在于防止错误而在于塑造一致性。它让AI从一个才华横溢但性格乖张的实习生变成了一个深刻理解团队文化和项目规范、值得信赖的资深搭档。当你不再需要为括号换行、导入排序、测试遗漏这些琐事而分心时你才能真正专注于解决那些真正复杂、有趣的工程问题。ai-config提供的正是这样一套将团队智慧“编译”进AI工作流的底层基础设施。