primer-cli：为AI编程助手打造结构化项目规范与智能脚手架

1. 项目概述：为AI时代重构开发脚手架

如果你和我一样，每天都要和Cursor、Claude Code这类AI编程助手打交道，那你肯定也经历过那种“鸡同鸭讲”的混乱时刻。你让AI帮你写个数据库迁移脚本，它却开始跟你讨论前端组件的状态管理；你让它按照公司的架构规范来组织代码，它却完全无视你精心编写的文档。这种挫败感，我经历了太多次。

直到我意识到问题不在AI，而在于我们——我们习惯了把项目文档扔在某个角落，然后指望AI能像资深同事一样，瞬间理解整个项目的上下文、规范、禁忌和最佳实践。这怎么可能呢？人类工程师都需要几个月才能熟悉一个项目的“潜规则”，凭什么要求AI在几秒钟内就掌握？

这就是我开发primer-cli的初衷。它不是一个普通的项目脚手架工具，而是一个AI就绪项目生成器。它的核心思想很简单：既然AI无法主动学习我们的项目规范，那我们就主动把规范“喂”给它，用一种AI能理解、能遵循的格式，从项目诞生的第一天起就建立秩序。

简单来说，primer init这一条命令，会为你生成一个自带“AI使用说明书”的项目骨架。这份说明书不是给人看的Markdown文件（虽然也有），而是一整套结构化、可执行的规则、命令和知识库，直接集成到Cursor和Claude Code的工作流中。从此，AI助手在你的项目里不再是一个需要不断纠正的“实习生”，而是一个清楚知道该读什么、该做什么、该避免什么的“正式员工”。

2. 核心设计理念：将隐性知识显性化、结构化

2.1 为什么传统的README和文档对AI无效？

我们过去的项目文档，本质上是叙事性和参考性的。它们像一本小说或一本字典，适合人类线性阅读或按需查阅。但AI，特别是编程助手，工作在一个指令-执行的循环中。当你输入一个模糊的指令时，它需要快速、准确地定位到相关的上下文。

举个例子，你的项目里有一个docs/backend/architecture.md文件，详细描述了REST API的设计规范、错误处理中间件、日志格式等。但当你对AI说“帮我加个用户登录的API端点”时，AI怎么知道要去读这个文件？即使它读了，又怎么从几千字中提取出“必须使用Zod进行请求验证”、“错误响应必须遵循{code, message, details}格式”这些具体的、强制性的规则？

传统文档的失败在于上下文缺失和约束力不足。primer-cli的解决方案是双重的：

1. 强制入口点：在每个生成的项目根目录，都会有一个AGENTS.md文件。这个文件是给AI的“总导航”，用最清晰的语言告诉AI：“进入这个项目，请首先阅读以下文件以了解全局上下文”。这解决了“从哪开始读”的问题。
2. 规则化知识：将领域知识（如数据库、认证）打包成“技能包”。这些包不仅包含人类可读的说明，更重要的是包含.cursor/rules/下的.mdc规则文件。这些规则文件会被Cursor自动加载，成为AI在编写该领域代码时必须遵守的“法律”。这解决了“必须怎么做”的问题。

2.2 技能包：领域知识的原子化封装

这是primer最精髓的设计。我们不再写笼统的“后端开发指南”，而是将其拆解成一个个高内聚、低耦合的技能包。目前primer内置了五个核心技能包：

• 数据库：涵盖从Schema设计、迁移脚本编写、查询优化到安全审计的全链路知识。AI在操作数据库时，会被规则提醒“所有新增字段必须为NOT NULL并提供默认值”、“JOIN查询必须检查N+1问题”。
• 认证：聚焦于AuthN（认证）和AuthZ（授权）。规则会强制要求“密钥必须存储在环境变量中，严禁硬编码”、“所有用户输入在用于数据库查询前必须经过参数化处理以防止SQL注入”。
• 后端：定义API契约、弹性模式（如熔断器、重试）、流量控制和可观测性标准。AI在创建API时，会被要求“接口响应必须包含requestId用于链路追踪”、“必须实现健康检查端点/health”。
• 前端：针对现代React生态（特别是Next.js App Router），明确服务端组件与客户端组件的边界、水合注意事项、以及基于Feature-Sliced Design的架构规范。
• 测试：专门应对AI生成代码的测试痛点，包括如何为AI生成的代码植入“变异测试”、如何进行契约测试，以及如何诊断和修复不稳定的测试用例。

