1. 项目概述从“氛围编程”到“智能体工程”的范式转变如果你和我一样在过去一年里深度使用过 Claude Code、Cursor 或者 Windsurf 这类 AI 编程助手那你一定经历过这种熟悉的挫败感昨天刚和 AI 花了两个小时敲定的架构决策今天打开新会话它忘得一干二净又得从头解释一遍。代码质量像坐过山车时好时坏完全取决于你当时提示词的状态。项目越做越大你发现自己不是在“构建”而是在“管理”一个健忘的、需要不断被提醒的合作伙伴。这种感觉业内有个戏称叫“氛围编程”——全凭当下的“氛围”和运气来推进。FavioVazquez 的learnship项目就是冲着解决这个核心痛点来的。它不是一个新模型也不是一个花哨的 UI 插件而是一个智能体工程框架。你可以把它理解为你和 AI 编程助手之间的“操作系统”或“脚手架”。它的核心使命是给原本松散、健忘、不可预测的 AI 协作过程注入结构、记忆和意图。简单来说learnship将你的项目从“每次会话都从零开始”的混沌状态升级为一个拥有持久化记忆、标准化流程和知识复利的工程化系统。它通过一套精心设计的命令和工作流将你的项目上下文、技术决策、阶段目标“工程化”地喂给 AI确保每一次交互都建立在前一次工作的坚实基础上。无论你是独立开发者、创业者还是希望用 AI 高效构建原型的产品经理learnship提供的这套方法论和工具链都能显著提升你与 AI 协作的产出质量和可预测性。2. 核心理念与架构拆解为什么“脚手架”比“模型”更重要在深入实操之前我们必须先理解learnship背后的哲学。这决定了你是否能真正用好它而不是仅仅把它当作另一堆命令的集合。2.1 智能体工程 vs. 氛围编程一次根本性的思维升级learnship的宣传材料里有一张对比图非常精辟地概括了这两种模式维度氛围编程智能体工程上下文每次会话重置AI 如同失忆通过AGENTS.md等文件持久化加载会话间记忆连贯决策隐含在对话中极易被遗忘显式记录在DECISIONS.md中并被后续工作流强制执行计划即兴的提示词结果不可预测基于规格说明驱动可验证、按波次排序的执行计划产出一堆能运行的代码你真正理解的、可维护的代码和系统知识这个对比揭示了一个关键事实AI 模型本身无论是 Claude、GPT 还是 Gemini的能力是相对固定的。但模型被调用的方式、接收的上下文、遵循的流程——也就是所谓的“智能体脚手架”——才是决定最终产出质量的最大变量。研究表明同样的模型在不同的脚手架下任务完成率可以有天壤之别。learnship做的就是提供那个经过深思熟虑的、高效的脚手架。2.2 三层架构工作流引擎、学习伙伴与设计系统learnship并非一个单一工具而是三个紧密集成、相互增强的层次工作流引擎这是骨架。它定义了一个从讨论、计划、执行到验证、交付的七步闭环Phase Loop。每一步都有对应的命令如/discuss-phase,/plan-phase,/execute-phase将模糊的需求转化为原子化的、可执行的计划并确保执行结果经过验证。这是对抗项目熵增的核心机制。学习伙伴这是灵魂。这是learnship最独特的部分。它基于认知科学原理检索、反思、间隔重复、合意困难在关键的工作流节点如阶段转换时自动触发学习检查点。它的目的不是让 AI 替你思考而是确保你在构建的过程中真正理解你所构建的东西。例如在执行完一个阶段后它会引导你进行结构化反思“你学到了什么这个阶段的目标是什么还有哪些知识缺口”设计系统这是皮肤。它集成了名为impeccable的 UI 设计指导技能包含 21 个精准的 steering 命令如/audit,/critique,/polish。这确保了 AI 生成的 UI 代码不是那种千篇一律的“AI 味”设计而是符合生产级质量、具有一致性和美感的界面。它把设计原则也工程化了。这三层共同作用使得learnship不仅仅是一个“自动化工具”更是一个“增强认知”的伙伴。它管理过程你专注创造。2.3 上下文工程渐进式披露的艺术传统使用 AI 编程时我们倾向于把所有相关文件一股脑塞进上下文希望模型能自己找到重点。这效率低下且容易导致模型混淆。learnship采用了“上下文工程”策略即渐进式披露。系统会为每一次 AI 调用精心组装一个结构化的上下文包通常包括AGENTS.md项目的“灵魂”文件包含项目原则、当前阶段、技术栈等。REQUIREMENTS.md我们要构建什么。DECISIONS.md所有重要的架构和技术决策。当前阶段的CONTEXT.md仅包含本阶段实现所需的偏好和细节。这样AI 在每一步都只获得完成当前任务最相关、最少且充分的信息极大提高了响应的准确性和一致性。AGENTS.md是这个系统的基石由/new-project命令生成并在每次会话开始时自动加载在支持的平台上从根本上解决了“会话失忆”问题。3. 核心工作流实战手把手构建你的第一个项目理论说再多不如动手做一遍。让我们以一个简单的全栈 Web 应用为例——比如一个“个人书签收藏管理器”——来完整走一遍learnship的核心循环。3.1 初始化/new-project与项目灵魂的诞生一切始于/new-project。这个命令不是简单地创建一个文件夹而是进行一场结构化的“项目诞生访谈”。操作实录在你的 AI 编程助手如 Claude Code中输入/new-project。系统会开始一系列交互式提问项目名称与描述“bookmark-nexus - A full-stack web app for managing and tagging personal bookmarks with AI-powered summaries.”核心用户与问题“For individuals who save many articles/links but struggle to refind them. It solves link rot and forgotten treasures.”技术偏好“I prefer modern JS stack: Next.js 15 (App Router) for frontend, Express.js Prisma PostgreSQL for backend, deployed on Vercel and Railway. Use Tailwind CSS and shadcn/ui for components.”质量与速度权衡“Prioritize clean, maintainable code and good UX. Willing to trade some speed for quality.”学习目标“I want to deepen my understanding of Next.js server actions, Prisma migrations, and implementing a robust tag system.”背后原理与产出这个过程不仅仅是收集信息。learnship会根据你的回答启动一个project-researcher智能体去研究你提到的技术栈的最新实践、常见陷阱和最佳架构。然后它会生成一系列核心文件AGENTS.md你的项目圣经。它定义了项目的“灵魂”如“我们是注重细节的工匠”10条工作原则并记录了上述所有信息。这是解决“AI 失忆症”的关键。REQUIREMENTS.md从用户故事和问题陈述中提炼出的具体功能需求列表。ROADMAP.md一个初步的、分阶段的开发路线图。learnship会根据你设置的granularity粒度配置将大目标拆解成 3-12 个不等的阶段。实操心得在回答技术偏好时尽量具体。说“用 React”不如说“用 Next.js 15 with App Router and React Server Components”。越具体后续 AI 生成的代码和计划就越精准。learnship的roadmapper智能体会根据这些具体信息生成更可行的路线图。3.2 阶段循环从讨论到交付的标准化流程项目初始化后你就进入了learnship的核心——阶段循环。假设我们的ROADMAP.md第一个阶段是“设置项目基础结构与用户认证”。3.2.1 阶段讨论/discuss-phase 1在写任何代码之前先进行“对齐”。输入/discuss-phase 1。AI 会做什么它会读取AGENTS.md和ROADMAP.md中关于阶段 1 的描述然后生成一份详细的讨论草案包括技术选择例如使用 NextAuth.js 还是 Clerk、文件结构、数据库 schema 草图等。你需要做什么审查这份草案与 AI 讨论细节、权衡利弊。比如“我们选择 NextAuth.js因为它与 Next.js 集成度更高且我们的需求不复杂。用户模型需要name,email,image字段。书签模型需要url,title,description,userId和与标签的many-to-many关系。”关键产出所有讨论中达成一致的决策会被自动记录到DECISIONS.md。例如“决策 001认证采用 NextAuth.js v5适配 App Router。” 这个文件将成为后续所有工作的“宪法”AI 必须遵守。3.2.2 阶段计划/plan-phase 1讨论清楚了开始制定作战计划。输入/plan-phase 1。AI 会做什么phase-researcher智能体首先会深入研究 NextAuth.js v5 在 App Router 下的具体配置、Prisma 与 PostgreSQL 的最佳实践。然后planner智能体会生成一份PLAN-PHASE-1.md。计划文件剖析这份计划不是笼统的“实现登录”。它会拆解成一系列原子任务并按依赖关系排序和分组为“波次”。例如波次 1初始化 Next.js 项目安装基础依赖Tailwind, shadcn/ui, Prisma。波次 2配置 PostgreSQL 数据库设置 Prisma schema 和初始迁移。波次 3集成 NextAuth.js配置 GitHub OAuth 提供商创建基础登录页面组件。波次 4创建核心布局组件Header with user avatar和 protected route 示例。计划验证生成计划后plan-checker智能体会自动检查计划的完整性、可行性与DECISIONS.md的一致性并可能提出修改建议。这个过程可能迭代 2-3 轮确保计划是可执行的蓝图。3.2.3 阶段执行/execute-phase 1蓝图在手开始施工。输入/execute-phase 1。顺序执行默认情况下AI 会按波次顺序执行计划。每个波次内的任务可能被拆分为更小的原子提交。例如在波次 2 中它会先创建prisma/schema.prisma文件然后运行npx prisma migrate dev --name init生成 SQL 并应用最后生成 Prisma Client。每个步骤都是一个清晰的、有信息的 Git 提交。并行执行高级在 Claude Code、OpenCode 等支持并行子智能体的平台上你可以在配置中启用parallelization。这样一个波次内没有依赖关系的多个计划可以由不同的 AI 智能体同时执行每个智能体拥有独立的上下文预算大幅提升速度。但请注意并行执行对项目结构和任务拆分的质量要求更高初期建议使用默认的顺序模式。现场记录执行过程中AI 会输出它正在做什么、运行了什么命令、创建了什么文件。你会看到一个高度结构化的、自动化的开发过程在眼前展开。3.2.4 工作验证/verify-work 1代码写完了但它符合预期吗输入/verify-work 1。手动验收测试learnship会引导你进行手动测试。它会列出阶段 1 的目标并问你“请打开http://localhost:3000尝试用 GitHub 账号登录。登录后检查页面右上角是否显示你的头像和用户名。然后访问/dashboard确认未登录用户会被重定向。”自动诊断如果你在测试中发现了问题比如登录后头像不显示不要直接告诉 AI“修复它”。而是描述现象。learnship的verifier智能体会根据你的描述自动分析代码、诊断根本原因可能是session回调配置错误并生成一个详细的“修复计划”。你批准后它会自动执行这个修复计划。UAT 驱动这个流程确保了交付物是经过真实用户你验收的而不是 AI 自说自话完成的。3.2.5 后续步骤/review,/ship,/compound阶段 1 验证通过后你可以选择进入更高级的工作流/review启动一个多角色代码审查。learnship会模拟资深工程师、安全专家、新手开发者等不同视角对你的代码进行审查提出可读性、性能、安全性等方面的改进建议。/ship一键化交付流水线。它会运行测试如果配置了、代码检查、创建符合 Conventional Commits 规范的提交信息、推送到远程仓库并生成 Pull Request 描述草稿。/compound知识复利。这是learnship的精华。在解决了一个棘手问题比如调试了一个奇怪的 NextAuth 回调错误后运行此命令。它会引导你结构化地记录问题是什么、根本原因、解决方案、以及学到的通用模式。这些知识会被写入docs/目录并变得可搜索。当下次遇到类似问题时AI 可以直接从你的知识库中检索解决方案而不是重新发明轮子。3.3 导航与快捷命令高效协作的秘诀在整个过程中你不需要记住所有 57 个命令。只需要记住 5 个核心命令/ls(列表状态)每次开始会话时首先使用。它会告诉你项目当前处于哪个阶段、最近做了什么、接下来应该做什么并且通常会直接提供一个按钮让你执行下一步。它是你的指挥中心。/next(下一步)当你信任系统只想埋头干活时就用它。它会读取项目状态自动判断并执行最合适的下一个工作流例如自动进入discuss-phase 2。/new-project(新项目)项目起点。/quick “...”(快速任务)用于那些不需要完整阶段循环的小任务比如修复一个明显的 bug、添加一个简单的工具函数。它会自动进行原子提交但跳过前期的规划和讨论仪式。/help(帮助)查看所有可用命令的索引。注意事项/ls是新用户和老用户的最佳入口。对于新项目它会介绍learnship并建议开始/new-project。对于进行中的项目它是你找回上下文、明确方向的最快方式。养成每次打开编辑器先打/ls的习惯。4. 平台适配与高级配置详解learnship支持主流 AI 编程环境但各平台能力不同体验也有差异。理解这些差异能帮你选择最适合的工具链。4.1 平台特性矩阵与选型建议特性WindsurfClaude CodeCursorOpenCodeGemini CLICodex CLI原生斜杠命令✓ (最佳体验)✓✓ (需learnship)✓✓$skills形式并行子智能体—✓ (核心优势)—✓✓✓会话钩子—✓ (状态行、上下文监控)——✓—技能原生调用✓ (agentic-learning)需上下文文件引用需上下文文件引用需上下文文件引用需上下文文件引用需上下文文件引用安装方式npx learnship --windsurfnpx learnship --claude应用市场/add-pluginnpx learnship --opencodenpx learnship --gemininpx learnship --codex选型指南追求最强自动化与并行能力首选Claude Code。它的Task()子智能体 API 是learnship并行执行功能的绝配能真正实现多任务同时推进适合大型复杂项目。追求最佳集成与用户体验选Windsurf。它的技能系统与learnship的agentic-learning和impeccable原生集成调用最流畅体验最统一。希望无终端安装Cursor通过应用市场安装最方便适合不喜欢命令行的用户。研究和实验OpenCode和Gemini CLI提供了更多开源和可定制空间。4.2 核心配置解析定制你的工作流项目配置位于.planning/config.json通过/settings命令可以交互式修改。几个关键配置项决定了你的开发节奏1. 模式与粒度 (modegranularity):mode: “auto”系统自动推进无需确认。适合你完全信任计划时。mode: “interactive”在每个关键决策点如执行计划前请求确认。适合需要高控制力的场景。granularity: “coarse/standard/fine”控制ROADMAP.md中阶段的粗细程度。“粗糙”可能只分 3 个阶段适合原型“精细”可能分 12 个阶段适合复杂生产特性。2. 模型配置档 (model_profile):这个设置非常实用它根据任务重要性动态分配不同的 AI 模型“档位”在成本和质量间取得平衡。quality档将最重要的任务如规划、核心代码审查分配给平台可用的最强模型如 Claude Opus。balanced档默认混合使用中大型模型在大多数任务上取得良好性价比。budget档尽可能使用小型高效模型适合原型探索或预算敏感时期。 你不需要手动切换模型learnship根据配置自动分配。3. 并行化配置 (parallelization):parallelization: { enabled: false, plan_level: true, max_concurrent_agents: 5, min_plans_for_parallel: 2 }enabled总开关。警告仅在 Claude Code、OpenCode、Gemini CLI 上有效且要求你的项目任务拆解清晰、依赖关系明确。初期建议关闭。plan_level在“计划”层面并行。例如一个阶段有 5 个独立的数据模型创建计划可以同时执行。max_concurrent_agents限制同时运行的子智能体数量控制资源消耗。4. 学习模式 (learning_mode):auto在阶段转换等关键节点自动弹出学习检查点如“花 2 分钟反思一下这个阶段”。这是将学习内建于开发流程的推荐方式。manual仅在您显式调用agentic-learning技能时触发学习活动。4.3 预设场景配置模板你可以根据项目阶段快速切换配置预设快速原型模式 (.planning/config.json):{ mode: auto, granularity: coarse, model_profile: budget, workflow: { research: false, plan_check: false, verifier: false } }解释关闭研究和深度验证使用廉价模型快速产出可运行的概念验证。生产开发模式 (.planning/config.json):{ mode: interactive, granularity: fine, model_profile: quality, workflow: { research: true, plan_check: true, verifier: true, review: true, security_enforcement: true }, test_first: true }解释开启所有质量关卡使用最强模型采用测试驱动开发每个决策都需确认追求最高代码质量。5. 进阶技巧、问题排查与生态整合当你熟悉基础循环后这些进阶功能和技巧能让你如虎添翼。5.1 高效使用“学习伙伴”技能agentic-learning技能是learnship区别于其他自动化工具的灵魂。它不是帮你写代码而是帮你成为更好的构建者。agentic-learning struggle “如何设计一个支持嵌套标签的书签系统”不要直接问答案。使用struggle命令。AI 会像一个优秀的教练先给你一个提示让你自己思考。如果你卡住了再请求下一个提示。这个过程强制你进行深度思考记忆和理解远比直接得到答案深刻。agentic-learning space在完成一个包含新概念如“Prisma 中间件”的阶段后运行。AI 会根据艾宾浩斯遗忘曲线为你生成一个docs/revisit.md文件规划在未来几天、几周后回顾这些概念的提示。这是对抗知识遗忘的利器。agentic-learning reflect在每个execute-phase结束后运行。它会问你三个结构化问题1) 你实际学到了什么2) 这个阶段最初的目标是什么3) 你现在意识到还有哪些知识缺口这个过程将隐性的、零散的经验转化为显性的、结构化的知识。实操心得不要把学习技能当作负担。把它看作开发流程中的“强制休息点”和“知识存档点”。每天花在reflect和space上的 5-10 分钟长期来看会极大提升你的技术成长速度和项目掌控力。5.2 常见问题与排查实录即使有完善的框架实操中也会遇到问题。以下是我踩过的一些坑和解决方案问题 1/execute-phase卡住或执行了错误操作。排查首先检查PLAN-PHASE-N.md文件。计划是否足够原子化某个步骤的指令是否模糊例如“配置数据库” vs “在.env中添加DATABASE_URL然后运行npx prisma db push”解决运行/execute-plan N [plan-id]重新执行单个失败的计划。如果计划本身有问题回到/discuss-phase N澄清细节然后重新运行/plan-phase N生成更精确的计划。教训在discuss阶段越细致plan和execute阶段就越顺畅。问题 2AI 似乎忽略了DECISIONS.md中的早期决策。排查检查AGENTS.md顶部是否正常加载。在某些平台非 Windsurf/Cursor上可能需要确保工作流正确引用了./AGENTS.md。检查DECISIONS.md文件的格式是否规范。解决运行/health命令进行项目健康检查它会扫描缺失或格式错误的工件。也可以手动在提示中强调“请严格遵守DECISIONS.md文件中的决策 #001 和 #002。”问题 3并行执行时出现上下文污染或冲突。现象两个并行的子智能体修改了同一个文件的同一部分导致合并冲突或逻辑错误。解决这是并行执行的高级风险。预防胜于治疗在discuss和plan阶段确保任务拆分的边界清晰职责不重叠。如果发生了使用/undo命令安全回滚然后调整计划可能将冲突的任务合并到同一个序列中执行。对于高度耦合的模块关闭并行化是更安全的选择。问题 4/verify-work时我描述的问题 AI 诊断不准。策略提供更精确、可观测的现象。不要说“登录不行”而要说“点击 GitHub 登录按钮后页面跳转至http://localhost:3000/api/auth/error?errorConfiguration控制台网络选项卡显示对/api/auth/providers的请求返回 500 状态码”。提供错误信息、日志、截图能极大提升诊断准确性。5.3 与现有开发流程整合learnship不是要取代你的 Git、测试或部署流程而是增强它们。Git 策略在.planning/config.json中配置git.branching_strategy。none所有提交都在主分支。适合单人快速项目。phase每个execute-phase创建一个特性分支如phase-1-auth适合进行每阶段的代码审查。milestone每个里程碑创建一个分支适合版本发布流程。CI/CD 集成/ship命令可以配置为在推送前运行测试 (ship.auto_test: true)。你可以将.planning/目录也纳入版本控制这样 CI 系统也能了解项目结构和阶段目标。/compound生成的知识文档 (docs/) 也应被提交作为项目活文档。团队协作/transition命令可以生成一份完整的项目交接文档包含当前状态、决策日志、待办事项和知识库链接。这对于向团队成员交接项目或自己隔了一段时间后重新上手 invaluable无比珍贵。5.4 设计系统impeccable的实战应用当你的项目涉及 UI 时impeccable技能是你的秘密武器。它内置于learnship的上下文中。项目初始化后立即运行/teach-impeccable。它会通过一系列问题了解你的品牌色、字体、间距系统、设计理念如“极简主义”、“大胆生动”并生成一个持久的.planning/impeccable-guidelines.md文件。每个 UI 开发阶段开始前在discuss-phase中可以加入指令“请遵循我们的 impeccable 设计指南。”UI 组件完成后运行/audit进行全面的无障碍访问、性能和主题一致性审查。运行/polish进行最后的像素级调整。当 UI 感觉“平淡”时运行/delight或/animateAI 会建议添加一些微交互或令人愉悦的细节提升用户体验。这个设计系统能有效防止 AI 生成那种具有“通用 AI 审美”的、缺乏个性的界面确保你的产品拥有独特且一致的设计语言。回顾这整个旅程learnship带给我的最大改变是让我从与 AI 的“对话式编程”进入了“协作式工程”的心流状态。我不再需要反复陈述背景不再担心它忘记昨天的约定。项目有了记忆过程有了节奏知识得以沉淀。它就像为你的 AI 伙伴配备了一个超级外脑和一套严谨的工作手册。最初的学习曲线是存在的你需要适应这种结构化的思维方式但一旦你习惯了用/ls开始一天用/compound结束一个难题你就会发现你不仅在构建软件更在系统性地构建你自己的理解和能力。这或许才是智能体时代开发者最需要掌握的新技能。