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的解决方案是双重的强制入口点在每个生成的项目根目录都会有一个AGENTS.md文件。这个文件是给AI的“总导航”用最清晰的语言告诉AI“进入这个项目请首先阅读以下文件以了解全局上下文”。这解决了“从哪开始读”的问题。规则化知识将领域知识如数据库、认证打包成“技能包”。这些包不仅包含人类可读的说明更重要的是包含.cursor/rules/下的.mdc规则文件。这些规则文件会被Cursor自动加载成为AI在编写该领域代码时必须遵守的“法律”。这解决了“必须怎么做”的问题。2.2 技能包领域知识的原子化封装这是primer最精髓的设计。我们不再写笼统的“后端开发指南”而是将其拆解成一个个高内聚、低耦合的技能包。目前primer内置了五个核心技能包数据库涵盖从Schema设计、迁移脚本编写、查询优化到安全审计的全链路知识。AI在操作数据库时会被规则提醒“所有新增字段必须为NOT NULL并提供默认值”、“JOIN查询必须检查N1问题”。认证聚焦于AuthN认证和AuthZ授权。规则会强制要求“密钥必须存储在环境变量中严禁硬编码”、“所有用户输入在用于数据库查询前必须经过参数化处理以防止SQL注入”。后端定义API契约、弹性模式如熔断器、重试、流量控制和可观测性标准。AI在创建API时会被要求“接口响应必须包含requestId用于链路追踪”、“必须实现健康检查端点/health”。前端针对现代React生态特别是Next.js App Router明确服务端组件与客户端组件的边界、水合注意事项、以及基于Feature-Sliced Design的架构规范。测试专门应对AI生成代码的测试痛点包括如何为AI生成的代码植入“变异测试”、如何进行契约测试以及如何诊断和修复不稳定的测试用例。每个技能包都包含三部分知识文档(docs/skills/): 给人类开发者看的原理和最佳实践。Cursor规则(.cursor/rules/): 自动加载的、强制性的编码约束。Slash命令(.cursor/commands/agents/): 封装了复杂工作流的快捷指令例如/design-schema会引导AI通过一系列问答来设计数据库Schema。这种设计让知识的复用和组合变得极其灵活。一个初创项目可能只需要database和backend技能而一个大型全栈应用则可以启用全部五个。2.3 Git纪律被编码的最佳实践版本控制是团队协作的基石但也是最容易产生混乱的地方。primer将一套严格的Git工作流直接“烧录”进项目模板分支策略禁止直接向默认分支如main提交。所有改动必须通过特性分支进行。分支命名强制使用type/scope-description格式如feat/auth-add-otp或fix/payment-handle-null-amount。这使分支目的一目了然。提交信息要求符合Conventional Commits规范并带scope如feat(auth): 添加基于时间的一次性密码验证。这为自动生成变更日志打下了基础。自动化检查在每次提交前自动运行类型检查、代码风格检查和测试。只有全部通过代码才被允许提交。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后你会经历一个简短的交互式配置过程项目名称默认使用当前目录名 (next-saas-starter)可直接回车确认。包管理器选择你偏好的工具 (npm,yarn,pnpm)。这里的选择会影响后续依赖安装命令的生成。我强烈推荐pnpm它在Monorepo和磁盘空间利用上优势明显。AI提供商选择你主要使用的AI编程助手。如果你主要用Cursor选claude(Anthropic) 或openai如果主要用Claude Code同样选claude。这个选择决定了生成的Agent角色描述和brief-me命令使用的模型。AI工具选择你计划在本项目中使用哪些工具可多选。例如同时选中cursor和claude-code。primer会为所有选中的工具生成对应的配置目录。技能包根据项目类型选择需要的领域知识。对于一个全栈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 ORMs query builder.这些规则会作为上下文持续影响AI在你项目中的所有编码行为。GETTING_STARTED.md这不是一个泛泛而谈的文档。它会根据你的选择包管理器、技能包生成精确的、可复制粘贴的命令行指令比如pnpm install,pnpm dev以及如何填充那些Canonical文档。3.4 为现有项目注入AI能力retrofit命令也许你已经在开发一个项目了难道要推倒重来当然不用。primer retrofit命令就是为现有项目设计的“升级工具”。# 在你现有项目的根目录下运行 primer retrofit这个命令非常智能检测它会扫描你的项目识别出现有的包管理器通过package.json和锁文件、项目结构、以及可能已经存在的AI工具配置。分析对比primer的标准配置找出缺失的部分比如没有AGENTS.md没有技能包规则。生成以非破坏性的方式添加缺失的文件和配置。它默认不会覆盖任何已有文件除非使用--force标志。预览强烈建议先使用--dry-run参数预览将要进行的更改。primer retrofit --dry-run这会输出一个详细的报告列出所有将要创建或修改的文件让你心中有数。注意事项retrofit不会改变你的源代码结构它只添加元文件和配置。它的目标是让你的项目“AI-ready”而不是重构你的代码。4. 深度使用让AI成为你的项目专家4.1 生成项目技术简报brief-me命令当项目复杂到一定程度或者有新成员无论是人类还是AI加入时快速理解项目全貌成为一个挑战。primer brief-me命令解决了这个问题。# 在项目根目录运行生成全面的技术简报 primer brief-me这个命令会做以下几件事读取它会读取你项目中的核心文档CANONICAL_ARCHITECTURE.md,CANONICAL_PATTERNS.md, 技能包文档以及AGENTS.md。分析利用你配置的AI模型默认是Claude Sonnet理解这些文档的内容和关联。生成在docs/BRIEF.md中生成一份结构清晰的技术简报通常包含架构摘要项目整体技术栈和模块划分。领域分解按技能包数据库、认证等详细说明当前的设计决策、使用的库和关键模式。关键模式从代码规范文档中提取的核心编码约定。“开始构建”序列一份按部就班的清单指导如何开始开发一个新功能例如“1. 创建特性分支feat/your-feature。2. 查阅docs/skills/database/以了解数据模型规范...”。高级用法你可以使用--domain参数为特定领域生成深度简报。# 只生成关于数据库领域的简报 primer brief-me --domain database这对于在复杂系统中专注于某一个模块的改造或排查问题特别有用。4.2 配置与定制primer.config.jsonprimer提供了丰富的配置选项让你可以微调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_KEYyour-key-here # 设置OpenAI export OPENAI_API_KEYyour-key-here # 设置Gemini export GEMINI_API_KEYyour-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密钥无效会导致失败。解决检查网络连接。使用primer init --offline跳过AI生成步骤。确认你的API密钥环境变量设置正确且未过期。可以通过echo $ANTHROPIC_API_KEY来验证。如果使用代理请确保终端能正确访问外部API。问题2Cursor没有自动加载.cursor/rules/下的规则。可能原因Cursor的规则自动加载可能需要重启或特定设置。解决完全关闭Cursor IDE并重新打开项目。在Cursor的设置中确认“Enable Project Rules”选项是开启的。检查.cursor/rules/目录下的.mdc文件格式是否正确。可以尝试在Cursor中手动打开一个.mdc文件如果语法高亮正常说明格式没问题。问题3primer retrofit命令没有检测到我的现有配置。可能原因项目结构非常规或者使用了priner不直接支持的框架/工具链。解决始终先使用primer retrofit --dry-run预览。如果输出为空说明priner认为没有需要添加的东西或者无法识别项目类型。检查你的项目是否有package.json文件这是priner识别为Node.js项目的主要依据。primer目前主要针对Node.js/TypeScript生态优化。对于其他语言如Go, Python, Rust其生成的通用文档如AGENTS.md,GETTING_STARTED.md仍然有用但技能包中的具体规则和命令可能需要你手动调整或只作为参考。问题4生成的Agent角色描述或技术简报内容空洞、不准确。可能原因docs/CANONICAL_*.md文件内容过于简略或还未填充。解决brief-me命令的质量完全依赖于输入文档的质量。确保你的Canonical文档已经详细、准确地描述了项目的技术栈、架构决策和代码规范。内容越丰富AI生成的简报就越有价值。primer-cli的本质是将优秀开发者的经验和纪律转化为机器可读、可执行的规范。它不会取代你的思考而是将你从重复的、低层次的规范传达中解放出来让你和你的AI助手能更专注于创造性的问题解决和架构设计。从这个角度看它不只是脚手架更是一个项目级的“认知外挂”。