每个技能包都包含三部分：

1. 知识文档(docs/skills/): 给人类开发者看的原理和最佳实践。
2. Cursor规则(.cursor/rules/): 自动加载的、强制性的编码约束。
3. Slash命令(.cursor/commands/agents/): 封装了复杂工作流的快捷指令，例如/design-schema会引导AI通过一系列问答来设计数据库Schema。

这种设计让知识的复用和组合变得极其灵活。一个初创项目可能只需要database和backend技能，而一个大型全栈应用则可以启用全部五个。

2.3 Git纪律：被编码的最佳实践

版本控制是团队协作的基石，但也是最容易产生混乱的地方。primer将一套严格的Git工作流直接“烧录”进项目模板：

1. 分支策略：禁止直接向默认分支（如main）提交。所有改动必须通过特性分支进行。
2. 分支命名：强制使用<type>/<scope>-<description>格式，如feat/auth-add-otp或fix/payment-handle-null-amount。这使分支目的一目了然。
3. 提交信息：要求符合Conventional Commits规范，并带scope，如feat(auth): 添加基于时间的一次性密码验证。这为自动生成变更日志打下了基础。
4. 自动化检查：在每次提交前，自动运行类型检查、代码风格检查和测试。只有全部通过，代码才被允许提交。
5. PR工作流：通过/git-start-work,/git-commit-progress,/git-finish-work等命令，引导开发者完成“创建分支->开发->提交->推送->创建PR->合并”的标准流程。

实操心得：这套“纪律”刚开始可能会让习惯自由提交的开发者感到束缚，但坚持一两周后，你会发现代码库的历史变得无比清晰。更重要的是，当AI助手进行代码重构或功能添加时，它也会遵循这套流程，自动创建语义清晰的分支和提交，极大降低了后续代码审查和合并的认知负担。

3. 从零开始：使用primer-cli搭建你的第一个AI就绪项目

3.1 环境准备与安装

primer-cli基于Node.js开发，因此你需要先确保本地环境已安装Node.js（建议版本18或以上）和npm/pnpm/yarn等包管理器。

# 使用npm全局安装（最通用） npm install -g @monomit/primer # 或者，如果你像我一样偏爱pnpm的速度和磁盘效率 pnpm add -g @monomit/primer # 安装后验证 primer --version

安装成功后，直接运行primer命令（不带任何参数），你会进入一个精美的交互式界面。这个界面不仅展示了工具版本和核心命令，还会自动检测你系统中配置的AI提供商API密钥（如ANTHROPIC_API_KEY），并给出可视化提示。这对于新手来说非常友好，能快速了解工具状态。

3.2 初始化一个全新项目

假设我们要创建一个名为next-saas-starter的全栈SaaS项目。

# 1. 创建一个项目目录并进入 mkdir next-saas-starter && cd next-saas-starter # 2. 运行primer初始化 primer init

执行primer init后，你会经历一个简短的交互式配置过程：

1. 项目名称：默认使用当前目录名 (next-saas-starter)，可直接回车确认。
2. 包管理器：选择你偏好的工具 (npm,yarn,pnpm)。这里的选择会影响后续依赖安装命令的生成。我强烈推荐pnpm，它在Monorepo和磁盘空间利用上优势明显。
3. AI提供商：选择你主要使用的AI编程助手。如果你主要用Cursor，选claude(Anthropic) 或openai；如果主要用Claude Code，同样选claude。这个选择决定了生成的Agent角色描述和brief-me命令使用的模型。
4. AI工具：选择你计划在本项目中使用哪些工具（可多选）。例如，同时选中cursor和claude-code。primer会为所有选中的工具生成对应的配置目录。
5. 技能包：根据项目类型选择需要的领域知识。对于一个全栈SaaS，我们可以全选database,auth,backend,frontend,testing。

配置完成后，primer会开始执行一系列动作：

• 生成项目基础结构（src/,package.json等）。
• 创建所有核心文档（AGENTS.md,GETTING_STARTED.md等）。
• 在.cursor/和.claude/目录下生成规则和命令文件。
• 安装你选择的技能包到docs/skills/和对应的AI工具配置目录。
• 初始化Git仓库，并按照Git纪律进行第一次提交。

整个过程大约1-2分钟。完成后，你的项目目录已经焕然一新，充满了各种“AI友好”的元数据。

3.3 解读生成的核心文件

让我们看看primer init究竟生成了什么，以及每个文件的作用：

