AIT：基于Git与符号链接的AI开发配置管理工具

1. 项目概述：一个AI开发者的配置管理中枢

如果你和我一样，日常开发中同时用着Cursor和Claude Code，那你肯定也经历过这种痛苦：每次开新项目，都得把那些用顺手的Rules（规则）、Skills（技能）和MCP（模型上下文协议）配置重新配一遍；换台电脑，又得从头来过。更别提团队协作了，每个人的配置习惯不同，项目里的AI辅助代码风格也五花八门。AIT（AI Dev Config Manager）这个项目，就是来解决这个痛点的。它本质上是一个基于Git和符号链接（symlink）的配置管理中心，让你能把所有AI开发相关的配置像代码一样管理起来，实现跨机器、跨项目的无缝复用。

简单来说，AIT帮你做了三件事：集中管理、一键部署、同步无忧。它把所有散落在各处的.claude/rules/、.cursor/rules/、技能文件、项目模板，都收拢到一个Git仓库里。然后通过一个叫ait的CLI工具，用软链接的方式，“安装”到你的全局目录或具体项目里。这样一来，你只需要维护仓库里的一份配置，所有关联的地方都会自动更新。无论是个人在多台设备间切换，还是团队想要统一编码规范，它都能极大地提升效率。

2. 核心设计思路与架构解析

2.1 为什么选择“Git + Symlink”这个组合拳？

看到AIT的方案，你可能会问，为什么不用单纯的配置文件，或者更复杂的配置服务？这背后有很实际的工程考量。

首先，Git负责版本与同步。AI助手的规则、技能这些配置，本身就是在不断迭代优化的。今天发现一条新规则对代码质量提升明显，明天可能又调整了某个技能的触发条件。用Git管理，每一次修改都有迹可循，可以回滚，也能通过git diff清晰地看到变化。更重要的是，它解决了跨设备同步的核心问题。你只需要把仓库克隆到新电脑，所有配置就都回来了，这是任何本地化方案无法比拟的便利。

其次，Symlink（符号链接）负责分发与生效。这是整个方案最巧妙的地方。如果只是复制文件，那么当仓库里的源文件更新后，所有已“安装”的项目都需要手动重新复制一遍，维护成本爆炸。而软链接只是一个指向源文件的“快捷方式”。当你在仓库里更新了rules/claude/vue-use-eui.md这个文件，所有链接到这个文件的规则（无论是在~/.claude/rules/下的全局链接，还是在具体项目.claude/rules/下的项目链接）都会立即生效，因为它们指向的是同一个物理文件。这实现了“一次修改，处处更新”。

最后，CLI工具负责体验与封装。光有Git和Symlink还不够，因为手动创建、管理一大堆软链接非常容易出错。ait这个命令行工具，就是用Python写的自动化脚本，它封装了“克隆仓库”、“创建链接”、“组合配置”等一系列繁琐操作，让你通过ait use vue-admin这样一句命令，就能完成以往需要手动操作十几步的配置工作。它降低了使用门槛，让这个强大机制变得简单易用。

2.2 Profile机制：模块化配置组合的精髓

AIT里一个非常核心的概念是Profile。你可以把它理解为一个“配置套餐”或者“场景模式”。它解决了另一个常见问题：不同项目需要不同的配置组合。

举个例子，你开发一个Vue 3的后台管理系统，可能需要的配置是：Vue编码规范规则、UI组件库使用规则、Git提交安全规则，外加一个设计增强技能。而当你开发一个Android TV的WebView应用时，需要的则是完全不同的规则：针对老旧Chromium内核的兼容性规则、TV端交互规范等。

如果没有Profile，你每次都需要手动ait add一堆规则，既容易遗漏，也无法快速切换。Profile机制允许你预先定义好这些组合。查看项目提供的profiles/vue-admin.yaml，它的结构非常清晰：

