primer-cli：AI就绪项目脚手架，标准化AI协作开发流程

1. 项目概述：primer-cli，一个为AI协作时代量身定制的项目脚手架

如果你和我一样，每天都在和Cursor、Claude Code这类AI编程工具打交道，那你一定遇到过这样的困境：每次新建一个项目，都得花上半天甚至一天的时间，去手动配置那些能让AI“懂你”的规则文件。你得写.cursor/rules，得准备AGENTS.md，得设计一套能让AI理解项目架构和编码规范的文档。这个过程繁琐、重复，而且极易出错，不同项目间的配置还常常不一致，导致AI助手时而灵光乍现，时而“胡言乱语”。

primer-cli就是为了终结这种混乱而生的。它不是一个普通的项目生成器，而是一个**“AI就绪”** 项目的标准化生产线。简单来说，它把那些经过无数项目验证、能极大提升AI协作效率的最佳实践——包括智能体角色定义、架构文档模板、Git工作流纪律、领域技能包——全部封装进一条简单的命令里。你只需要运行primer init，就能获得一个开箱即用、AI助手能立刻高效参与开发的项目骨架。这对于独立开发者、初创团队，或者任何希望将AI深度集成到开发流程中的工程师来说，都是一个能显著提升“人机协作”体验和项目启动效率的利器。

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

为什么我们需要primer这样的工具？其背后的核心逻辑在于，当前AI编程助手的能力发挥，严重依赖于我们提供给它的“上下文”质量。这个上下文不仅仅是代码，更包括项目的架构意图、领域知识、协作规则和操作惯例。这些信息往往是隐性的，存在于资深开发者的脑子里，或者散落在零碎的文档和注释中。

2.1 从“对话式提示”到“工程化配置”的范式转变

在没有primer之前，我们与AI的协作模式是“对话式”的。我们需要在每次对话中，反复向AI描述：“我们这是一个Next.js全栈项目，用Prisma做ORM，采用Feature-Sliced Design（FSD）架构，提交信息要遵循Conventional Commits规范……” 这不仅低效，而且信息在多次对话中容易丢失或产生偏差。

primer推动的是一种“工程化配置”的范式。它将所有关键的、非代码的上下文信息，结构化地写入项目本身，成为项目资产的一部分。具体体现在以下几个层面：

