1. 项目概述一个为AI原生产品经理设计的结构化工作流框架如果你正在用Claude Code、Cursor这类AI编码助手来构建产品那你一定经历过这种循环每次打开一个新对话都得把产品背景、用户画像、技术栈限制从头到尾再解释一遍写好的PRD产品需求文档复制粘贴过去心里却打鼓不知道AI到底理解了多少会不会自作主张地“优化”出一些你根本不想要的功能好不容易功能上线了复盘的经验教训躺在某个文档里下次启动新项目时一切又得从零开始。这种“记忆断片”和“上下文丢失”的感觉是当前AI辅助开发中最磨人的痛点之一。VisNavyVet/PRODMAN简称ProdMan正是为了解决这个问题而生。它不是一个简单的文档模板库而是一个开源的、AI无关的产品管理框架核心目标是为你和你的AI助手建立一个持久化的产品记忆并提供一个从信号捕捉到功能上线的结构化工作流。简单说它让你和AI的协作从“每次都是初次见面”变成“老搭档之间的默契配合”。它的核心价值在于“连接”。你的产品背景、历史决策、用户反馈、技术约束都会被系统地记录在prodman-context/这个目录下。此后无论你使用哪个AI工具Claude、ChatGPT、Cursor等在执行任何ProdMan命令时这份“产品大脑”都会被自动加载。AI不再是那个需要你反复教育的“新人”而是一个对你的产品了如指掌的“资深成员”。更重要的是它输出的核心产物agent-brief.md是一份为AI编码智能体量身定制的、边界清晰、可测试、包含明确“禁止事项”和“升级触发条件”的指令集极大降低了AI过度发挥或误解范围的风险。无论你是独立开发者、技术创始人还是在一个小团队里身兼数职的产品经理只要你正在利用AI智能体进行产品构建ProdMan都能帮你把混乱的构思、零散的信号转化为机器可读、团队可协作、AI可精准执行的标准化产出。2. 核心设计哲学为什么“结构”比“智能”更重要在深入实操之前理解ProdMan背后的设计哲学至关重要。这能帮你明白为什么在AI能力已经如此强大的今天我们还需要这样一个框架。2.1 从“对话式探索”到“结构化产出”的范式转变直接与LLM大语言模型对话进行产品设计模式是发散且线性的。你提出一个想法它给出建议你再追问它再补充。这个过程充满了即兴发挥但缺乏可追溯的决策路径和可复用的产出结构。每次对话都是一次独立的冒险。ProdMan将这个过程工程化了。它将产品从0到1的思考与产出过程划分为五个明确的“区域”Zone每个区域有特定的输入、处理和输出。这就像为产品思维搭建了一条流水线Zone 1 - 具体化处理原始信号用户反馈、数据波动、灵感通过系统性的提问和框架分析将模糊的问题转化为一个可被证伪的、明确的方向承诺commitment.md。Zone 2 - 规划基于承诺一键生成包含agent-brief.md在内的完整需求包共5个文件。Zone 3 - 研究在需要时提供用户访谈、竞品分析等研究工具。Zone 4 - 交付将一份核心需求自动生成面向工程师、设计师、高管等不同受众的定制化文档。Zone 5 - 发布与学习管理上线清单并通过复盘自动更新产品历史记忆。这个结构确保了思考的深度和产出的质量不因执行者的状态或AI会话的偶然性而波动。2.2 “产品记忆”作为第一性原则这是ProdMan区别于所有笔记软件或文档模板的核心。prodman-context/目录下的四个文件product.md,users.md,constraints.md,history.md构成了项目的“长期记忆”。product.md定义产品是什么、核心价值主张、愿景。这是产品的“宪法”。users.md定义用户画像、用户旅程、核心痛点。这是所有需求的“北极星”。constraints.md定义技术栈、性能要求、安全合规、品牌规范等不可妥协的边界。这是创意的“护栏”。history.md通过/pm-retro命令自动记录每次功能迭代的决策逻辑、成功经验和失败教训。这是团队的“集体智慧”。每次执行命令AI都会先“阅读”这些文件。这意味着当你处理第10个功能时AI已经知晓前9个功能中踩过的坑和学到的经验。这种连续性是任何单次对话都无法提供的。2.3 “智能体优先”的输出设计传统PM工具的输出是给人看的。ProdMan的核心输出agent-brief.md首先是给AI编码智能体看的。这份文档的设计遵循六个原则边界清晰、可测试、上下文完整、包含明确“禁止事项”、有清晰的升级触发机制、可重现。举个例子一个模糊的需求是“优化结账流程”。而在agent-brief.md中它会变成范围内为访客用户非登录增加信用卡信息保存选项仅限选择加入。范围外不修改现有已登录用户的结账路径不添加任何商品推荐或加售提示。必须禁止不得创建新的数据库表不得引入第三方支付SDK。升级触发如果支付提供商API返回文档中未定义的错误代码立即停止并通知工程师如果订单总额超过10,000美元欺诈风险停止并上报产品经理。这种级别的精确性极大地约束了AI的发挥空间使其行动高度可控、结果高度可预测真正实现了“人指挥AI”而非“人猜测AI会做什么”。3. 快速上手指南两条核心路径ProdMan的入门极其简单无需安装任何复杂环境。你可以通过两条路径开始它们最终都会导向一个通过了全部12条规则校验、可供AI智能体直接使用的agent-brief.md。3.1 环境准备与初始化无论选择哪条路径第一步都是获取ProdMan并初始化你的产品记忆。# 1. 克隆仓库 git clone https://github.com/VisNavyVet/PRODMAN.git cd PRODMAN # 2. 在你的AI工具中如Claude Code运行初始化命令 /pm-import运行/pm-import后AI会通过一个简短的5个问题的访谈引导你创建prodman-context/目录。问题通常围绕产品名称、核心用户、要解决的首要问题等。这里有一个关键技巧如果你已经有现成的产品说明、用户画像文档可以直接在对话中粘贴进去AI会自动提取关键信息并填充到对应的Markdown文件中跳过重复的问答。初始化只需做一次。完成后你的项目根目录下会生成prodman-context/文件夹里面包含了上述四个核心记忆文件。请花点时间审查并完善它们这是后续所有高质量产出的基石。3.2 路径A从模糊信号开始推荐给探索型项目当你只有一个初步的想法、用户的一句抱怨或一个模糊的数据指标时走这条路径。它通过一系列结构化的对话帮你把“感觉不对劲”变成“明确要做什么”。操作流程与核心对话捕获信号/pm-signal [你的原始信号]例如/pm-signal 我们的移动应用注册流程第二步用户流失率比第一步高了40%。AI的响应模式它不会直接给出解决方案而是会先进行苏格拉底式提问通常每次只问一个最核心的问题。比如“你能否确认这40%的流失用户是卡在了某个具体的表单字段还是在加载页面时直接关闭了应用” 这个阶段的目标是分离“症状”和“根因”。构建问题框架/pm-frame基于上一步的澄清AI会生成2-3个不同的问题框架。例如框架A这是一个用户体验摩擦问题表单太复杂、字段令人困惑。框架B这是一个技术性能问题页面加载慢、有bug。框架C这是一个用户动机问题用户在第二步才意识到产品不符合预期。你的任务不是“选择正确的那一个”而是“对每个框架做出反应”指出哪个更贴近你的直觉哪个可能被忽略。这个过程能有效打破你的思维定势。深度探索/pm-explore选定一个框架后AI会引导你进行六个维度的深度探索受影响用户、根本原因、已尝试方案、成功标准、约束条件、相关方。它会一个维度一个维度地问并在每个维度结束后进行小结确保思考的连贯性。锁定方向/pm-commit经过以上探索AI会帮你总结出一个“可证伪的问题陈述”和明确的“解决范围”与“不解决范围”并写入features/[功能名]/commitment.md。这个文件是Zone 1的成果也是进入Zone 2的钥匙。生成完整需求包/pm-ff [功能名]这是最强大的命令。基于commitment.md一键生成5个文件agent-brief.md给AI智能体的核心指令。prd.md完整的产品需求文档含P0/P1/P2优先级。brief.md一页纸的PM摘要。approach.md决策依据和备选方案。plan.md里程碑和风险计划。生成后VS Code扩展会立即进行 lint 检查状态栏会显示通过情况如PRODMAN ✓ Agent Ready — 12/12 rules passing。3.3 路径B从现有PRD开始快速转化如果你已经用Notion、Linear、Word甚至聊天记录写好了一份需求文档这条路径能在15分钟内将其转化为AI友好的格式。操作流程确保已初始化已完成/pm-import。运行转化命令/pm-agent-brief [功能名]AI会提示你粘贴现有的PRD内容。粘贴后它会开始解析并只针对缺失的关键信息如明确的“禁止事项”、具体的“升级触发条件”进行针对性提问而不是重写整个文档。修复Lint错误命令生成的agent-brief.md会直接在VS Code中打开并伴有ProdMan Linter的实时检查。红色波浪线会提示缺失的必填字段或模糊的表述。实操技巧将光标放在波浪线上使用Ctrl.(或Cmd.) 打开“快速修复”菜单通常可以选择“插入‘升级触发条件’模板”AI会自动生成一个结构化的模板供你填写极大提升效率。验证与使用当状态栏显示所有12条规则都通过时这份agent-brief.md就可以直接复制粘贴给你的AI编码助手如Claude Code、Cursor AI开始开发了。重要提示无论走哪条路/pm-ff生成文件后务必运行prodman validate [功能名]进行最终校验。这是确保你的需求包足够健壮、能有效约束AI行为的最后一道关卡。4. VS Code扩展将质量检查内嵌到工作流中虽然ProdMan的核心是Markdown可以在任何AI工具中使用但其VS Code扩展prodman/vscode将体验提升到了新的高度。它把Spec需求规约的“编写-校验-编译”闭环无缝集成到了编辑器中。4.1 核心功能详解安装扩展后在VS Code扩展商店搜索“ProdMan”当你打开一个包含agent-brief.md的文件或处于ProdMan项目结构中时扩展会被激活。实时语法检查这不仅仅是拼写检查。它基于prodman/core的12条规则对agent-brief.md进行语义级的Lint。例如它会检查acceptance_criteria中的描述是否“可观察、可验证”规则LNT-009会检查escalation_triggers是否具体规则LNT-011。模糊的表述如“性能要好”会被标记为警告而缺失整个must_NOT_do章节则会被标记为错误。状态栏就绪指示器编辑器底部状态栏会持续显示PRODMAN ✓ Agent Ready — 12/12 rules passing或PRODMAN ✗ Incomplete (2 errors)。这让你对当前Spec的“可交付状态”一目了然无需手动运行命令。一键启动智能体这是最流畅的环节。当你修复完所有Lint错误后点击状态栏的“Agent Ready”按钮或使用文件顶部的CodeLens动作▶ Run with PRODMAN扩展会自动执行以下操作运行prodman validate进行最终校验。运行prodman compile将Markdown编译为结构化的compiled-spec.json。将agent-brief.md的内容和compiled-spec.json的路径组装成一个清晰的提示词。自动复制到你的剪贴板。 接下来你只需要切换到Claude Code或Cursor的聊天窗口粘贴AI就获得了一份完整、精确的构建指令。上下文健康与漂移检测扩展的侧边栏提供了一个面板展示prodman-context/下所有文件的状态。更有用的是“漂移检测”它会扫描你的代码库如果发现实际使用的技术栈如从package.json中检测到与constraints.md中记录的不一致会发出警告。这确保了你的产品记忆与代码现实同步。4.2 安装与配置细节# 从VS Code市场安装推荐 code --install-extension prodman.prodman安装后无需复杂配置。扩展在检测到以下任一文件时自动激活项目根目录下的CLAUDE.mdprodman-context/product.md任何features/**/agent-brief.md文件首次打开一个已有代码库但未初始化ProdMan的项目时扩展的“初始化向导”会主动弹出引导你创建prodman-context/并尝试从现有代码中推断技术栈填入constraints.md非常贴心。5. CLI工具与核心库自动化与集成基石ProdMan的魔法不仅在于交互命令更在于其提供的命令行工具和可编程核心库这让它可以融入你的自动化流程和CI/CD管道。5.1 CLI工具的使用场景通过npm全局安装CLI工具后你可以在终端直接操作ProdMan。npm install -g prodman/cli批量验证与质量门禁在团队协作中你可以在Git的pre-commit钩子或CI流水线中运行prodman validate --all检查所有功能需求包的完整性。如果某个功能的agent-brief.md缺少关键字段或AC描述模糊验证会失败从而阻止不完整的Spec被合并到主分支。这是保障团队产出质量的一致性护栏。# 在CI脚本中 if ! prodman validate --all; then echo ERROR: One or more ProdMan specs are incomplete. Please fix before merging. exit 1 fi编译为机器可读合约prodman compile checkout-v2命令会将人类可读的agent-brief.md编译成compiled-spec.json。这个JSON文件结构严格遵循schemas/compiled-spec-schema.json定义的模式可以被其他自动化工具读取。例如你可以写一个脚本自动根据compiled-spec.json中的acceptance_criteria生成对应的测试用例骨架。项目状态概览prodman status命令能以表格形式列出所有功能显示其所属区域Zone、文件完备性和就绪状态非常适合PM做项目进度管理。5.2 核心库的编程化集成对于想深度集成的团队prodman/core这个零依赖的Node.js库提供了所有能力。import { Linter, Compiler } from prodman/core; import fs from fs/promises; // 示例在自定义工具中验证Spec async function validateSpecForFeature(featureName: string) { const linter new Linter(); const briefPath features/${featureName}/agent-brief.md; const result await linter.lintFile(briefPath); if (result.readiness agent-ready) { console.log(✅ ${featureName} 就绪可交付AI。); // 可以触发后续自动化流程如创建GitHub Issue } else { console.log(❌ ${featureName} 未就绪。问题); result.issues.forEach(issue { console.log( - [${issue.code}] ${issue.message} (位于: ${issue.field})); }); } return result; } // 示例编译Spec并用于生成文档 async function compileAndGenerateDocs(featureName: string) { const compiler new Compiler(); const briefPath features/${featureName}/agent-brief.md; const contextDir prodman-context/; const spec await compiler.compile(briefPath, contextDir); // 现在你可以使用结构化的spec对象做任何事 console.log(功能${spec.task_summary}); console.log(范围内事项, spec.in_scope); console.log(验收标准, spec.acceptance_criteria); // 例如生成Confluence页面或Notion数据库条目 // await postToConfluence(spec); }这种可编程性让ProdMan不仅能被人使用还能被其他系统调用成为你AI原生开发流水线中的一个标准组件。6. 团队协作与上下文管理ProdMan天生支持团队协作其设计哲学是“上下文即代码”。6.1 共享产品记忆的两种模式prodman-context/目录就是团队共享的“产品真理之源”。管理它和管理代码一样。模式A共享产品代码库推荐 直接将prodman-context/提交到你的产品主代码库中。这样任何克隆该仓库的团队成员都自动获得了最新的产品记忆。当PM通过/pm-retro更新了history.md或者更新了users.md中的用户画像这些变更通过标准的Git Pull Request流程进行评审和合并确保记忆的演进是透明且受控的。模式B独立的上下文仓库如果公司有多个产品线或者需要对产品战略文档进行更严格的权限控制可以创建一个独立的Git仓库如company-product-a-context专门存放prodman-context/。在每个产品的代码库中通过CLAUDE.md文件或README中的说明指向这个独立仓库的路径。这种方式隔离了代码和产品上下文的变化。6.2 交付-反馈循环的闭环ProdMan设计了一个优雅的反馈机制确保Spec不是单向抛出的“石头”而是可以持续迭代的“活文档”。当PM使用/pm-handoff engineer生成handoff-eng.md并交给工程师后工程师在评审过程中可能会发现模糊点、技术限制或更好的实现方案。这时工程师不是仅仅在聊天工具里回复而是去修改或创建同一个功能目录下的handoff-response.md文件。这个文件有固定的模板用于记录已解答的问题澄清了PM需求中的哪些模糊点。范围变更因技术原因需要增加、减少或调整的需求。发现的依赖或阻碍。技术建议。关键流程当PM后续因需求变更需要重新生成Spec时再次运行/pm-ff [功能名]。AI在生成新的需求包时会自动读取并整合handoff-response.md中的反馈。这意味着工程师的输入被直接“烧录”到了下一代Spec中避免了信息在多次传递中丢失或失真真正实现了跨职能的“记忆共享”。7. 避坑指南与实战心得在实际使用ProdMan几个月后我积累了一些能让你事半功倍的经验和需要警惕的“坑”。7.1 初始化阶段的常见陷阱陷阱一product.md写得太空泛。避免写成“我们是一个提升效率的平台”。要具体像电梯演讲“我们为中小型电商团队提供一个基于AI的客服工单自动分类与回复建议工具核心是减少人工处理时间30%。” 具体的价值主张能让AI在后续所有决策中保持聚焦。陷阱二constraints.md遗漏关键限制。除了技术栈务必包含性能指标如页面加载时间2秒、安全合规要求如GDPR、PCI DSS、设计系统限制如必须使用公司UI组件库V1.2、第三方服务配额如每月API调用上限。这些是AI容易“创造性越界”的地方提前设好围栏。心得初始化时不妨把你现有的所有相关文档产品路线图、技术架构图、用户调研报告都扔给AI让它帮你提炼和总结。/pm-import命令的对话界面非常擅长做信息提取和结构化。7.2 撰写agent-brief.md的核心技巧这是与AI协作成败的关键。很多人在这里写得像给人看的PRD导致AI过度发挥。技巧一“必须禁止”比“必须做”更重要。AI尤其是编码智能体有很强的“完成任务”倾向。如果你只说“建一堵墙”它可能会用砖、木头甚至钢铁。但如果你说“用砖建一堵墙禁止使用木头和钢铁”结果就可控了。在anti_requirements里要极端具体“禁止创建新的数据库表”、“禁止修改src/core/auth.js文件中的任何函数签名”、“禁止引入任何新的npm包”。技巧二升级触发条件要可执行。不要写“遇到问题就问我”。要写“如果用户上传的文件大小超过config.MAX_FILE_SIZE中定义的值停止并记录错误FILE_TOO_LARGE到日志。”“如果调用PaymentService.charge() 返回状态码422且错误信息包含‘insufficient_funds’停止并将订单状态标记为PAYMENT_FAILED通知用户。” 这样AI才知道在什么确切条件下应该“举手”。技巧三验收标准必须是“可观察、可验证”的。避免“用户体验良好”。改为“未登录用户点击‘保存卡片’复选框后应在数据库user_payment_methods表中创建一条is_defaultfalse的记录并在UI上显示‘已保存’提示框2秒后消失。” 这种描述AI在编码后可以自己写一个简单的测试来验证。常见问题Linter报错[LNT-011] Missing escalation triggers。这通常是因为你只写了“如果出错就停止”但没有定义什么是“错”。快速修复是使用VS Code的Quick Fix功能插入模板然后填充像上面例子一样的具体条件。7.3 管理不断增长的prodman-context/随着项目推进history.md会变得很长。全部加载可能会让AI的上下文窗口不堪重负。定期修剪策略每季度或每完成一个大型里程碑后回顾history.md。将过时的、被推翻的决策移至文档末尾的一个“归档”部分或直接移到一个单独的history-archive.md文件中。确保当前加载的history.md主要包含最近6-12个月内的、仍有参考价值的决策和学习。保持核心文件精简product.md和users.md应力求一页纸说清楚。它们是高频引用的“宪法”不是详细的产品手册。细节可以链接到更外部的文档如Confluence。利用signals.md/pm-signal命令捕获的原始信号会汇总到这里。定期回顾这些信号能帮你发现新的问题模式或用户需求甚至可以成为/pm-frame新问题框架的灵感来源。7.4 与不同AI工具的适配心得ProdMan是AI无关的但在不同工具中体验有差异。Claude Code体验最无缝。将ProdMan仓库克隆到本地在Claude Code中打开它就能识别/pm-开头的自定义指令并自动加载claude/commands/下的命令文件。这是官方推荐的工作流。Cursor需要在Cursor中设置“规则”文件并手动触发命令。虽然多一步但Cursor强大的代码理解和编辑能力与ProdMan精确的Spec结合效果惊人。确保在Cursor的Agent模式中将prodman-context/作为上下文提供。ChatGPT/Gemini等Web界面采用“复制-粘贴”工作流。在ProdMan的commands/目录下找到对应命令的Markdown文件将其内容复制到聊天框。虽然不能一键运行但结构化的提问和输出模板依然能极大提升需求讨论的质量。关键是每次都要记得手动附上相关的prodman-context/文件内容。一个通用技巧无论用什么工具在开始一个重要的ProdMan会话前先发一条消息“请根据以下产品上下文来理解和协助我[粘贴product.md和users.md的核心摘要]”。这相当于给AI一个“热身”能显著提升后续对话的针对性。ProdMan不是一个要你全盘接受的新方法论而是一套可以逐步采纳的“增强插件”。你可以先从用它来写最关键的agent-brief.md开始感受AI执行精度提升带来的快感。然后再尝试用它来结构化你的早期问题探索最后再将整个团队的产品记忆沉淀下来。它的价值会在你与AI协作的每一个“啊哈这次它完全理解我了”的时刻不断显现。