next-saas-starter/ ├── AGENTS.md # 【核心】AI入口文件，必须首先阅读 ├── GETTING_STARTED.md # 人类开发者上手指南，包含精确的下一步命令 ├── .primer/ │ └── project.json # Primer自身配置，记录你的所有选择 ├── docs/ │ ├── CANONICAL_ARCHITECTURE.md # 【待填充】技术栈与架构决策记录 │ ├── CANONICAL_PATTERNS.md # 【待填充】代码风格与模式规范 │ ├── agents/ # AI生成的、针对本项目的具体Agent角色定义 │ └── skills/ # 已安装的技能包知识库（database/, auth/等） ├── .cursor/ # Cursor专用配置（如果选中） │ ├── rules/ # 自动加载的规则文件（.mdc格式） │ │ ├── core.mdc │ │ ├── git-discipline.mdc │ │ ├── database.mdc │ │ └── ... │ └── commands/ # 自定义Slash命令 │ └── agents/ │ ├── database/ │ ├── auth/ │ └── ... ├── .claude/ # Claude Code专用配置（如果选中） │ ├── CLAUDE.md # Claude Code的入口文件 │ └── commands/ │ └── agents/ │ ├── database/ │ ├── auth/ │ └── ... └── src/ └── index.ts # 项目源码入口（示例）

关键文件解析：

• AGENTS.md：这是整个项目的“总开关”。它的内容是指令性的，例如：

  # Agent Instructions for [next-saas-starter] BEFORE you write any code in this project, you MUST read and understand the following documents: 1. **Architecture & Patterns**: Read `docs/CANONICAL_ARCHITECTURE.md` and `docs/CANONICAL_PATTERNS.md` to understand our technical stack and coding conventions. 2. **Domain Skills**: Consult the `docs/skills/` directory for deep knowledge on specific domains (Database, Auth, etc.). 3. **Git Discipline**: All changes MUST follow the workflow defined in `.cursor/rules/git-discipline.mdc` (or `.claude/commands/git-discipline.mdc`). ... (具体指令省略)

  每次你新开一个AI会话，第一件事就是把这个文件的内容贴进去。这相当于给了AI一个清晰的“入职培训”。

• docs/CANONICAL_*.md：这两个文件是需要你手动填充的。这是priner哲学的一部分：工具搭建框架，你来注入灵魂。在CANONICAL_ARCHITECTURE.md里，定义你的技术栈（如Next.js 15, Prisma, Tailwind, Resend）。在CANONICAL_PATTERNS.md里，定义你的代码规范（如函数命名用camelCase，错误处理用Result类型）。AI会严格遵守这里的约定。