name: vue-admin description: Vue 3 管理后台项目配置 rules: claude: - vue-use-eui # 规则1：强制使用特定UI库 - server-security # 规则2：服务器安全规范 - git-security # 规则3：Git提交规范 cursor: - tv-webview-vue # 规则4：Cursor专用规则 skills: - ui-ux-pro-max # 技能：UI/UX设计增强 templates: - nuxt-admin # 模板：项目基础文档 mcp: - context7 # MCP：文档查询服务

当你执行ait use vue-admin时，CLI工具会做以下几件事：

1. 读取这个Profile文件。
2. 根据rules.claude列表，从仓库的rules/claude/目录找到对应文件，在项目目录下创建.claude/rules/[规则名].md的软链接。
3. 同理，处理rules.cursor、skills等。
4. 对于templates，它不是创建链接，而是将仓库里模板文件的内容（去掉Frontmatter头信息）复制到项目的CLAUDE.md文件中。
5. 对于mcp，它会将MCP配置片段合并到项目的.claude/mcp.json文件里，采用深度合并策略，避免覆盖你已有的其他MCP配置。

这个机制极大地提升了配置的复用性和场景化能力。你可以为前端、后端、移动端、特定框架甚至特定客户，创建不同的Profile，实现真正的开箱即用。

注意：ait use命令在应用新的Profile时，会自动清理当前项目下由旧Profile创建的所有资源链接，然后再创建新链接。这保证了项目配置的纯净，不会留下冗余文件，但同时也意味着你不能同时混用两个Profile的配置。如果需要混合，可以手动使用ait add命令添加额外资源。

3. 详细安装与初始化指南

3.1 环境准备与前置依赖

在开始使用AIT之前，你需要确保系统环境满足要求。AIT的CLI工具是用Python编写的，并且使用了现代Python项目管理工具uv。

1. Python 3.10+：这是运行CLI的基础。你可以在终端输入python3 --version或python --version来检查。如果版本低于3.10，需要先升级。对于macOS用户，推荐使用brew install python@3.11；Linux用户使用系统包管理器（如apt install python3.11）；Windows用户可以从官网下载安装包。

2. uv工具：uv是一个用Rust写的、极快的Python包安装器和项目管理器，类似于pip和poetry的结合体。它是AIT CLI的依赖管理工具。

   • 安装uv：访问 uv的官方安装页面 ，选择对应你操作系统的安装命令。通常一行curl命令就能搞定。
   • 验证安装：安装后，在终端运行uv --version，能看到版本号即表示成功。

3. Git：这是同步配置仓库的必备工具。绝大多数开发者系统都已安装，可通过git --version确认。

3.2 安装AIT CLI工具

AIT项目采用了一种“自托管”的安装方式，你需要先克隆包含CLI源码的仓库，然后使用uv在本地安装这个工具。

# 1. 克隆AIT项目仓库（假设你从GitHub克隆） git clone https://github.com/danweiyuancircle/ait.git cd ait # 2. 进入cli目录并使用uv安装工具 cd cli uv tool install .

执行uv tool install .这条命令时，uv会做以下几件事：

• 读取当前目录（.）下的pyproject.toml文件。
• 创建一个独立的、隔离的虚拟环境（通常在你用户目录下的.local/bin或类似位置）。
• 将ait这个命令行工具安装到你的系统PATH路径下（通常是~/.local/bin）。
• 安装ait命令所需的所有Python依赖包（如typer,rich,pyyaml等）。

安装完成后，请务必关闭当前终端并重新打开一个新的终端窗口。这是为了让系统重新加载PATH环境变量，识别新安装的ait命令。然后运行ait --help，如果看到命令帮助信息，说明安装成功。

实操心得：有时uv安装的工具可能没有自动添加到PATH的前端，导致命令找不到。如果遇到ait: command not found，可以手动将~/.local/bin添加到你的shell配置文件（如~/.bashrc,~/.zshrc）中：export PATH="$HOME/.local/bin:$PATH"，然后执行source ~/.zshrc（根据你的shell调整）使其生效。