1. 规范文档结构化：生成的AGENTS.md、CLAUDE.md、CANONICAL_ARCHITECTURE.md等文件，为AI提供了权威的、唯一的真相来源。AI在分析代码或执行任务时，会优先参考这些文档，确保其理解和行动与项目整体设计保持一致。
2. 规则与命令的自动化加载：通过.cursor/rules/*.mdc和.cursor/commands/目录，primer将领域特定的规则和自定义的Slash命令直接注入到Cursor的运行时环境中。这意味着开发者无需手动激活或提醒，AI助手在项目内自然就“知道”该遵守什么规则，能使用什么高级命令。
3. 领域技能的模块化封装：这是primer最精妙的设计之一。它将“数据库设计”、“认证授权”、“后端API”、“前端架构”、“测试策略”等通用领域知识，打包成独立的“技能包”。每个技能包包含人类可读的参考文档和AI可直接执行的命令集。这相当于为你的AI助手提前安装了“专业插件”，让它从一个通才变成了在特定领域有专精的专家。

2.2 面向Git与团队协作的设计

一个优秀的项目脚手架，不仅要考虑单兵作战，更要为团队协作铺平道路。primer深谙此道，它内置的“Git纪律”系统，是我认为其最具远见的功能之一。

它不仅仅生成一个.gitignore文件，而是定义并自动化了一整套基于分支的Git工作流：

• 分支策略：强制使用形如feat/auth-jwt-rotation的分支命名规范，一目了然。
• 提交规范：强制使用Conventional Commits（如feat(auth): add JWT refresh rotation），这使得生成CHANGELOG和进行语义化版本发布变得轻而易举。
• 自动化门禁：通过预提交钩子（pre-commit hooks）串联起类型检查、代码风格检查和测试，确保进入版本库的每一行代码都符合基本质量要求。
• PR驱动流程：它倡导并可通过命令（/git-start-work,/git-finish-work）引导开发者走“创建功能分支 -> 开发提交 -> 发起PR -> 合并后删除分支”的标准流程，这极大地减少了主分支的污染，让代码审查和集成过程更清晰。

这套纪律被编码进git-discipline.mdc规则文件和相应的Slash命令中，AI助手在协助你提交代码时，也会遵循这套规范，从而在源头保障了项目历史记录的整洁与可追溯性。

3. 核心功能深度解析与实操指南

了解了设计理念，我们来看看primer具体能做什么，以及如何最高效地使用它。

3.1primer init：一站式项目初始化

这是最常用的命令。执行primer init后，primer会启动一个交互式向导。这个向导会询问你几个关键问题，你的选择将决定生成项目的形态：

1. 项目名称与包管理器：首先确定项目根目录名称和使用的包管理器（npm、yarn、pnpm）。primer会据此初始化package.json。
2. AI工具选择：你主要使用Cursor、Claude Code，还是两者都使用？primer会为选中的工具生成对应的配置目录（.cursor/和/或.claude/）。
3. AI提供商与模型选择：primer需要调用AI API来为你生成定制的智能体角色文档。你需要选择Claude、ChatGPT或Gemini之一，并确保对应的API密钥（如ANTHROPIC_API_KEY）已设置在环境变量中。模型通常使用各提供商的最新版主力模型（如Claude 3.5 Sonnet）。
4. 领域技能包选择：从数据库、认证、后端、前端、测试五个技能包中，根据你的项目类型勾选需要的。例如，一个全栈Web项目可能全选，而一个纯后端API服务可能只选数据库、认证和后端。

实操心得：即使你暂时不确定是否需要某个技能包，也建议勾选上。primer生成的技能文档是极佳的学习资料，其命令也能启发你思考项目中可能需要的功能。后期不需要可以手动删除相关文件，但一开始多了解一些模式没有坏处。

完成选择后，primer会开始执行以下原子操作，这些操作共同构成了“AI就绪”的状态：

• 生成核心文档：创建AGENTS.md（AI智能体总入口）、GETTING_STARTED.md（你的项目专属启动指南）。
• 生成架构文档模板：创建docs/CANONICAL_ARCHITECTURE.md和CANONICAL_PATTERNS.md，你需要在这里手动填充你的技术栈选型（如“我们使用PostgreSQL + Prisma + tRPC”）和核心编码模式（如“错误处理使用Result模式”）。这是最关键的一步，因为这些内容将成为AI理解你项目的基础。
• 安装技能包：将你选择的技能包内容，分别写入docs/skills/目录（供人阅读）和对应的AI工具命令/规则目录（供AI使用）。
• 调用AI生成智能体角色：primer会将你的项目配置（名称、技能包）和架构模板发送给你指定的AI提供商，请求其生成2-4个具体的智能体角色描述（如“数据库架构师”、“API合约设计师”），并写入docs/agents/目录。这些角色描述会让AI在协作时更具“人格化”和针对性。
• 初始化Git并提交：执行git init，并将所有生成的文件进行初始提交，信息为“chore: primer init”。这确保了项目起点是清晰且可追溯的。

3.2primer retrofit：为已有项目注入AI能力

你不可能所有项目都从零开始。对于已有项目，primer retrofit命令就是救星。它的设计非常智能：

• 无损探测：它会扫描你的项目，识别出现有的包管理器、是否已有Cursor或Claude配置、已经包含了哪些类似技能（通过分析package.json和目录结构）。
• 增量添加：它只会添加项目中缺失的primer组件，而不会覆盖或修改任何现有文件。例如，如果你已有自己的.cursor/rules文件，primer会将自己的规则文件放在旁边，而不是替换它。
• 预览与强制模式：使用--dry-run参数可以预览retrofit将会进行的所有更改，确认无误后再实际执行。如果你确信需要覆盖个别文件（请谨慎），可以使用--force参数。

一个典型场景：你有一个运行了半年的Express后端项目，之前都是手动和AI协作。现在运行primer retrofit，它会为你补上AGENTS.md、数据库和后台技能包、以及Git纪律规则，瞬间将这个老项目升级为“AI就绪”状态。

3.3primer brief-me：生成项目技术简报

这是primer另一个杀手级功能。随着项目发展，文档可能滞后，新成员（包括未来的你）或新的AI会话需要快速理解项目全貌。primer brief-me命令能自动完成这件事。

它会综合分析你项目中的核心文档（CANONICAL_*文件）、智能体角色和技能包知识，生成一份结构清晰的docs/BRIEF.md文件。这份简报通常包括：

• 架构摘要：用一两句话概括项目是做什么的，核心架构是什么。
• 领域分解：基于技能包，列出项目涉及的核心领域（如“用户认证”、“数据模型”、“API层”）。
• 关键模式与决策：提炼出最重要的技术选型和设计模式。
• “开始构建”序列：给出一个具体的、下一步可以执行的开发任务清单，例如“1. 在prisma/schema.prisma中定义User模型；2. 运行prisma migrate dev；3. 在src/routers/user.router.ts中实现CRUD端点”。

你还可以使用--domain参数生成针对特定领域（如--domain database）的深度简报，这对于聚焦解决某个模块的问题特别有帮助。

4. 技能包详解：AI的“专业工具箱”

primer的五大技能包是其灵魂所在。它们不是简单的代码片段合集，而是包含“知识”、“命令”和“规则”的完整体系。我们以Database和Auth技能包为例，深入看看它们提供了什么。

4.1 Database技能包

知识文档 (docs/skills/database/README.md)： 这部分是给开发者看的，它系统化地阐述了在本项目语境下关于数据库的最佳实践。例如，它可能规定：

• ORM/查询工具：本项目使用Prisma。所有数据库交互必须通过Prisma Client进行。
• 模式设计原则：遵循描述性命名、适当的数据类型、定义明确的关系和索引。
• 迁移策略：使用Prisma Migrate，每次模式变更都必须生成并审核迁移文件。
• 性能守则：N+1查询是绝对禁止的，复杂查询必须考虑分页和索引优化。
• 安全红线：严禁拼接SQL字符串，用户输入必须经过验证和参数化处理。

AI规则与命令： 对应的，在.cursor/rules/database.mdc中，会写入让AI强制遵守的规则，例如：

- 当修改数据模型时，必须同时更新Prisma schema文件并计划生成迁移。 - 回答涉及查询的问题时，必须优先考虑性能，提及索引和关联加载。 - 绝对不允许提供使用字符串拼接生成SQL的示例代码。

在.cursor/commands/agents/database/目录下，则提供了可执行的Slash命令，例如：

• /design-schema：引导AI根据你的自然语言描述，生成符合规范的Prisma数据模型定义。
• /create-migration：在修改schema后，引导AI为你生成下一步的Prisma迁移命令和迁移文件草稿。
• /optimize-query：分析你提供的Prisma查询代码，提出性能优化建议（如添加include、使用select、添加索引等）。
• /audit-security：审查指定的模型或查询，识别潜在的安全风险（如数据暴露、注入漏洞）。

4.2 Auth技能包

知识文档： 会定义本项目的认证授权范式。例如：“本项目采用基于JWT的无状态认证。使用argon2进行密码哈希。授权采用基于角色的访问控制（RBAC），角色定义在User模型中。”

AI规则与命令： 规则文件会强调：“所有新端点都必须考虑认证和授权。密码比较必须使用恒定时间比较函数。” 命令则包括：

• /setup-auth-provider：引导设置NextAuth.js或类似库的配置。
• /configure-access-policy：根据用户角色（如‘admin’， ‘user’），为某个API路由或组件生成授权逻辑。
• /rotate-secrets：提供安全轮换JWT密钥或数据库密码的步骤指南。

通过这种方式，技能包将领域专家的知识“固化”到了项目配置中，使得任何参与项目的AI（乃至新人开发者）都能快速达到一个较高的协作基线。

5. 配置、定制与进阶使用

primer提供了灵活的配置方式，以适应不同项目和团队的个性化需求。

5.1 项目级配置：primer.config.json

你可以在项目根目录创建primer.config.json文件，来精细控制AI生成内容的行为。例如：

{ "ai": { "maxTokens": 4096, // 控制生成文档的详细程度 "maxAgents": 3, // 最多生成几个智能体角色 "maxCommandsPerAgent": 2, // 每个智能体关联的命令数 "maxStepsPerCommand": 4 // 每个命令最多几步 } }

这个配置主要影响primer init时调用AI生成agents文档的过程。如果你觉得默认生成的文档太冗长，可以调低maxTokens；如果你希望角色更聚焦，可以减少maxAgents。

5.2 离线模式与模型覆盖

有时你没有可用的API密钥，或者想使用特定的模型。primer提供了相应的选项：

• --offline：在离线模式下运行，primer将使用内置的模板生成智能体角色，而不会调用AI API。生成的内容是通用型的，但项目骨架和技能包依然完整。
• 环境变量覆盖：你可以通过设置ANTHROPIC_MODEL、OPENAI_MODEL等环境变量，来指定使用不同的AI模型（例如，使用更便宜的claude-haiku或gpt-4o-mini来生成文档）。

5.3 理解.primer/project.json

初始化后，primer会在项目根目录的.primer/文件夹下生成一个project.json文件。这个文件记录了项目初始化时的所有元数据：

{ "projectName": "my-saas-app", "packageManager": "pnpm", "aiProvider": "claude", "aiTools": ["cursor"], "skills": ["database", "auth", "backend", "frontend"], "createdAt": "2024-06-15T10:30:00.000Z", "primerVersion": "1.1.0" }

这个文件至关重要。当你后续在这个项目中运行primer brief-me或再次运行primer retrofit时，primer会读取这个文件，确保其行为与项目初始设置保持一致。请不要手动删除或随意修改此文件。

6. 常见问题与故障排查实录

在实际使用中，你可能会遇到一些问题。以下是我在多次使用中总结出的常见情况及解决方法。

6.1 初始化阶段问题

问题1：运行primer init时卡在“Generating agent roles with AI...”很久，最后报超时错误。

• 原因：网络连接问题，或AI提供商API不稳定，或请求的令牌数（maxTokens）设置过高。
• 排查：
  1. 检查你的API密钥环境变量设置是否正确（echo $ANTHROPIC_API_KEY）。
  2. 尝试使用--offline模式初始化，看是否能成功。如果可以，则问题出在AI API调用环节。
  3. 临时设置一个更低的maxTokens（如2048）在配置文件中，或使用响应更快的模型（如claude-haiku）。
• 解决：使用离线模式完成初始化，之后可以手动编写或稍后使用primer brief-me（同样可离线）来补充智能体文档。

问题2：技能包的命令在我的AI工具（如Cursor）中没有出现。

• 原因：Cursor或Claude Code没有正确加载自定义命令目录。这可能是因为工具版本问题、配置路径错误，或需要重启AI工具。
• 排查：
  1. 确认primer init时正确选择了你使用的AI工具。
  2. 检查项目目录下是否生成了对应的.cursor/commands/agents/或.claude/commands/agents/文件夹，并且里面有.mdc文件。
  3. 在Cursor中，尝试通过快捷键（通常是Cmd/Ctrl + Shift + P）打开命令面板，搜索是否存在以/开头的primer命令（如/design-schema）。
• 解决：最有效的方法是完全关闭并重新启动你的Cursor或Claude Code应用。这些工具通常在启动时加载自定义命令，热加载可能不生效。

6.2 使用与协作问题

问题3：AI助手似乎忽略了.cursor/rules里我定义的规则。

• 原因：Cursor的规则加载有优先级，且AI对规则的理解和执行存在概率性。也可能是规则描述不够清晰或存在冲突。
• 排查：
  1. 在Cursor的设置中，确认“Rules”路径指向了你的项目目录。
  2. 检查规则文件语法是否正确，是否是.mdc格式，规则描述是否具体、无歧义。例如，“写好代码”是模糊的，“所有函数都必须有JSDoc注释，描述其作用和参数”是清晰的。
  3. 在对话中，你可以尝试明确提醒AI：“请参考我们项目中的database.mdc规则文件。”
• 解决：将最重要的、非此即彼的规则写得极其明确。对于复杂的逻辑，考虑将其拆解为具体的Slash命令，让AI通过执行命令来遵循最佳实践，这比依赖其自主理解规则更可靠。

问题4：团队其他成员使用primer时，生成的文档或规则与我的不一致。

• 原因：primer的模板或技能包可能更新了，或者他们使用了不同的配置选项（如选择了不同的技能包）。
• 解决：
  1. 锁定版本：在团队内部约定使用特定版本的primer CLI（npm install -g @monomit/primer@1.1.0）。
  2. 共享配置：将团队达成一致的primer.config.json文件纳入版本控制。
  3. 代码化初始化：对于核心项目，可以考虑将初始化后生成的、需要团队统一的文件（如AGENTS.md,.cursor/rules下的核心规则）的“黄金版本”保存在一个内部模板仓库中，新成员直接复制，而非完全依赖primer动态生成。

6.3 高级定制与扩展

问题5：我想为我的团队添加一个特定的领域技能包，比如“支付集成”或“内部监控”。

• 方法：primer目前（v1.1.0）尚未开放用户自定义技能包的官方插件体系。但你可以通过手动仿照现有技能包的结构来实现：
  1. 在docs/skills/下创建payments/目录，编写你的领域知识README。
  2. 在.cursor/rules/下创建payments.mdc文件，编写支付相关的硬性规则。
  3. 在.cursor/commands/agents/payments/下创建.mdc文件，定义像/setup-stripe、/handle-webhook这样的命令。
  4. 最后，你需要手动更新AGENTS.md，将你的支付专家智能体角色描述添加进去。
• 建议：关注primer项目的GitHub仓库，这类扩展性功能很可能在未来的版本中提供。

primer-cli的出现，标志着一个新的趋势：将AI协作从临时的、基于对话的“手工作坊”模式，升级为可重复、可配置、可继承的“工业化”模式。它节省的远不止是项目初始化那一个小时，而是在整个项目生命周期中，通过维持一个高质量、结构化的AI上下文环境，持续提升开发效率和代码质量。虽然它在初期需要你投入一些时间去理解和填充那些架构文档，但这份投资带来的长期回报——一个真正“懂你”的项目环境——绝对是值得的。