AlignTrue:统一管理AI编程助手规则,告别配置碎片化
1. 项目概述:告别AI代理规则管理的混乱时代
如果你和我一样,同时在使用Cursor、GitHub Copilot、Claude Code,甚至还在尝试Windsurf或Aider,那你一定体会过那种“规则管理地狱”。每个AI编程助手都有自己的一套配置文件格式:Cursor用 .mdc ,Copilot和Claude认 AGENTS.md ,Aider有自己的 .aider.conf.yml ,VS Code的MCP代理又是另一套。更别提那些项目级的、团队级的规则,每次更新都得手动复制粘贴到五六个地方,稍不留神就出现版本漂移——这个项目用的规则A,那个项目用的规则B,团队协作时更是灾难。
这就是AlignTrue要解决的问题。它不是一个全新的规则语言,而是一个 同步中枢 。它的核心哲学很简单: 一处编写,处处同步 。你把所有给AI的指令、规范、项目上下文,都用Markdown写在 .aligntrue/rules/ 目录下,然后运行一条 aligntrue sync 命令,它就会自动探测你项目里安装了哪些AI代理,并把规则转换成它们各自的“母语”格式,精准分发。
想象一下,你定义了一条“本项目使用TypeScript,禁止使用 any 类型”的规则。过去,你需要在Cursor的 .mdc 里写一遍,在项目的 AGENTS.md 里再写一遍,如果团队有新成员用Claude Code,你还得提醒他手动加。现在,你只需要在 .aligntrue/rules/coding-standards.md 里写一次。AlignTrue会确保这条规则同时出现在Cursor的配置、项目的 AGENTS.md 、以及任何它探测到的、支持该格式的代理配置中。无论是个人开发者维护多个项目的一致性,还是团队确保编码规范的统一,它都从根本上解决了规则碎片化的问题。
2. 核心设计思路:为什么“同步”比“翻译”更重要
AlignTrue的设计目标非常明确: 做减法,而不是加法 。市面上有些工具试图创造一种“超级AI规则语言”来统一所有代理,但这带来了新的学习成本和适配问题。AlignTrue走了另一条路:尊重现状,充当“适配器”和“同步器”。
2.1 以Markdown为源头的设计考量
选择Markdown作为源格式,是一个深思熟虑的、降低门槛的决策。几乎所有开发者都熟悉Markdown,它足够表达结构化的指令(通过标题、列表、代码块),又保持了人类可读性。更重要的是,AI代理本身就能很好地理解Markdown。这意味着,你在 .aligntrue/rules/ 下写的文件,不仅AlignTrue能处理,你直接打开阅读、甚至直接复制给ChatGPT,它都能理解。这避免了“锁死”在一个专有工具里的风险。
从技术实现看,AlignTrue的解析器并不是简单地把Markdown原文复制出去。它会解析文档结构,识别出哪些部分是指令(Instruction)、哪些是上下文(Context)、哪些是示例(Examples)。然后,针对不同的目标代理,它会进行 格式适配 。例如,对于Cursor,它知道要把指令块包装在特定的 .mdc 标签里;对于 AGENTS.md ,它会遵循其约定的章节结构(如 ## Instructions , ## Context )。这种设计保证了输出的文件是每个代理“期望看到”的格式,确保了兼容性。
2.2 单向同步与“只读出口”的哲学
AlignTrue强制实行 单向同步 :你只能在源目录( .aligntrue/rules/ )编辑,同步后生成的各个代理配置文件(如 .cursor/mdc , AGENTS.md )被视为“只读出口”。这是一个关键的安全和简化设计。
为什么这么做?假设允许双向同步,如果有人在 AGENTS.md 里直接修改了一条规则,而另一个人在源文件里也做了修改,就会立刻产生冲突。解决这种冲突需要复杂的合并逻辑,大大增加了工具的复杂性和使用成本。单向同步明确了权责: .aligntrue/rules/ 是唯一的真相源。这带来了几个好处:
- 版本控制清晰 :你只需要对
.aligntrue/目录进行Git管理。所有代理配置文件的变更历史都体现在源文件的变更中,历史记录干净明了。 - 避免意外覆盖 :你不用担心AI代理自己修改了它的配置文件(有些代理确实会),导致你的修改被覆盖。因为下次同步时,AlignTrue会用源文件的内容重新生成它们。
- 简化心智模型 :开发者只需要记住一个规则:改源文件,然后同步。
为了贯彻这一点,AlignTrue在初始化或同步时,会在生成的代理配置文件旁创建一个 .alignignore 文件(类似于 .gitignore ),里面包含这些生成文件的模式,防止它们被意外提交(如果你使用其Git集成功能)。同时,在团队模式下,它使用锁文件( .aligntrue/lock.json )来精确记录当前生效的源文件版本哈希,确保在任何机器上、任何时间点, aligntrue sync 产生的结果都是完全一致的,这是实现可靠CI/CD验证的基础。
2.3 可扩展的导出器(Exporter)架构
支持众多代理的背后,是一个插件化的导出器系统。每个导出器都是一个独立的模块,负责三件事:
- 探测(Detection) :检查当前项目环境是否存在该代理(例如,检查是否存在
.cursor目录或AGENTS.md文件)。 - 转换(Transformation) :将通用的、从Markdown解析出的中间表示(AST或特定数据结构),转换成该代理的原生配置格式。
- 写入(Writing) :将转换后的内容写入到正确的位置,并处理好相关的备份和原子化操作。
这种架构使得社区贡献新的代理支持变得相对容易。开发者不需要理解AlignTrue的全部内部逻辑,只需要实现一个符合接口的导出器,告诉它“如何将规则X转换成目标格式Y”。项目目前的“广度优先”策略——优先覆盖Cursor、Copilot、Claude等主流代理——正是通过不断集成这些导出器实现的。
3. 从零到一的完整实操指南
理论说再多,不如动手试一遍。下面我以一个新项目为例,带你完整走一遍从安装到编写复杂规则的流程,并分享一些我踩过坑才总结出来的经验。
3.1 环境准备与一分钟初始化
首先,确保你的环境有Node.js 20或更高版本。然后全局安装AlignTrue:
npm install -g aligntrue
安装后,进入你的项目根目录(或者一个新文件夹)。运行初始化命令:
cd my-awesome-project
aligntrue init
这里会发生什么? init 命令是一个“智能引导”过程:
- 代理探测 :它会静默扫描你的项目目录,寻找已知AI代理的痕迹。比如,它会看有没有
.cursor文件夹(Cursor代理)、AGENTS.md文件(Copilot/Claude)、.aider.conf.yml(Aider)等等。 - 规则导入 :如果发现了任何现有的规则文件,它会主动询问你是否要将这些规则导入到AlignTrue的中心仓库。例如,如果你有一个现成的
AGENTS.md,它会解析其中的内容,转换成Markdown文件,存放到.aligntrue/rules/下。 这是一个非常贴心的功能,意味着迁移成本几乎为零。 - 目录结构创建 :如果什么都没找到,它会创建基础的
.aligntrue/rules/目录结构,并可能根据探测到的代理,生成一个最基础的规则模板文件。
实操心得 :第一次运行
init时,我建议在一个全新的或规则较简单的项目里进行。如果你有一个庞大且复杂的AGENTS.md,先备份。虽然导入功能通常很可靠,但在复杂规则(比如嵌套代码块、特殊注释)的解析上,可能会有边缘情况。用--dry-run先预览总是一个好习惯:aligntrue init --dry-run。
初始化完成后,你的项目目录会多出一个 .aligntrue 文件夹,结构大致如下:
.my-awesome-project/
├── .aligntrue/
│ ├── rules/ # 你的规则源文件都在这里
│ │ └── (可能有一些自动生成的示例文件)
│ └── aligntrue.json # 项目配置文件
└── (你的其他项目文件)
3.2 编写你的第一条规则:从简单到复杂
现在,进入核心环节:编写规则。所有规则都放在 .aligntrue/rules/ 下,支持子目录,方便分类管理。
示例1:基础项目上下文 在 .aligntrue/rules/project-context.md 中写入:
# Project Overview: My Awesome API
This is a Node.js + TypeScript REST API built with Express.js and Prisma.
## Tech Stack
- **Runtime:** Node.js 20
- **Language:** TypeScript (strict mode enabled)
- **Framework:** Express.js
- **ORM:** Prisma
- **Database:** PostgreSQL
- **Testing:** Jest & Supertest
## Key Conventions
- Use `async/await` over callbacks.
- All API responses must follow the `{ data: T, error: string | null }` wrapper format.
- Environment variables are loaded via `dotenv` and validated using Zod.
这定义了一些基本的项目背景和技术栈,任何AI代理都需要知道这些。
示例2:具体的编码指令 创建 .aligntrue/rules/coding-standards.md :
# TypeScript Coding Standards
## Strict Rules
- Never use the `any` type. Use `unknown` or proper generics.
- Enable all strict flags in `tsconfig.json`.
- Use `interface` for object shapes that can be extended, `type` for unions/tuples.
## Error Handling
- Use typed error classes extending `Error`.
- Always use try-catch for async operations that may fail.
- Log errors with structured logging (Pino), including `requestId`.
## Example: Proper API Handler
```typescript
import { Request, Response } from 'express';
import { z } from 'zod';
const CreateUserSchema = z.object({
email: z.string().email(),
name: z.string().min(1),
});
export const createUserHandler = async (req: Request, res: Response) => {
try {
const validatedData = CreateUserSchema.parse(req.body);
// ... business logic
res.status(201).json({ data: newUser, error: null });
} catch (error) {
if (error instanceof z.ZodError) {
res.status(400).json({ data: null, error: error.errors[0].message });
} else {
// Log the unexpected error
req.log.error({ error }, 'Failed to create user');
res.status(500).json({ data: null, error: 'Internal server error' });
}
}
};
```
这条规则更具体,包含了禁止项、最佳实践和一个完整的代码示例。AI代理在为你编写或补全类似 createUserHandler 的代码时,就会参考这个模式和规范。
3.3 执行同步与验证效果
规则写好后,运行同步命令:
aligntrue sync
这个命令会:
- 读取
.aligntrue/rules/下的所有Markdown文件。 - 根据
aligntrue.json的配置和自动探测到的代理,调用相应的导出器。 - 为每个代理生成或更新其原生配置文件。
- (关键安全步骤) 在覆盖任何现有文件前,自动在
.aligntrue/backups/下创建带时间戳的备份。
执行后,你可能会发现项目里多了这些文件(取决于探测到的代理):
.cursor/mdc/目录下生成了对应的.mdc文件。- 项目根目录下生成了
AGENTS.md文件。 - 如果安装了Claude Code,可能还会生成
CLAUDE.md。 - 每个生成的文件旁边可能有一个
.alignignore,里面写着*,表示该目录下的文件是生成的,提醒你不要直接编辑。
如何验证同步成功?
- 肉眼检查 :打开生成的
AGENTS.md或.cursor/mdc/里的文件,看看内容是否是你的规则的正确转换。 - 使用
--dry-run:在运行实际同步前,使用aligntrue sync --dry-run。这会输出一个详细的预览,显示哪些文件将被创建、更新或删除,而不会做任何实际改动。这是 最重要的安全阀 ,每次执行sync前都建议先dry-run一下。 - 使用
check命令 :aligntrue check会验证你的源规则文件语法是否基本正确,以及生成的配置是否有效。这在CI流水线中特别有用。
3.4 高级功能实战:作用域、插槽与覆盖层
当你的项目变得复杂,比如一个Monorepo包含多个子包,或者你需要为不同环境(开发/生产)准备略有不同的规则时,基础功能就不够了。这时需要用到AlignTrue的高级特性。
作用域(Scopes) :为子目录定义特殊规则。 假设你的项目结构是:
my-monorepo/
├── packages/
│ ├── web-app/ # 前端,React + TypeScript
│ └── api-server/ # 后端,Node.js + TypeScript
└── .aligntrue/
你可以在 .aligntrue/rules/ 下创建:
global.md:定义全局规则,如Git提交规范、通用代码风格。scopes/frontend.md:定义React、CSS-in-JS相关的规则。scopes/backend.md:定义Express、数据库、API安全相关的规则。
然后在 .aligntrue/aligntrue.json 中配置作用域:
{
"scopes": {
"packages/web-app": ["scopes/frontend.md"],
"packages/api-server": ["scopes/backend.md"]
}
}
当你运行 aligntrue sync 时,AlignTrue会为 packages/web-app 目录下的代理生成包含 global.md + scopes/frontend.md 规则的配置,而为 packages/api-server 生成 global.md + scopes/backend.md 的配置。这完美解决了Monorepo中不同部分需要不同AI指导的问题。
插槽(Plugs) :实现动态规则。 有时候,规则里需要一些动态值,比如当前用户名、项目名称。你不想把这些硬编码在规则里。插槽就是为此设计的。
在规则文件中,你可以这样写:
# Code Review Guidelines
- Always add tests for new features, @reviewer.
- The project prefix for all environment variables is `{{projectPrefix}}`.
然后在 .aligntrue/aligntrue.json 中定义插槽值:
{
"plugs": {
"reviewer": "alice",
"projectPrefix": "MYAPP"
}
}
同步后, @reviewer 会被替换为“alice”, {{projectPrefix}} 会被替换为“MYAPP”。这使得规则模板化,更容易在多个项目间复用。你甚至可以为不同作用域设置不同的插槽值。
覆盖层(Overlays) :安全地微调第三方规则。 这是团队协作或使用共享规则库时的神器。假设你从公司中央仓库导入了一套基础规则 base-rules.md ,但你的特定项目需要禁用其中一条关于“必须写JSDoc”的规则。
你不应该直接修改 base-rules.md (因为它是共享的,你的修改无法同步上游更新)。相反,你创建一个覆盖层文件 local-overrides.md :
# Override: Disable JSDoc requirement
- Remove the rule about mandatory JSDoc comments.
在配置中指定叠加顺序:
{
"rules": ["base-rules.md"],
"overlays": ["local-overrides.md"]
}
AlignTrue在应用规则时,会先加载基础规则,然后应用覆盖层进行“打补丁”式的修改(移除、替换、添加特定规则)。这实现了“fork”共享规则并自定义的能力,同时保留了未来平滑合并上游更新的可能性。
4. 集成到开发生命周期与团队协作
AlignTrue真正的威力在于它不仅能用于本地开发,更能无缝集成到版本控制和CI/CD流程中,成为团队质量守门员的一部分。
4.1 个人工作流:Git钩子与自动化
对于个人项目,我习惯将 aligntrue sync 加入到我的日常流程中:
- 作为预提交钩子(Pre-commit Hook) :使用Husky或类似的工具,在
git commit前自动运行aligntrue sync,确保提交到仓库的代码所对应的AI规则配置文件总是最新的。这避免了忘记手动同步导致规则不一致。 - 作为NPM脚本 :在
package.json中增加脚本,方便调用。
{
"scripts": {
"prepare": "aligntrue sync", // 在npm install后自动运行
"rules:sync": "aligntrue sync",
"rules:check": "aligntrue check",
"rules:preview": "aligntrue sync --dry-run"
}
}
- IDE集成 :虽然AlignTrue本身是CLI工具,但你可以配置VS Code的Tasks或者JetBrains IDE的File Watchers,在保存
.aligntrue/rules/目录下的Markdown文件时,自动触发aligntrue sync --dry-run在输出面板显示预览,实现近乎实时的反馈。
4.2 团队协作模式:锁文件、漂移检测与CI门禁
对于团队,AlignTrue的“团队模式”是必备功能。通过 aligntrue team enable 启用后,它会创建一个 .aligntrue/lock.json 文件。这个锁文件记录了当前所有源规则文件的精确哈希值。
团队工作流如下:
- 规则工程师 (或任何有权限的人)在
.aligntrue/rules/中修改规则。 - 运行
aligntrue sync,这会更新所有代理的配置文件, 同时也会更新lock.json文件 。 - 将
rules/目录的更改 和lock.json的更改一并提交到Git。 - 其他团队成员拉取代码后,运行
aligntrue sync。工具会读取lock.json,确保基于完全相同的源文件版本生成配置,实现100%的一致性。
漂移检测(Drift Detection) :这是团队模式的杀手级功能。运行 aligntrue drift 可以检查“预期状态”(锁文件记录的)和“实际状态”(当前源文件生成的)之间的差异。如果有人未经流程修改了某个生成的 AGENTS.md 文件,或者本地有未提交的规则修改,这个命令就能检测出来。在CI流水线中集成 aligntrue drift --gates ,可以设置门禁:如果检测到漂移,CI失败,阻止合并。这强制了整个团队对“单一真相源”的遵守。
CI/CD集成示例(GitHub Actions):
name: Validate AI Agent Rules
on: [pull_request, push]
jobs:
validate-rules:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install AlignTrue
run: npm install -g aligntrue
- name: Check rule syntax and integrity
run: aligntrue check --ci
# --ci 标志会以非零退出码失败,适合CI环境
- name: Detect configuration drift
run: aligntrue drift --gates
# --gates 标志会在发现任何漂移时失败
# 这确保了PR中的规则修改必须经过锁文件更新流程
这个工作流确保了:
- 所有合并到主分支的规则变更都是语法正确的。
- 生成的配置文件与锁文件锁定的版本一致,无人能绕过流程直接修改出口文件。
- 团队始终保持规则同步。
4.3 从现有工具迁移
如果你之前在使用类似Ruler这样的工具,AlignTrue提供了迁移路径。运行 aligntrue migrate ruler ,它会尝试自动检测并转换现有的Ruler配置文件。不过根据我的经验,自动迁移可能无法覆盖100%的自定义配置。 最佳实践是 :
- 先在一个分支上运行迁移命令。
- 仔细检查生成的
.aligntrue/rules/下的Markdown文件,确保转换准确。 - 运行
aligntrue sync --dry-run,预览将要生成的代理配置文件。 - 与原来的配置文件进行对比,手动调整任何差异。
- 确认无误后,再实际执行同步并启用团队模式。
5. 避坑指南与常见问题排查
在实际使用中,我遇到了一些典型问题,这里总结出来,希望能帮你节省时间。
5.1 同步未生效或代理未检测到
问题 :运行 aligntrue sync 后,预期的配置文件没有出现或没有更新。 排查步骤 :
- 检查代理探测 :运行
aligntrue sync --verbose。在详细输出中,查看“Detected Agents”部分。确认你期望的代理(如Cursor、Copilot)是否被列出。如果没有,可能是该代理尚未被AlignTrue支持,或者其安装路径非常规。 - 检查配置文件 :查看
.aligntrue/aligntrue.json。确认其中agents部分是否显式禁用(disabled)了某些代理。默认是自动探测所有,但可能被手动关闭了。 - 检查规则文件路径 :确认你的规则
.md文件确实放在.aligntrue/rules/目录或其子目录下,并且没有被.aligntrueignore文件忽略。 - 检查导出器配置 :某些代理支持多种导出格式(如“单文件AGENTS.md”或“多文件原生格式”)。检查配置中对应代理的
format选项是否符合你的预期。
5.2 规则冲突或覆盖不符合预期
问题 :当使用作用域或覆盖层时,某些规则没有按预期应用或发生了冲突。 排查步骤 :
- 理解加载顺序 :AlignTrue按顺序加载规则文件。后面的文件中的规则会覆盖前面文件中同名的或冲突的规则。检查你的
aligntrue.json中rules数组的顺序。 - 检查作用域路径 :作用域的路径是相对于项目根目录的,且匹配规则是“以此路径开头”。确保你配置的作用域路径完全正确,没有多余的斜杠或拼写错误。
- 使用
--dry-run和--verbose:这是最强大的调试工具。aligntrue sync --dry-run --verbose会输出极其详细的信息,包括每个规则文件被加载的顺序、每个代理应用了哪些规则文件、以及最终生成的配置内容。通过仔细阅读这个输出,你可以精确定位规则是在哪一步被覆盖或忽略的。 - 简化测试 :如果问题复杂,尝试创建一个最小化测试用例:只保留一两条核心规则,禁用所有作用域和覆盖层,看是否能正确同步。然后逐步添加复杂度,直到问题复现,从而定位问题根源。
5.3 团队模式下锁文件冲突
问题 :在团队协作中,多人同时修改规则并提交,导致 lock.json 合并冲突。 解决方案与预防 :
- 将
lock.json视为“衍生文件” :像处理package-lock.json一样对待它。解决冲突时,通常的流程是: a. 拉取最新代码,解决rules/目录下源Markdown文件的冲突(这是需要人工理解合并的)。 b. 丢弃lock.json的冲突,直接使用某一方的版本(或直接删除它) 。 c. 在本地运行aligntrue sync。这会基于合并后的、已解决冲突的源文件,重新生成一个正确的、新的lock.json。 d. 提交这个新的lock.json。 - 沟通与流程 :在团队内建立约定,修改规则前先在沟通渠道(如Slack、Issue)中说明,减少同时修改同一文件的概率。可以考虑将
rules/目录的修改权限限制给少数“规则维护者”。 - CI门禁 :确保CI中启用了
aligntrue drift --gates。这样,如果有人提交了未更新lock.json的规则修改,或者提交了一个过时的lock.json,CI会失败,从而在合并前发现问题。
5.4 性能问题与大型规则库
问题 :当规则文件非常多(几十上百个)或非常大时,同步速度变慢。 优化建议 :
- 按需加载 :充分利用 作用域 。不要把所有全局规则都塞进一个文件然后应用到所有子项目。为不同的项目或目录结构配置精确的作用域,减少每次同步需要处理的规则总量。
- 精简规则 :定期回顾你的规则。有些规则可能已经过时,或者AI代理已经内化了这些模式。保持规则简洁、关键。
- 忽略不必要的代理 :如果你确定某个项目永远不会用到某个AI代理(比如某个纯后端项目不用Cursor),可以在
aligntrue.json中明确将其disabled,避免AlignTrue每次都为它生成文件。 - 升级版本 :关注AlignTrue的更新日志,性能优化通常是持续进行的。
5.5 与版本控制系统(Git)的协作
问题 :生成的代理配置文件(如 .cursor/mdc/ 下的文件)是否应该提交到Git? 官方建议是:不提交 。这些是衍生文件,真相源是 .aligntrue/rules/ 。提交它们会导致仓库臃肿,并可能引发不必要的合并冲突。AlignTrue的 init 命令通常会尝试在 .gitignore 中添加对这些生成目录和文件的忽略规则。
但是,有一种情况可能需要提交 :如果你的团队中有成员没有安装或不想安装AlignTrue,但他们仍然需要使用AI代理。这时,你可以选择提交生成的 AGENTS.md 文件,作为对未安装工具成员的兼容。但这会引入“两个真相源”的风险,需要团队严格约定:只从 .aligntrue/rules/ 修改规则,生成的文件仅供读取。更好的做法是鼓励所有成员都使用AlignTrue。
一个折中的Git工作流是:
- 将
.aligntrue/rules/和.aligntrue/aligntrue.json(以及团队模式下的.aligntrue/lock.json)提交到版本控制。 - 在
.gitignore中忽略所有生成的代理配置目录,如.cursor/mdc/、AGENTS.md、CLAUDE.md等。 - 在项目的
README.md中明确说明,开发者需要先运行aligntrue sync来生成这些配置文件。
最后,记住AlignTrue仍处于Alpha阶段。如果你遇到了文档未覆盖的奇怪问题,或者有新的功能需求,去GitHub仓库提交Issue是帮助项目改进的最好方式。开源工具的生命力正来自于社区的反馈和贡献。
更多推荐



所有评论(0)