1. Primer项目概述：用AI代理构建真实软件的“脚手架”
如果你和我一样，尝试过让AI编码助手（比如Claude Code、Cursor、Codex）去构建一个完整的项目，大概率会遇到一个共同的困境：任务描述太模糊，AI要么卡住，要么跑偏，最后产出一堆无法运行的代码片段，或者过早地实现了未来的功能，导致项目结构混乱。这种体验就像让一个新手厨师直接去准备一场十道菜的晚宴，却没有给他食谱和步骤清单——结果可想而知。
Primer的出现，就是为了解决这个核心痛点。它不是一个替代AI的工具，而是一个AI代理的工作流框架。你可以把它想象成一个经验丰富的项目导师，它把一个大而模糊的构建任务（比如“构建一个操作系统”）拆解成一系列经过验证的、清晰的“里程碑合约”。每个合约都定义了明确的范围、验收标准和下一步行动。你的AI代理只需要专注于完成当前这一个里程碑，然后由Primer来验证是否达标，达标后才能解锁下一个。这样一来，AI的“创造力”就被引导到了一个可控、可验证的轨道上，大大提升了用AI构建复杂、真实软件的成功率和学习效率。
简单来说，Primer让你和AI的协作从“开放式探索”变成了“有指导的实验室”。它特别适合三类人：学习者（想要通过动手项目系统学习）、构建者（希望用AI高效、可靠地构建原型或产品）以及教育者/内容创作者（希望设计可复用的、基于里程碑的学习路径）。无论你是想从零开始学习Python CLI开发，还是挑战构建一个操作系统内核，Primer都能提供一个结构化的“脚手架”，让你和你的AI伙伴一步一个脚印地前进。
2. Primer核心工作流与设计哲学拆解
2.1 两层架构：CLI设置层与AI工作层
Primer的设计非常清晰地区分了“准备”和“执行”两个阶段，这对应着它的两层架构。
第一层是设置层，由primer命令行工具（CLI）负责。这是你主要在终端里操作的环节。它的核心职责是：
- 初始化工作区：使用
primer init命令，选择一个“配方”（如cli-tool），并指定你的AI工具（如codex），Primer会在你指定的路径下生成一个独立的工作区。这个工作区包含了项目骨架、Primer的状态文件，以及为你的AI工具定制的指令文件（如AGENTS.md）。 - 环境诊断：使用
primer doctor命令，检查你的本地开发环境是否满足当前里程碑所需的所有前提条件（如Python版本、特定库、编译工具链等）。这能提前暴露环境问题，避免AI在错误的基础上白费功夫。 - 工作流管理：提供一些底层工具，如切换引导模式（
track）、生成Shell自动补全（completions）等。
注意：一个关键的设计原则是，不要在Primer的源代码仓库里进行构建。
primer init命令的目的就是为你创建一个干净的、独立的工作区。这保证了每个项目环境的隔离性，也避免了污染Primer自身的代码。
第二层是工作层，发生在你的AI编码代理内部。这是你花费大部分时间的地方。Primer在初始化的工作区中，为你的AI工具生成了特定的“技能”或“命令”。例如，对于Codex，它会在.agents/skills/目录下生成primer-build、primer-verify等技能。你只需要在AI代理的聊天界面或命令面板中调用这些生成的命令即可。
这种设计的精妙之处在于，它让AI代理成为了工作的“主界面”，而Primer CLI则退居幕后，成为可靠的基础设施。你不需要记忆复杂的CLI命令参数，AI代理已经通过生成的指令“理解”了Primer的工作流。
2.2 “里程碑合约”与验证驱动的工作流
这是Primer的灵魂。传统的AI编码提示往往是：“帮我写一个任务追踪CLI”。这个提示太宽泛，AI可能会一次性生成整个项目，但其中可能夹杂着错误的设计、未实现的依赖，或者干脆无法运行。
Primer将这个过程重构为一个循环：
- 加载合约：通过
primer-build（或在AI代理中调用对应命令），获取当前里程碑的详细“合约”。这份合约会精确描述本阶段需要实现的功能范围、输入输出示例、以及相关的代码文件。例如，第一个里程碑可能只是“创建一个能响应--help参数并打印使用说明的Python脚本入口点”。 - 专注构建：你和你的AI代理基于这份清晰的合约进行编码。因为范围明确，AI不容易跑偏，你也更容易理解每一步在构建什么。
- 运行验证：通过
primer-verify执行验证。验证不是简单的“代码能跑”，而是一套针对该里程碑的自动化测试。它可能检查文件结构、运行特定的单元测试、验证命令行输出是否符合预期等。 - 安全推进：只有验证通过后，你才能使用
primer-next-milestone解锁下一个里程碑。如果验证失败，Primer会给出明确的失败信息（比如哪个测试用例没通过），你和AI可以基于此进行调试和修正，然后重新验证。
这个“构建-验证-推进”的循环，强制引入了“完成”的定义。它模拟了真实软件开发中的“测试驱动开发”（TDD）和“持续集成”（CI）理念，让AI辅助开发变得可预测、可管理。
2.3 “学习者”与“构建者”双轨道模式
Primer体贴地考虑到了不同用户的需求差异，提供了两种交互风格，称为“轨道”。
- 学习者轨道：这是默认模式，也是对新用户最友好的模式。在此模式下，AI代理在提供实现代码的同时，会附带更多的解释、教学性评论和上下文说明。它会在关键节点暂停，让你理解“为什么这么做”。这就像有一位耐心的导师在旁边，一边带你做，一边讲解原理。非常适合学生、编程新手或第一次接触某个领域项目的人。
- 构建者轨道：此模式下，AI代理的输出会更加简洁、直接，专注于生成实现代码，减少教学性叙述。它假设你已经熟悉Primer的工作流和项目的基本概念，只想高效地推进构建。适合有经验的开发者或已经走过一遍“学习者”轨道，想快速复现项目的人。
你可以在初始化时通过--track learner或--track builder指定，也可以在项目中途使用primer track命令随时切换，无需重新初始化。这种灵活性让Primer能适应从学习到生产的全过程。
3. 从零开始：手把手搭建你的第一个Primer项目
理论说得再多，不如亲手实践。让我们以最经典的cli-tool配方为例，完整走一遍流程。这个项目是用Python构建一个实用的任务追踪命令行工具。
3.1 环境准备与Primer安装
首先，你需要安装Primer CLI。根据你的操作系统选择最方便的方式。以macOS/Linux为例，最快捷的方式是使用安装脚本：
curl -sSf https://raw.githubusercontent.com/armgabrielyan/primer/main/install.sh | sh安装完成后，在终端运行primer --help，如果能看到命令列表，说明安装成功。同时，也建议安装Shell自动补全，能极大提升CLI使用效率：
# 根据你的Shell选择，例如zsh primer completions zsh > ~/.zsh_completions/_primer # 然后将 `source ~/.zsh_completions/_primer` 添加到你的 ~/.zshrc 文件中，或根据你的Shell配置方式加载。实操心得：虽然Primer强调工作主要在AI代理内进行，但一个配置良好的本地CLI环境是基础。确保
primer命令在终端全局可用（即在PATH中）。如果你遇到“command not found”错误，可能需要手动将安装目录（如~/.local/bin）添加到你的PATH环境变量中。
3.2 初始化工作区并选择AI工具
假设我们使用Codex作为AI编码代理。我们为cli-tool项目创建一个独立的工作区：
primer init cli-tool --tool codex --track learner --path ~/projects/my-task-cli这条命令做了以下几件事：
- 识别配方：找到
cli-tool这个配方。 - 生成工作区：在
~/projects/my-task-cli目录下创建所有必要的文件。 - 适配AI工具：因为指定了
--tool codex，它会生成AGENTS.md文件和.agents/skills/目录，里面包含了Codex能识别的Primer工作流技能。 - 设置轨道：
--track learner将初始交互模式设置为学习者模式。
完成后，进入该目录：
cd ~/projects/my-task-cli现在，用你的代码编辑器或IDE打开这个目录。关键一步：你需要在你使用的AI编码代理（如Codex的Web界面或集成IDE）中，打开或切换到~/projects/my-task-cli这个工作区，而不是Primer的源码仓库。
3.3 运行环境诊断
在开始编码前，先进行环境诊断是个好习惯：
primer doctor cli-tool --milestone 01-bootstrap这个命令会检查运行第一个里程碑（01-bootstrap）所需的所有条件，比如Python解释器是否存在、版本是否满足要求、必要的包管理器是否可用等。如果一切显示为绿色或“OK”，你就可以放心地开始了。如果报错，它会明确指出缺失什么，你需要先解决这些环境问题。
3.4 在AI代理中启动Primer工作流
现在，在你的AI编码代理（Codex）中，你应该能看到Primer生成的特殊指令或技能。通常，你可以在聊天框或命令面板中直接调用它们。
- 查看状态：首先，调用
primer-status（或相应的AI技能）。这会显示当前项目信息：配方名称、当前里程碑（应该是01-bootstrap）、验证状态（未验证）、以及进度概览。这让你对所处位置一目了然。 - 理解任务：调用
primer-explain。在“学习者”轨道下，这会给出当前里程碑的详细教学解释：这个里程碑的目标是什么、在整体项目中的位置、涉及的核心概念等。花时间阅读这部分，能帮你更好地理解后续的代码。 - 开始构建：调用
primer-build。此时，AI代理会接收到一份具体的“里程碑合约”。对于01-bootstrap，合约可能要求：创建一个名为taskcli的Python包入口文件（__main__.py），使其能够响应--help和--version参数，并打印出预设的帮助文本和版本号。AI会根据这份合约生成或指导你编写相应的代码。 - 运行验证：编写完代码后，调用
primer-verify。Primer会在后台运行针对该里程碑的验证脚本。这可能包括：检查taskcli文件是否存在且可执行，运行它并捕获--help的输出，与预期字符串进行比对。如果验证通过，终端会显示成功信息，并且里程碑状态会更新为“已验证”。 - 推进到下个里程碑：验证通过后，调用
primer-next-milestone。这会安全地将工作流状态切换到下一个里程碑（例如02-add-task）。然后，重复primer-build->primer-verify的循环。
核心技巧：在整个过程中，尽量使用AI代理界面提供的Primer技能按钮或命令，而不是回到终端手动输入
primer build等CLI命令。这样能保证AI代理始终拥有完整的上下文，理解你正在进行的步骤，从而提供更精准的帮助。CLI命令更多用于初始设置和全局管理。
4. 深入核心：配方、工作流与高级用法
4.1 理解“配方”与现有项目选择
Primer的强大之处在于其“配方”系统。配方是一个预定义的项目蓝图，包含了完整的里程碑序列、验证逻辑和教学材料。目前官方提供了三个配方，难度递增：
| 配方ID | 项目描述 | 难度 | 适用人群与建议 |
|---|---|---|---|
cli-tool | 构建一个任务追踪CLI工具 | 初学者 | Primer和AI辅助开发新手的绝对首选。通过构建一个实用的命令行工具，学习Python、参数解析、文件IO等基础，并完整体验Primer工作流。 |
interpreter-mini | 构建一个小型表达式解释器 | 中级 | 完成cli-tool后的自然进阶。涉及更抽象的概念，如词法分析、语法解析、抽象语法树（AST）和求值，是学习编译原理基础的绝佳实践。 |
operating-system | 构建一个x86操作系统（从引导程序到Shell） | 高级 | 面向有相当经验的开发者或勇敢的学习者。涉及低层编程、硬件交互、内存管理。务必使用--track learner，并把它当作一个长期的、指导性的实验室项目，而非快速教程。 |
选择配方的建议很直接：从cli-tool开始。它不仅教你使用Primer，更重要的是建立“用AI一步步构建可运行软件”的信心和模式。成功完成它之后，你会对是否挑战更复杂的项目有更清晰的判断。
4.2 AI工具集成深度解析
Primer目前原生支持多款主流AI编码代理，并为它们生成量身定制的集成文件：
| AI工具 | 生成的关键文件 | 集成原理 |
|---|---|---|
| Claude Code | CLAUDE.md,.claude/commands/ | Claude Code可以读取工作区根目录的CLAUDE.md作为项目说明，并加载.claude/commands/下的自定义命令。Primer将工作流技能注册为这些命令。 |
| Codex | AGENTS.md,.agents/skills/ | 类似Claude Code，Codex通过AGENTS.md了解项目，并通过.agents/skills/目录下的技能定义来调用Primer CLI。 |
| OpenCode | AGENTS.md,.opencode/skills/ | 机制与Codex兼容。 |
| Gemini CLI | GEMINI.md,.gemini/skills/ | 为Google的Gemini CLI工具生成对应的配置和技能。 |
| Cursor | AGENTS.md,.cursor/skills/ | Cursor IDE内置的AI代理可以识别这些文件，将Primer技能集成到其命令面板中。 |
如果你的AI工具不在上述列表怎么办？Primer的设计是开放的。只要你的AI工具能够：
- 读取工作区中的说明文档（如
README.md或自定义的.md文件）。 - 执行工作区内的Shell命令或调用本地CLI。 那么，你完全可以手动适配。你可以参考已有适配器的生成逻辑，为你使用的工具创建类似的指令文件，告诉AI如何调用
primer build、primer verify等命令。Primer CLI本身是工具无关的。
4.3 针对已有代码库的“棕地”工作流
Primer不仅适用于从零开始的“绿地”项目，其“工作流”功能更是为改造现有代码库（“棕地”项目）而设计的强大特性。假设你有一个庞大的单体应用，想用AI辅助重构其中的认证模块。
- 分析代码库：在现有代码库的根目录下，运行
primer workstream analyze --goal "重构用户认证模块，使其支持OAuth 2.0"。Primer会分析代码结构，识别出与认证相关的文件边界，并建议几个安全的、可作为第一个里程碑的代码范围。 - 创建工作流：根据分析结果，初始化一个工作流：
primer workstream init auth-oauth-refactor --goal "重构用户认证模块，使其支持OAuth 2.0" --tool claude --track learner。这会在代码库的.primer/workstreams/auth-oauth-refactor/目录下创建配置，并生成AI工具适配文件。 - 切换与工作：使用
primer workstream switch auth-oauth-refactor激活这个工作流。现在，当你在这个代码库中打开AI代理，它看到的就是针对“认证重构”这个特定目标的Primer工作流。你可以像在新项目里一样，使用primer-build来获取针对现有代码的第一个重构里程碑（例如“提取出独立的认证服务接口”），然后逐步推进。 - 管理多个工作流：你可以用
primer workstream list查看当前仓库中的所有工作流及其状态。这意味着你可以在同一个代码库中并行管理多个独立的AI辅助重构或特性开发任务，彼此隔离，互不干扰。
这个功能将Primer从一个“项目构建工具”升级为了一个“AI辅助的代码库演进平台”，对于在真实企业环境中引入AI辅助开发极具价值。
5. 实战避坑指南与高级技巧
5.1 常见问题与排查实录
即使有了清晰的指引，实践中仍会遇到问题。以下是我在多次使用中总结的常见“坑”及解决方法：
问题1：AI代理无法识别或执行Primer技能。
- 症状：在AI界面输入
primer-status等命令无反应，或AI表示不理解。 - 排查：
- 确认工作区：你是否在
primer init生成的项目工作区（如~/projects/my-task-cli）中打开了AI代理？最常见的原因是在Primer的源码仓库或其它目录中操作。 - 检查生成文件：查看工作区根目录下是否存在对应的说明文件（如
AGENTS.mdfor Codex）和技能目录（如.agents/skills/）。如果缺失，可能是primer init命令执行不完整或指定了错误的--tool参数。 - AI工具配置：某些AI工具可能需要手动刷新或重新加载工作区才能识别新的技能文件。尝试重启AI代理的会话或重新打开工作区。
- 确认工作区：你是否在
问题2：primer verify验证失败，但代码看起来没问题。
- 症状：验证脚本报错，错误信息可能比较晦涩。
- 排查：
- 仔细阅读错误输出：Primer的验证错误通常会指出是哪个检查项失败了，例如“Expected output ‘Usage:’ but got ‘usage:’”。注意大小写、空格、标点等细节。
- 本地手动运行测试：进入工作区，尝试手动运行验证脚本可能调用的命令。例如，对于CLI工具，直接运行
python -m taskcli --help看看输出是什么。 - 检查环境一致性：确保AI代理运行的代码环境（如Python解释器路径、已安装的包）与你在终端中手动测试的环境一致。有时IDE的虚拟环境与系统环境不同。
- 查看里程碑合约：再次运行
primer-explain或仔细阅读primer-build给出的合约，确认你是否完全理解了需求。有时需求包含隐藏的边界条件。
问题3：想回退到之前的里程碑或修改已验证的代码。
- 症状：验证通过后，发现代码有bug或想优化，但Primer已进入下一个里程碑。
- 解决：Primer的工作流状态是持久化的，但它不管理你的代码版本！这是故意为之的设计。Primer只关心“里程碑合约是否被满足”。因此：
- 版本控制是你的朋友：在开始项目前，务必用Git初始化工作区（
git init）。在每个里程碑验证通过后，进行一次提交（git commit -m "Milestone X verified"）。这样，你可以随时用git checkout回退到任何历史状态。 - 重新验证：如果你修改了已验证里程碑的代码，可以随时再次运行
primer-verify。如果修改导致验证失败，状态会变回“未验证”，你需要修复直到通过。
- 版本控制是你的朋友：在开始项目前，务必用Git初始化工作区（
5.2 提升效率的高级技巧与心得
- 善用
primer doctor：不仅在项目开始时使用，在切换里程碑后，如果新里程碑需要新的工具（如从Python CLI切换到需要nasm汇编器的OS项目），再次运行doctor可以提前发现环境缺口。 - 结合
primer-explain深入学习：在“学习者”轨道下，不要急于跳过解释。这些解释往往包含了重要的设计思路、编程范式或领域知识。把它们当作迷你教程来阅读，能让你从“照猫画虎”上升到“理解原理”。 - 利用JSON输出进行自动化：Primer的CLI命令大多支持
--json标志，输出机器可读的JSON格式。这对于想集成Primer到自定义脚本、仪表板或CI/CD流水线中非常有用。例如，你可以写一个简单的脚本，定期运行primer status --json并解析进度，生成项目报告。 - 为复杂项目创建检查点：对于像
operating-system这样的高级项目，一个里程碑可能就需要数小时甚至更久。建议在完成每个里程碑的验证后，不仅提交代码，还可以在项目笔记中记录下关键的学习点、遇到的难点和解决方案。这能帮你形成持久的知识积累。 - 不要害怕“失败”的验证：验证失败是学习过程的一部分。Primer的验证机制就像一个严格的代码审查员。仔细分析失败原因，与AI代理讨论，是加深对问题理解的最佳时机。这比一次性得到“正确”但你不理解的代码更有价值。
5.3 自定义与贡献：超越使用者
当你熟练使用Primer后，你可能会想：“我能为自己常用的技术栈（比如用Go构建Web服务，或用Rust写解析器）创建配方吗？”答案是肯定的，这也是Primer生态发展的核心。
创建自定义配方：Primer的配方本质上是一个遵循特定结构的目录，包含recipe.toml（配方元数据）、milestones/目录（每个里程碑的合约和验证脚本）、以及可选的guides/（教学材料）。官方文档（docs/community-recipes.md）提供了详细的指南。你可以从复刻一个现有配方（如cli-tool）开始修改，逐步构建自己的学习路径。
贡献的价值：将你创建的精良配方贡献给社区，可以帮助无数有相同学习需求的人。Primer的愿景正是成为一个由社区驱动的、覆盖各种技术和难度级别的“引导式实验室”库。你的贡献可能是一份关于“用React和TypeScript构建现代仪表盘”的配方，也可能是“深入理解Kubernetes Operator”的实践路径。
从我个人的使用体验来看，Primer最大的价值在于它提供了一种范式。它教会你和AI如何有效地协作，将模糊的想法转化为可验证的、递增的成果。无论你是用它来学习、构建原型，还是探索如何将AI规模化地融入开发流程，Primer都提供了一个坚实且可扩展的起点。记住，最重要的不是急于完成所有里程碑，而是在这个结构化的循环中，真正理解每一步在做什么，以及为什么这样做。这才是“用AI构建真实软件”的核心能力。
