• 如遇问题，请通过 Issues 提交报告，或使用 rulebook-ai 命令 rulebook-ai bug-report。
• 如需实时聊天、社区支持或分享您的想法，请加入我们的 Discord：Join our Discord。
• 想提供具体反馈或预约个人演示？请在我的日历上预约聊天：Book a Chat on my Calendar。

Rulebook-AI：AI 环境管理器

rulebook-ai 是一款命令行工具，用于打包并部署一致且专业的环境——包括规则、上下文和工具——到您最喜爱的 AI 编程助手。

不要再浪费时间重复解释项目的架构，也不必在不同 AI 之间手动复制粘贴指令。使用 rulebook-ai，您可以一次性定义 AI 的运行环境，并将其部署到任何地方。

问题：AI 助手过于通用且彼此孤立

AI 编程助手功能强大，但它们往往处于“信息孤岛”状态：

1. 容易遗忘： 它们无法长期记忆您项目的特定架构、所用库或目标。
2. 不一致： 您给 Cursor 的指令可能无法在 Gemini 上生效，而 Copilot 的上下文又是独立的。
3. 不够专业： AI 的通用知识不足以胜任专家级任务。一个优秀的“React 开发者”AI 需要的规则、上下文和工具，与一个优秀的“DevOps 工程师”AI 截然不同。

解决方案：可移植且可组合的 AI 环境

rulebook-ai 通过将 AI 的完整运行环境视为可移植的环境来解决这一问题，您可以像管理代码一样对其进行管理。一个环境由三部分组成：

• 规则： AI 的操作指令和工作流程。
• 上下文： 持久的知识库（即您项目的“记忆”）。
• 工具： AI 可用于执行任务的辅助脚本。

这些环境被打包成可版本控制、可共享的包。

为什么 rulebook-ai 是答案

核心价值	rulebook-ai 的实现方式
跨助手的可移植性	在一个通用的包中定义一次环境。使用 project sync 命令，即可自动将其转换并部署到任何支持的 AI（Cursor、Gemini、Copilot 等）。这样您就可以根据任务选择最适合的 AI，同时保持上下文一致性。
针对任何任务的深度专业化	创建或使用针对特定角色（如产品经理、DevOps 工程师）或技术领域（如 React、AWS、数据科学）的包。让您的 AI 立即具备完成当前任务所需的专家知识和工具。
可组合且可版本化的上下文	将 AI 的环境视作代码。混合搭配不同的包，构建适合任何项目的完美配置。利用配置文件（命名的包组），可以快速切换整个配置。
社区驱动的专业知识	无需从头开始。rulebook-ai 是一个供专家社区构建和共享包的平台，从而创建一个面向 AI 辅助开发的最佳实践公共库。
整洁且可预测的工作空间	该工具会清晰地分离用户拥有的内容（memory/、tools/）与框架管理的产物（.rulebook-ai/、生成的规则），使您的项目保持整洁且行为可预测。
完全掌控源代码	不局限于公共索引。您可以直接从任何 GitHub 仓库添加包（github:），也可以从本地文件系统开发和测试包（local:）。这为您提供了安全的私有包路径，以及无缝的新包创建工作流。

快速入门：使用 uvx

# 1. 如果尚未安装 uv，请先安装
curl -fsSL https://astral.sh/uv/install.sh | bash

# 2. 向项目中添加一个包（例如 light-spec 入门包）
uvx rulebook-ai packs add light-spec

# 3. 将环境同步到您的工作区
uvx rulebook-ai project sync

这将会创建一个 .rulebook-ai 目录来管理状态，并填充 memory/ 和 tools/ 中的初始内容。同时还会生成针对不同助手的规则文件（例如 .cursor/rules/、GEMINI.md）。

如需更详细的全功能教程，请参阅 逐步教程。

支持的 AI 助手

rulebook-ai 支持为多种 AI 编程助手生成规则文件。目前支持的助手包括：Cursor、Windsurf、Cline、RooCode、Kilo Code、Warp、GitHub Copilot、Claude Code、Codex CLI 和 Gemini CLI。

有关各助手的具体行为、文件位置及格式说明，请参阅：memory/docs/user_guide/supported_assistants.md。

您可以通过 --assistant 标志为一个或多个助手生成规则，例如：

rulebook-ai project sync --assistant cursor copilot

或者为所有支持的助手生成规则：

rulebook-ai project sync --all

工作原理：包系统

rulebook-ai 的核心是一个简单而强大的工作流程：

1. 添加包： 您可以将一个或多个包添加到项目的库中。这些包可以是内置的、来自社区的，也可以是您本地目录中的自定义包。
2. 同步项目： 运行 rulebook-ai project sync。工具会读取您选择的包，复制其中的初始 memory/ 和 tools/ 内容，并以正确的格式为每个使用的 AI 生成最终的规则文件。

此工作流程确保您的项目“AI 环境”明确、可版本化且易于管理。

