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/ 是唯一的真相源。这带来了几个好处:

  1. 版本控制清晰 :你只需要对 .aligntrue/ 目录进行Git管理。所有代理配置文件的变更历史都体现在源文件的变更中,历史记录干净明了。
  2. 避免意外覆盖 :你不用担心AI代理自己修改了它的配置文件(有些代理确实会),导致你的修改被覆盖。因为下次同步时,AlignTrue会用源文件的内容重新生成它们。
  3. 简化心智模型 :开发者只需要记住一个规则:改源文件,然后同步。

为了贯彻这一点,AlignTrue在初始化或同步时,会在生成的代理配置文件旁创建一个 .alignignore 文件(类似于 .gitignore ),里面包含这些生成文件的模式,防止它们被意外提交(如果你使用其Git集成功能)。同时,在团队模式下,它使用锁文件( .aligntrue/lock.json )来精确记录当前生效的源文件版本哈希,确保在任何机器上、任何时间点, aligntrue sync 产生的结果都是完全一致的,这是实现可靠CI/CD验证的基础。

2.3 可扩展的导出器(Exporter)架构

支持众多代理的背后,是一个插件化的导出器系统。每个导出器都是一个独立的模块,负责三件事:

  1. 探测(Detection) :检查当前项目环境是否存在该代理(例如,检查是否存在 .cursor 目录或 AGENTS.md 文件)。
  2. 转换(Transformation) :将通用的、从Markdown解析出的中间表示(AST或特定数据结构),转换成该代理的原生配置格式。
  3. 写入(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 命令是一个“智能引导”过程:

  1. 代理探测 :它会静默扫描你的项目目录,寻找已知AI代理的痕迹。比如,它会看有没有 .cursor 文件夹(Cursor代理)、 AGENTS.md 文件(Copilot/Claude)、 .aider.conf.yml (Aider)等等。
  2. 规则导入 :如果发现了任何现有的规则文件,它会主动询问你是否要将这些规则导入到AlignTrue的中心仓库。例如,如果你有一个现成的 AGENTS.md ,它会解析其中的内容,转换成Markdown文件,存放到 .aligntrue/rules/ 下。 这是一个非常贴心的功能,意味着迁移成本几乎为零。
  3. 目录结构创建 :如果什么都没找到,它会创建基础的 .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

这个命令会:

  1. 读取 .aligntrue/rules/ 下的所有Markdown文件。
  2. 根据 aligntrue.json 的配置和自动探测到的代理,调用相应的导出器。
  3. 为每个代理生成或更新其原生配置文件。
  4. (关键安全步骤) 在覆盖任何现有文件前,自动在 .aligntrue/backups/ 下创建带时间戳的备份。

执行后,你可能会发现项目里多了这些文件(取决于探测到的代理):

  • .cursor/mdc/ 目录下生成了对应的 .mdc 文件。
  • 项目根目录下生成了 AGENTS.md 文件。
  • 如果安装了Claude Code,可能还会生成 CLAUDE.md
  • 每个生成的文件旁边可能有一个 .alignignore ,里面写着 * ,表示该目录下的文件是生成的,提醒你不要直接编辑。

如何验证同步成功?

  1. 肉眼检查 :打开生成的 AGENTS.md .cursor/mdc/ 里的文件,看看内容是否是你的规则的正确转换。
  2. 使用 --dry-run :在运行实际同步前,使用 aligntrue sync --dry-run 。这会输出一个详细的预览,显示哪些文件将被创建、更新或删除,而不会做任何实际改动。这是 最重要的安全阀 ,每次执行 sync 前都建议先 dry-run 一下。
  3. 使用 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 加入到我的日常流程中:

  1. 作为预提交钩子(Pre-commit Hook) :使用Husky或类似的工具,在 git commit 前自动运行 aligntrue sync ,确保提交到仓库的代码所对应的AI规则配置文件总是最新的。这避免了忘记手动同步导致规则不一致。
  2. 作为NPM脚本 :在 package.json 中增加脚本,方便调用。
{
  "scripts": {
    "prepare": "aligntrue sync", // 在npm install后自动运行
    "rules:sync": "aligntrue sync",
    "rules:check": "aligntrue check",
    "rules:preview": "aligntrue sync --dry-run"
  }
}
  1. 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 文件。这个锁文件记录了当前所有源规则文件的精确哈希值。

团队工作流如下:

  1. 规则工程师 (或任何有权限的人)在 .aligntrue/rules/ 中修改规则。
  2. 运行 aligntrue sync ,这会更新所有代理的配置文件, 同时也会更新 lock.json 文件
  3. rules/ 目录的更改 lock.json 的更改一并提交到Git。
  4. 其他团队成员拉取代码后,运行 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%的自定义配置。 最佳实践是

  1. 先在一个分支上运行迁移命令。
  2. 仔细检查生成的 .aligntrue/rules/ 下的Markdown文件,确保转换准确。
  3. 运行 aligntrue sync --dry-run ,预览将要生成的代理配置文件。
  4. 与原来的配置文件进行对比,手动调整任何差异。
  5. 确认无误后,再实际执行同步并启用团队模式。

5. 避坑指南与常见问题排查

在实际使用中,我遇到了一些典型问题,这里总结出来,希望能帮你节省时间。

5.1 同步未生效或代理未检测到

问题 :运行 aligntrue sync 后,预期的配置文件没有出现或没有更新。 排查步骤

  1. 检查代理探测 :运行 aligntrue sync --verbose 。在详细输出中,查看“Detected Agents”部分。确认你期望的代理(如Cursor、Copilot)是否被列出。如果没有,可能是该代理尚未被AlignTrue支持,或者其安装路径非常规。
  2. 检查配置文件 :查看 .aligntrue/aligntrue.json 。确认其中 agents 部分是否显式禁用( disabled )了某些代理。默认是自动探测所有,但可能被手动关闭了。
  3. 检查规则文件路径 :确认你的规则 .md 文件确实放在 .aligntrue/rules/ 目录或其子目录下,并且没有被 .aligntrueignore 文件忽略。
  4. 检查导出器配置 :某些代理支持多种导出格式(如“单文件AGENTS.md”或“多文件原生格式”)。检查配置中对应代理的 format 选项是否符合你的预期。

5.2 规则冲突或覆盖不符合预期

问题 :当使用作用域或覆盖层时,某些规则没有按预期应用或发生了冲突。 排查步骤

  1. 理解加载顺序 :AlignTrue按顺序加载规则文件。后面的文件中的规则会覆盖前面文件中同名的或冲突的规则。检查你的 aligntrue.json rules 数组的顺序。
  2. 检查作用域路径 :作用域的路径是相对于项目根目录的,且匹配规则是“以此路径开头”。确保你配置的作用域路径完全正确,没有多余的斜杠或拼写错误。
  3. 使用 --dry-run --verbose :这是最强大的调试工具。 aligntrue sync --dry-run --verbose 会输出极其详细的信息,包括每个规则文件被加载的顺序、每个代理应用了哪些规则文件、以及最终生成的配置内容。通过仔细阅读这个输出,你可以精确定位规则是在哪一步被覆盖或忽略的。
  4. 简化测试 :如果问题复杂,尝试创建一个最小化测试用例:只保留一两条核心规则,禁用所有作用域和覆盖层,看是否能正确同步。然后逐步添加复杂度,直到问题复现,从而定位问题根源。

5.3 团队模式下锁文件冲突

问题 :在团队协作中,多人同时修改规则并提交,导致 lock.json 合并冲突。 解决方案与预防

  1. lock.json 视为“衍生文件” :像处理 package-lock.json 一样对待它。解决冲突时,通常的流程是: a. 拉取最新代码,解决 rules/ 目录下源Markdown文件的冲突(这是需要人工理解合并的)。 b. 丢弃 lock.json 的冲突,直接使用某一方的版本(或直接删除它) 。 c. 在本地运行 aligntrue sync 。这会基于合并后的、已解决冲突的源文件,重新生成一个正确的、新的 lock.json 。 d. 提交这个新的 lock.json
  2. 沟通与流程 :在团队内建立约定,修改规则前先在沟通渠道(如Slack、Issue)中说明,减少同时修改同一文件的概率。可以考虑将 rules/ 目录的修改权限限制给少数“规则维护者”。
  3. CI门禁 :确保CI中启用了 aligntrue drift --gates 。这样,如果有人提交了未更新 lock.json 的规则修改,或者提交了一个过时的 lock.json ,CI会失败,从而在合并前发现问题。

5.4 性能问题与大型规则库

问题 :当规则文件非常多(几十上百个)或非常大时,同步速度变慢。 优化建议

  1. 按需加载 :充分利用 作用域 。不要把所有全局规则都塞进一个文件然后应用到所有子项目。为不同的项目或目录结构配置精确的作用域,减少每次同步需要处理的规则总量。
  2. 精简规则 :定期回顾你的规则。有些规则可能已经过时,或者AI代理已经内化了这些模式。保持规则简洁、关键。
  3. 忽略不必要的代理 :如果你确定某个项目永远不会用到某个AI代理(比如某个纯后端项目不用Cursor),可以在 aligntrue.json 中明确将其 disabled ,避免AlignTrue每次都为它生成文件。
  4. 升级版本 :关注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是帮助项目改进的最好方式。开源工具的生命力正来自于社区的反馈和贡献。

更多推荐