• .cursor/rules/*.mdc：这些是Magic文件，会被Cursor自动识别和加载。打开database.mdc，你可能会看到这样的规则：

  When writing database schemas or queries: - Always define explicit primary keys named `id` of type `String @id @default(comeon())`. - All optional fields must be explicitly marked as `?` in TypeScript or `nullable` in Prisma. - Never write raw SQL queries without using parameterized statements or an ORM's query builder.

  这些规则会作为上下文，持续影响AI在你项目中的所有编码行为。

• GETTING_STARTED.md：这不是一个泛泛而谈的文档。它会根据你的选择（包管理器、技能包）生成精确的、可复制粘贴的命令行指令，比如pnpm install,pnpm dev，以及如何填充那些Canonical文档。

3.4 为现有项目注入AI能力：retrofit命令

也许你已经在开发一个项目了，难道要推倒重来？当然不用。primer retrofit命令就是为现有项目设计的“升级工具”。

# 在你现有项目的根目录下运行 primer retrofit

这个命令非常智能：

1. 检测：它会扫描你的项目，识别出现有的包管理器（通过package.json和锁文件）、项目结构、以及可能已经存在的AI工具配置。
2. 分析：对比primer的标准配置，找出缺失的部分（比如没有AGENTS.md，没有技能包规则）。
3. 生成：以非破坏性的方式添加缺失的文件和配置。它默认不会覆盖任何已有文件（除非使用--force标志）。
4. 预览：强烈建议先使用--dry-run参数预览将要进行的更改。

   primer retrofit --dry-run

   这会输出一个详细的报告，列出所有将要创建或修改的文件，让你心中有数。

注意事项：retrofit不会改变你的源代码结构，它只添加元文件和配置。它的目标是让你的项目“AI-ready”，而不是重构你的代码。

4. 深度使用：让AI成为你的项目专家

4.1 生成项目技术简报：brief-me命令

当项目复杂到一定程度，或者有新成员（无论是人类还是AI）加入时，快速理解项目全貌成为一个挑战。primer brief-me命令解决了这个问题。

# 在项目根目录运行，生成全面的技术简报 primer brief-me

这个命令会做以下几件事：

1. 读取：它会读取你项目中的核心文档（CANONICAL_ARCHITECTURE.md,CANONICAL_PATTERNS.md, 技能包文档，以及AGENTS.md）。
2. 分析：利用你配置的AI模型（默认是Claude Sonnet），理解这些文档的内容和关联。
3. 生成：在docs/BRIEF.md中生成一份结构清晰的技术简报，通常包含：
   • 架构摘要：项目整体技术栈和模块划分。
   • 领域分解：按技能包（数据库、认证等）详细说明当前的设计决策、使用的库和关键模式。
   • 关键模式：从代码规范文档中提取的核心编码约定。
   • “开始构建”序列：一份按部就班的清单，指导如何开始开发一个新功能（例如：“1. 创建特性分支feat/your-feature。2. 查阅docs/skills/database/以了解数据模型规范...”）。

高级用法：你可以使用--domain参数为特定领域生成深度简报。

# 只生成关于数据库领域的简报 primer brief-me --domain database

这对于在复杂系统中专注于某一个模块的改造或排查问题特别有用。

4.2 配置与定制：primer.config.json

primer提供了丰富的配置选项，让你可以微调AI Agent的生成行为。在项目根目录创建primer.config.json文件：

{ "ai": { "maxTokens": 8192, // AI生成内容的最大长度 "maxAgents": 4, // 最多生成几个专属Agent角色 "maxCommandsPerAgent": 3, // 每个Agent最多有几个快捷命令 "maxRulesPerAgent": 2, // 每个Agent的核心规则数量 "maxStepsPerCommand": 5, // 每个命令最多分几步执行 "maxDoNotPerCommand": 3, // 每个命令中“禁止事项”的最大条数 "maxRulesPerRuleSet": 5, // 每个规则集（如database.mdc）的最大规则数 "maxAdditionalRules": 5 // 除核心规则外，可添加的额外规则数 } }

配置心得：不要一开始就修改所有配置。建议先用默认设置运行几次，观察生成的Agent和规则是否符合你的预期。如果你发现生成的Agent角色描述过于冗长，可以适当调低maxTokens和maxAgents。如果你希望规则更严格、更细致，可以增加maxRulesPerRuleSet。这些配置项是primer灵活性的体现，让你能控制AI“助手”的“性格”和“能力边界”。

4.3 离线模式与多AI提供商支持

primer支持三种主流的AI提供商：Anthropic的Claude、OpenAI的ChatGPT和Google的Gemini。通过环境变量设置API密钥即可：

# 设置Claude (Anthropic) - 推荐，与Cursor/Claude Code集成最好 export ANTHROPIC_API_KEY='your-key-here' # 设置OpenAI export OPENAI_API_KEY='your-key-here' # 设置Gemini export GEMINI_API_KEY='your-key-here'

运行primer init或primer brief-me时，它会自动检测可用的API密钥，并优先使用Claude。你也可以通过环境变量ANTHROPIC_MODEL等来指定使用的具体模型。

离线模式：如果你没有API密钥，或者想在完全离线的环境下使用primer的基础脚手架功能，可以使用--offline标志。

primer init --offline primer brief-me --offline

在离线模式下，init仍然会生成所有项目结构和技能包，但不会调用AI来生成自定义的Agent角色描述。brief-me命令则会生成一个基于模板的、较简单的简报。离线模式确保了工具在任何环境下都能使用。

5. 实战经验与避坑指南

经过大量项目的实际使用，我总结了一些关键的经验和常见问题的解决方法。

5.1 技能包的选择策略：不要贪多

primer提供了五个技能包，但并不意味着每个项目都要全选。盲目启用所有技能包会导致项目配置臃肿，AI上下文过长，反而降低效率。

• 纯后端API服务：选择database,backend,testing即可。auth包如果与你的认证方案（如JWT、OAuth）高度契合也可以加入。
• 纯前端应用：主要选择frontend，如果涉及与后端的大量API交互，可以加入backend技能包中的API契约部分。
• 全栈应用：可以全选，但建议在项目初期只启用最核心的database,backend,frontend。待项目稳定后，再通过primer retrofit添加auth和更深入的testing规则。

核心原则：技能包是“按需加载”的依赖。从最小集合开始，随着项目复杂度的增长而逐步添加。

5.2 Canonical文档的维护：保持活力

docs/CANONICAL_ARCHITECTURE.md和docs/CANONICAL_PATTERNS.md是项目的“宪法”。它们最大的风险不是写不好，而是写完后就被遗忘，与实际代码脱节。

• 设立更新触发器：将更新Canonical文档作为代码审查（PR Review）的一项必检内容。任何重大的技术栈变更、架构调整或新的模式引入，都必须同步更新这些文档。
• 内容具体，避免空话：不要写“我们应该编写高质量的代码”。要写“函数长度不应超过50行，超过应拆分为子函数”、“错误信息必须本地化，键名遵循error.<module>.<action>.fail格式”。
• 与技能包联动：在Canonical文档中，可以引用具体的技能包。例如，在架构文档中写到数据访问层时，注明“具体规范请参阅docs/skills/database/query-optimization.md”。

5.3 处理AI的“规则冲突”与“创造性”

有时，AI可能会遇到两条看似冲突的规则，或者它想用一种更“聪明”但不符合规则的方式解决问题。

• 规则优先级：primer生成的规则是有优先级的。通常，.cursor/rules/core.mdc和git-discipline.mdc中的规则具有最高优先级，其次是具体领域（如database.mdc）的规则。在AGENTS.md中应该明确指示AI：“当领域规则与核心规则冲突时，以核心规则为准”。
• 鼓励沟通，而非盲从：在规则中，可以加入这样的表述：“如果你认为某条规则在当前上下文中不适用，或者有更好的实现方案，请首先向开发者提问并解释你的理由，而不是直接违反规则。” 这赋予了AI一定的灵活性，但决定权仍在开发者手中。
• 定期审查规则：每个季度或每个重大版本，花时间回顾一下.cursor/rules/下的规则文件。有些规则可能已经过时，或者发现了新的需要约束的常见错误。使用primer retrofit可以更新技能包，但自定义的规则需要手动维护。

5.4 常见问题排查

问题1：运行primer init时卡住或报网络错误。

• 可能原因：在非离线模式下，primer需要调用AI API来生成Agent角色。网络不通或API密钥无效会导致失败。
• 解决：
  1. 检查网络连接。
  2. 使用primer init --offline跳过AI生成步骤。
  3. 确认你的API密钥环境变量设置正确且未过期。可以通过echo $ANTHROPIC_API_KEY来验证。
  4. 如果使用代理，请确保终端能正确访问外部API。

问题2：Cursor没有自动加载.cursor/rules/下的规则。

• 可能原因：Cursor的规则自动加载可能需要重启或特定设置。
• 解决：
  1. 完全关闭Cursor IDE并重新打开项目。
  2. 在Cursor的设置中，确认“Enable Project Rules”选项是开启的。
  3. 检查.cursor/rules/目录下的.mdc文件格式是否正确。可以尝试在Cursor中手动打开一个.mdc文件，如果语法高亮正常，说明格式没问题。

问题3：primer retrofit命令没有检测到我的现有配置。

• 可能原因：项目结构非常规，或者使用了priner不直接支持的框架/工具链。
• 解决：
  1. 始终先使用primer retrofit --dry-run预览。如果输出为空，说明priner认为没有需要添加的东西，或者无法识别项目类型。
  2. 检查你的项目是否有package.json文件，这是priner识别为Node.js项目的主要依据。
  3. primer目前主要针对Node.js/TypeScript生态优化。对于其他语言（如Go, Python, Rust），其生成的通用文档（如AGENTS.md,GETTING_STARTED.md）仍然有用，但技能包中的具体规则和命令可能需要你手动调整或只作为参考。

问题4：生成的Agent角色描述或技术简报内容空洞、不准确。

• 可能原因：docs/CANONICAL_*.md文件内容过于简略或还未填充。
• 解决：brief-me命令的质量完全依赖于输入文档的质量。确保你的Canonical文档已经详细、准确地描述了项目的技术栈、架构决策和代码规范。内容越丰富，AI生成的简报就越有价值。

primer-cli的本质，是将优秀开发者的经验和纪律，转化为机器可读、可执行的规范。它不会取代你的思考，而是将你从重复的、低层次的规范传达中解放出来，让你和你的AI助手能更专注于创造性的问题解决和架构设计。从这个角度看，它不只是脚手架，更是一个项目级的“认知外挂”。