您的第一个环境：内置包

rulebook-ai 自带几个包，让您立即上手。light-spec 包是任何新项目的推荐起点。

• light-spec：

  • 优点： 安装了一个基础的软件开发生命周期环境。它教会您的 AI 像初级开发者一样思考，遵循规划、编码和调试的系统化流程。此外，还为您的项目文档提供了初始模板（memory/）。
  • 适用人群： 适合所有人。它是任何项目理想的首个包。

• medium-spec 和 heavy-spec：

  • 优点： 这些包提供了更详尽的规则和更严格的约束，非常适合需要 AI 更加谨慎和细致的情况，例如复杂的代码审查或重构。
  • 适用人群： 适合希望 AI 助手提供更多明确指导和检查的开发者。

同步后的项目结构

flowchart TD
    A[您的项目] --> D[... 您的其他文件];

    A --> E[memory/];
    A --> F[tools/];

    A --> I[/.rulebook-ai/];
    A --> J[/.cursor/];
    A --> K[... 其他生成的规则];


    subgraph "版本控制 (git)"
        direction LR
        subgraph "需要提交的（您的环境）"
            E & F
        end
        subgraph "需要忽略的（生成的工件）"
            I & J & K
        end
    end

    style E fill:#cde4f9,stroke:#8ab4e2
    style F fill:#cde4f9,stroke:#8ab4e2

    style I fill:#f9d4c3,stroke:#e2a48a
    style J fill:#f9d4c3,stroke:#e2a48a
    style K fill:#f9d4c3,stroke:#e2a48a

• 您的环境 (memory/、tools/)： 这是您项目的独特上下文。您拥有它，可以编辑它，并将其提交到版本控制系统中。
• 生成的工件（.rulebook-ai/、.cursor/ 等）： 这些由 CLI 管理。它们应被添加到 .gitignore 文件中，因为可以在任何时候重新生成。

贡献

如有任何问题或关于贡献的想法，请加入我们的 Discord https://discord.gg/aNmQB7JWPe。
本项目依靠社区贡献而蓬勃发展。您可以从以下方面做出贡献：

• 创建并分享包： 拥有一套针对特定框架或角色的优秀规则和工具吗？将其打包并分享吧！请参阅 包开发者指南。
• 报告错误或提出建议： 在仓库中打开一个 Issue。使用 rulebook-ai bug-report 命令即可快速进入该页面。
• 参与仓库贡献： 请访问 CONTRIBUTING.md。

rulebook-ai 快速上手指南

rulebook-ai 是一个命令行工具，用于将一致的 AI 开发环境（规则、上下文和工具）打包并部署到你喜欢的 AI 编程助手（如 Cursor、Copilot、Gemini 等）中。它解决了 AI 助手“健忘”、跨平台不一致以及缺乏专业领域知识的问题。

环境准备

• 操作系统：支持 Linux、macOS 和 Windows。
• Python 版本：需要 Python 3.9 或更高版本。
• 前置依赖：推荐使用 uv 进行快速安装和管理（无需手动配置 Python 虚拟环境）。

安装步骤

本指南推荐使用 uv 工具链，它能自动处理 Python 环境依赖。

1. 安装 uv 如果尚未安装 uv，请运行以下命令：

   curl -fsSL https://astral.sh/uv/install.sh | bash
   

   注：国内用户若下载缓慢，可尝试使用镜像源或手动下载安装脚本。

2. 验证安装 安装完成后，确保终端可以识别 uvx 命令。

基本使用

以下是将 rulebook-ai 集成到当前项目的最简流程：

1. 添加基础包 (Pack)

在项目根目录下，添加一个预设的“轻量级规范”包（light-spec）。这是官方推荐的起始包，能让 AI 像初级开发者一样遵循标准的规划、编码和调试流程。

uvx rulebook-ai packs add light-spec

2. 同步环境到工作区

运行同步命令。该命令会自动创建 .rulebook-ai 状态目录，初始化 memory/（项目记忆）和 tools/（辅助脚本），并根据你使用的 AI 助手生成对应的规则文件（如 .cursor/rules/ 或 GEMINI.md）。

uvx rulebook-ai project sync

3. 指定 AI 助手（可选）

如果你只针对特定的 AI 助手生成规则，可以使用 --assistant 标志。例如，仅针对 Cursor 和 GitHub Copilot：

uvx rulebook-ai project sync --assistant cursor copilot

若要为所有支持的助手生成规则：

uvx rulebook-ai project sync --all

4. 后续管理

• 提交版本控制：请将生成的 memory/ 和 tools/ 目录提交到 Git，这是你的核心环境配置。
• 忽略生成物：请将 .rulebook-ai/、.cursor/ 及其他生成的规则文件添加到 .gitignore 中，因为它们可以随时重新生成。

现在，你的 AI 助手已经具备了项目特定的上下文和专业规则，可以直接开始高效协作。