3.3 核心工作流：从零开始到项目配置

安装好CLI后，我们来走一遍完整的工作流，这是理解AIT如何运作的最佳方式。

第一步：全局初始化 (ait install)这是你在每台新电脑上首先需要执行的命令。它的作用相当于“搭建舞台”。

ait install

这条命令背后执行了以下操作：

1. 克隆配置仓库：它会将AIT的配置仓库（就是你刚才克隆的，或者它指定的远程仓库）克隆到你的用户主目录下的一个固定位置：~/.ai-dev-template/。这个目录就是所有配置的“中央仓库”。
2. 创建全局软链接：它会遍历中央仓库里的rules/claude/和skills/目录，为每一个规则和技能文件，在你的Claude Code全局配置目录（~/.claude/rules/,~/.claude/skills/）下创建同名的符号链接。这样，你在任何地方使用Claude Code，都能享受到这些全局规则和技能。

执行成功后，你可以去~/.claude/rules/目录下用ls -la命令查看，会发现那些文件都带有->箭头符号，指向~/.ai-dev-template/rules/claude/下的真实文件。

第二步：为具体项目应用配置 (ait use <profile>)“舞台”搭好了，现在可以给具体的“剧目”（项目）配置灯光音响了。进入你的项目目录。

cd /path/to/your-vue-project ait use vue-admin

这个命令是针对当前所在目录生效的。它会：

1. 读取vue-admin这个Profile的定义。
2. 在当前项目根目录下，创建.claude/rules/、.claude/skills/、.cursor/rules/等目录（如果不存在）。
3. 根据Profile内容，在这些目录下创建指向中央仓库的软链接。
4. 将nuxt-admin模板的内容复制到项目根目录的CLAUDE.md文件。
5. 将context7的MCP配置合并到项目目录的.claude/mcp.json文件。

现在，当你在这个项目里打开Cursor或Claude Code，它们就会自动加载这些项目特定的规则和技能，CLAUDE.md文件也会为AI提供项目上下文。

第三步：跨设备同步与恢复 (ait sync)这是体现AIT价值的关键场景。假设你在公司电脑上配置好了项目，回家后用笔记本继续开发。

1. 在新笔记本上，重复第一步：ait install。这会把最新的中央仓库克隆下来，并建立全局链接。
2. 进入你的项目目录（这个目录可能通过Git同步，或者你手动拷贝过来）。
3. 运行：ait sync

ait sync命令会读取当前项目目录下自动生成的配置文件.ai-rules.json（这个文件在ait use时被创建，记录了该项目应用了哪些资源），然后根据这个列表，重新创建所有软链接。因为中央仓库的内容已经通过ait install同步到本地了，所以链接可以立刻正确建立。你的项目配置瞬间恢复，无需任何手动操作。

4. 资源类型详解与自定义扩展

4.1 五大资源类型的作用与区别

AIT管理着五种类型的资源，理解它们的用途和安装方式，有助于你更好地组织和利用它们。

为什么Templates和MCP不用Symlink？这是一个深思熟虑的设计选择。

• Templates (复制)：CLAUDE.md是高度项目化的文档，每个项目都可能需要在其基础上进行增删改。如果使用软链接，所有项目将共享同一份内容，无法个性化修改。复制方式允许每个项目拥有独立的、可定制的项目说明。
• MCP (合并)：一个项目可能同时使用多个MCP服务（如既用context7查文档，又用sqlite连数据库）。.claude/mcp.json是一个配置文件。采用合并（merge）策略，可以将多个Profile中的MCP配置智能地合并到一个文件里，而不是覆盖。这保证了配置的累加性。

4.2 如何创建并贡献你自己的资源

AIT的强大之处在于它是一个可扩展的生态系统。你可以很容易地添加自己总结的规则、技能或模板。

第一步：创建资源文件所有资源文件都需要一个YAML Frontmatter头部，用于被AIT CLI识别和索引。这是一个Claude Rule的示例：

--- name: my-react-ts-rule description: 适用于React + TypeScript项目的代码规范与组件组织约定 type: claude-rule tags: [react, typescript, frontend, best-practices] version: 1.0.0 author: your-name --- ## 编码规范 - 始终使用函数式组件和React Hooks。 - 组件文件使用 `PascalCase` 命名（如 `UserProfile.tsx`）。 - 非组件工具文件使用 `camelCase` 命名。 - 使用 `interface` 而非 `type` 定义组件Props，以便扩展。 ## 组件组织 - 每个组件独占一个目录，目录内包含 `index.tsx`（主组件）、`styles.module.css`（样式）和 `types.ts`（类型定义）。 - 避免在组件内进行直接的数据获取，使用自定义Hook或状态管理库。 ## AI辅助提示 - 当我要求创建新组件时，请按照上述结构生成初始文件。 - 为所有导出的函数和组件添加清晰的JSDoc注释。

对于MCP资源，格式是JSON，并使用特殊的_meta字段：

{ "_meta": { "name": "my-jira-mcp", "description": "连接公司内部Jira系统，查询任务状态", "type": "mcp", "tags": ["jira", "productivity"], "version": "0.1.0", "author": "your-name" }, "mcpServers": { "jira": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-jira", "--baseUrl", "https://your-company.atlassian.net"] } } }

第二步：放入正确的目录根据type，将文件放入对应的仓库目录：

• claude-rule->rules/claude/
• cursor-rule->rules/cursor/
• skill->skills/
• template->templates/
• mcp->mcp/

第三步：创建或更新Profile编辑或新建一个YAML文件在profiles/目录下，将你的新资源加入组合。

# profiles/react-ts.yaml name: react-ts-starter description: React + TypeScript 项目启动配置 rules: claude: - my-react-ts-rule - git-security # 可以复用已有的通用规则 skills: - ui-ux-pro-max

第四步：使用与分享现在你就可以通过ait use react-ts-starter来使用这个配置了。如果你想与团队分享，只需将你的修改推送到Git远程仓库，团队成员ait update后即可使用。

注意事项：在创建规则或技能时，内容的质量至关重要。好的规则应该具体、可操作、无歧义。避免使用“写出高质量的代码”这种模糊描述，而应替换为“函数长度不超过50行”、“使用async/await而非回调地狱”、“错误必须被捕获并日志记录”等具体指令。清晰的规则能让AI生成更符合预期的代码。

5. 高级用法与运维技巧

5.1 CLI命令深度解析与组合使用

aitCLI提供的命令可以灵活组合，应对复杂场景。

• ait status：这是你的诊断利器。它不仅列出全局和当前项目安装了哪些资源，更重要的是能检测断链。如果因为误删了中央仓库的文件，或者手动移动了项目位置导致软链接失效（变成“悬空链接”），这个命令会明确警告你。定期运行一下可以确保配置系统健康。

• ait list --type=claude-rule --tag=vue：过滤查询。当仓库资源越来越多时，这个命令能帮你快速找到特定类型或标签的资源。--type和--tag参数可以组合使用。

• ait show vue-use-eui：预览内容。在决定是否将一个规则加入Profile前，可以用这个命令查看其详细内容，避免加入不适用或冲突的规则。

• ait add与ait remove：精细化管理。Profile适合一键套用标准套餐，但项目总有特殊需求。比如，vue-adminProfile已经很好，但当前项目还需要一个特殊的“图表优化规则”。这时，你可以在应用Profile后，单独执行ait add chart-optimization（假设该规则已存在于仓库）。反之，如果Profile里的某个规则在当前项目不适用，可以用ait remove server-security将其从当前项目移除，而不影响Profile定义和其他项目。

• ait update：获取更新。当团队其他成员向配置仓库添加了新资源或改进了现有规则后，你只需在任意目录运行ait update。它会执行git pull更新中央仓库，并列出变更的文件列表。由于使用的是软链接，这些更新会立即在所有项目中生效，无需任何其他操作。

5.2 团队协作与配置管理策略

将AIT用于团队，能极大统一开发环境与代码规范。

1. 建立团队中央仓库：不要直接使用个人的AIT仓库。应该Fork原项目，或新建一个Git仓库作为团队的“配置中心”。将团队共识的最佳实践、公司内部规范、特定技术栈的规则都沉淀进去。

2. 标准化Profile命名：在团队仓库的profiles/目录下，建立清晰命名的Profile，如team-frontend-basic、project-xxx-backend、legacy-vue2-support。新成员入职或新项目启动，文档里只需要写一句“请运行ait use team-frontend-basic”。

3. 版本化与发布流程：将配置仓库像代码库一样管理。重大的规则变更（如引入新的代码检查规则）可以创建一个Pull Request，经过团队成员评审后再合并。甚至可以打上Git Tag，对应不同的“版本”，方便追溯和回滚。

4. 处理个人定制与团队统一：矛盾点在于，团队需要统一，个人可能有特殊习惯。AIT的架构很好地解决了这点：

   • 团队统一层：通过团队仓库和标准Profile保证基线一致。
   • 个人定制层：开发者可以在自己的本地仓库副本中（~/.ai-dev-template/），在特定目录下添加个人私有规则，这些规则不会被推送到团队仓库。然后在自己的项目里，通过ait add来单独应用。这样既不影响团队，又满足了个性化需求。

5.3 故障排查与常见问题

即使设计得再完善，实际使用中也可能遇到问题。下面是一些常见情况的排查思路。

问题一：执行ait use后，Claude/Cursor没有反应，似乎规则没生效。

• 检查1：确认安装位置。运行ait status，查看当前项目的资源链接是否创建成功。确认链接指向的源文件路径是否正确。
• 检查2：工具配置目录。确认Claude Code或Cursor的配置目录是否正确指向了当前项目。Claude Code通常自动识别项目根目录下的.claude文件夹。对于Cursor，确保在设置中启用了“项目级规则”。
• 检查3：规则文件格式。对于Claude Rule，确保是.md文件；对于Cursor Rule，确保是.mdc文件。内容格式是否符合各自工具的要求？可以先用一个最简单的规则文件测试。
• 检查4：重启AI工具。有时AI工具需要重启或重新加载项目才能识别新的规则文件。

问题二：ait sync失败，提示链接已存在或文件冲突。

• 原因：这通常是因为项目目录下已经存在同名文件或目录（不是软链接），与AIT试图创建的链接冲突。
• 解决：最安全的方法是先备份你本地的文件，然后运行ait sync --force（如果CLI提供此参数）或手动清理冲突的文件/目录。更好的习惯是，在初始化新项目时，第一时间运行ait use，避免先手动创建了claude等目录。

问题三：更新仓库(ait update)后，某些规则似乎产生了冲突或错误。

• 排查：使用ait show [规则名]查看更新后的规则内容。很可能是因为规则本身的逻辑修改引入了问题，而不是AIT机制的问题。
• 回滚：AIT基于Git，你可以直接进入中央仓库目录~/.ai-dev-template/，使用Git命令回退到上一个版本：git checkout HEAD~1 -- path/to/problematic-rule.md。然后重新评估该规则的修改。

问题四：软链接在Windows系统上不工作。

• 背景：Windows对符号链接的支持与Unix系统不同，可能需要特殊权限或方式。
• 解决方案A（推荐）：使用WSL2（Windows Subsystem for Linux）。在WSL2的Linux环境中，软链接工作完全正常。将你的项目放在WSL的文件系统内，在此环境中使用AIT。
• 解决方案B：如果必须在原生Windows环境下，需要确保以管理员身份运行终端，并且Git for Windows配置了支持符号链接（git config --global core.symlinks true）。但这种方式可能仍有兼容性问题，WSL2是更稳定可靠的选择。

6. 项目生态与最佳实践建议

6.1 探索内置资源与学习资料

AIT项目本身已经提供了一些非常有价值的启动资源，值得你深入研究：

• rules/claude/server-security.md与git-security.md：这些是通用性极高的规则，无论你做什么项目，服务器安全意识和Git提交规范都是必需的。学习这些规则的内容，不仅能直接使用，更能启发你为自己的技术栈编写类似的安全与规范类规则。
• docs/ai-engineering-compound-growth.md：这份文档是项目的“灵魂”。它探讨的“AI工程化”、“上下文工程”、“Subagent架构”和“经验沉淀”理念，正是AIT工具设计的指导思想。阅读它能帮助你超越工具使用层面，理解如何系统性地利用AI提升研发效能。
• scripts/vue-build-deploy.py：这是一个非常务实的自动化脚本示例。它展示了如何将AI辅助开发与传统的CI/CD流程结合。你可以借鉴其思路，编写适合自己项目的构建、测试、部署脚本，并将其也纳入AIT的scripts/目录进行管理，实现开发-配置-部署经验的统一沉淀。

6.2 设计高质量Rules与Skills的心得

经过一段时间的实践，我总结出几条编写有效AI配置的准则：

1. 单一职责，具体明确：一条规则最好只约束一件事。比如“函数长度”一条规则，“错误处理”另一条规则。避免写一个叫best-practices.md的庞然大物，里面混杂了命名、格式、安全、性能等所有内容。AI在处理具体、单一的指令时表现更好。

2. 正向引导，举例说明：与其说“不要写嵌套很深的回调”，不如说“请使用async/await语法来处理异步操作，以下是一个示例：”。提供正面例子比单纯禁止更有效。

3. 利用优先级和条件：Claude Code的规则支持定义优先级(priority)和条件(conditions)。你可以让某些关键规则（如安全规则）拥有更高优先级。也可以设置规则只在特定文件类型（when: { language: “python” }）或路径（when: { path: “src/utils/” }）下生效，实现更精细的控制。

4. Skill是“能力扩展”：Rule是“约束和规范”，而Skill更像是给AI安装的“插件”或“知识包”。一个好的Skill应该聚焦于一个特定领域，提供该领域的结构化知识、推理框架或检查清单。例如ui-ux-pro-max这个Skill，它可能内置了色彩对比度检查、布局栅格系统、交互设计原则等大量UI/UX知识，让AI能在编码的同时兼任初级设计评审。

6.3 将AIT融入现有开发流程

要让AIT发挥最大价值，需要让它成为你工作流中自然的一环。

• 新项目初始化清单：在你的项目创建脚本或文档中，将ait use [profile-name]作为必选步骤。这能确保每个新项目从一开始就具备一致的AI辅助环境。
• 与IDE/编辑器集成：虽然AIT是命令行工具，但你可以利用现代IDE的“任务”或“启动配置”功能，为其创建快捷方式。例如，在VSCode的.vscode/tasks.json中定义一个任务，一键为当前项目应用某个Profile。
• 代码评审与知识传承：在团队代码评审中，除了看代码本身，也可以评审用于生成这些代码的Rule和Skill。如果发现某段代码总出现类似问题，思考一下是否可以通过新增或修改一条Rule来从根本上引导AI避免它？这相当于将代码审查的经验，固化到了AI的“编程习惯”中，实现了知识的自动化传承。
• 定期回顾与优化：每个季度，可以团队一起回顾一下常用的Profile和Rule。哪些规则已经过时？哪些新出现的最佳实践需要补充？AIT仓库的更新日志，就是团队工程能力演进的一个缩影。

AIT不是一个一劳永逸的工具，而是一个需要你和团队共同维护、持续演进的“活”的系统。它管理的不是冰冷的配置，而是你们在AI辅助编程过程中积累的所有经验、智慧和最佳实践。随着这些“集体智慧”的不断沉淀和复用，你会发现整个团队的开发效率与代码质量，都能获得复利式的增长。