1. 先搞清楚 pdlc-skills 到底解决什么问题
pdlc-skills 这个名字拆开看就很直白：PDLC 是 Product Development Life Cycle（产品开发生命周期）的缩写，skills 指的是一套可复用的技能模块。合在一起，它想做的事情就是——把产品从需求到上线的整条链路，拆成一个个可以被智能体（Agent）执行的标准化动作。
我最早接触这套东西的时候，第一反应是"又是一个流程模板"。但真正把它塞进一个正在跑的真实项目之后，我发现它跟传统的 PRD 模板、TDD 模板有本质区别：传统模板是给人看的文档格式，pdlc-skills 是给智能体看的执行指令。这个区别决定了你用它的时候，思路得换一换。
具体来说，它覆盖的核心环节包括：
- 需求发现与 PRD 生成：从零散的想法、前端原型、甚至已有的页面交互中，反向推导出结构化的产品需求文档
- TDD 任务拆解：把 PRD 里的功能点拆成可测试、可验证的开发任务，每个任务都有明确的输入输出和验收标准
- 代码实现与 Git 工作流：智能体根据任务描述生成代码，并通过 Git 分支管理、commit 规范来保证可追溯
- 验证与迭代：跑测试、对比预期、修正偏差，形成闭环
适合谁来用？我的判断是三类人：一是手里有前端工程但缺 PRD 的独立开发者，二是想用 Claude Code 这类工具提效但不知道怎么组织工作流的小团队，三是已经在用智能体写代码但总觉得"差点意思"的工程师。如果你属于这三类，下面的内容应该能帮你省不少试错时间。
2. 把 pdlc-skills 落到真实项目的整体设计思路
2.1 为什么不能直接照搬模板
很多人拿到 pdlc-skills 的第一反应是把它当成一个"填空模板"，把项目信息往里塞就完事了。我试过，效果很差。原因是真实项目的上下文远比模板复杂：你可能有遗留代码、有正在跑的线上服务、有不能动的数据库结构、有产品经理口头提的模糊需求。
所以我的做法是：把 pdlc-skills 当成一套"约束框架"，而不是"填充模板"。框架的作用是告诉智能体"你现在处于哪个阶段、这个阶段的输入是什么、输出应该长什么样、什么情况下算完成"。至于具体内容，得从你的真实项目里提取。
举个例子，PRD 生成这个环节，模板可能会要求你填"用户故事""验收标准""优先级"。但在真实项目里，你得先让智能体读你现有的前端代码，理解页面之间的跳转关系、表单字段、按钮的交互逻辑，然后才能写出靠谱的 PRD。这一步如果跳过，生成的 PRD 就是空中楼阁。
2.2 工具链选型的逻辑
pdlc-skills 本身不绑定具体工具，但实际用下来，Claude Code 是目前配合度最高的。原因有三个：
第一，Claude Code 支持在终端里直接操作文件系统和 Git，这意味着智能体可以自己读代码、写代码、提交 commit，不需要你手动搬运。第二，它的上下文窗口足够大，能一次性吃下一个中等规模前端工程的核心文件。第三，它对 Markdown 格式的指令理解得比较准，而 pdlc-skills 的输出基本都是 Markdown。
Git 这边没什么好说的，就是标准工作流。但有一个细节要注意：智能体操作 Git 的时候，分支命名和 commit message 必须提前约定好。我一般用feat/fix/docs/这样的前缀，commit message 用type(scope): description的格式。这样后面回溯的时候，一眼就能看出哪个 commit 是智能体生成的、对应哪个任务。
2.3 整体流程的拆解
我把整个流程分成四个阶段，每个阶段对应 pdlc-skills 里的不同技能模块：
| 阶段 | 输入 | 输出 | 对应技能 |
|---|---|---|---|
| 需求反推 | 前端工程代码、页面截图、口头需求 | 结构化 PRD | PRD 生成技能 |
| 任务拆解 | PRD 文档 | TDD 任务列表 | 任务拆解技能 |
| 代码实现 | 单个任务描述 | 可运行的代码 + commit | 编码技能 + Git 技能 |
| 验证迭代 | 代码 + 测试用例 | 测试报告 + 修正记录 | 验证技能 |
这个表格看起来简单，但每个阶段的"输入"和"输出"之间的转换，才是真正花时间的地方。下面我逐个拆。
3. 核心环节的实操细节与避坑要点
3.1 从现有前端工程反推 PRD 的具体做法
这是整个流程里最容易被低估的一步。很多人觉得"我有页面了，PRD 随便写写就行"，但实际做下来，从前端代码反推 PRD 需要解决三个问题：页面之间的关系、数据的流向、交互的边界条件。
我的操作步骤是这样的：
第一步，让智能体扫描工程结构。用 Claude Code 打开项目根目录，执行一条指令让它列出所有路由文件和对应的组件文件。比如：
# 在 Claude Code 里输入 请扫描 src/pages 和 src/router 目录，列出所有页面路由和对应的组件文件路径这一步的目的是建立"页面地图"。智能体会输出一个列表，告诉你有哪些页面、每个页面对应哪个组件文件。
第二步，逐个页面提取交互信息。对每个页面，让智能体读取组件代码，提取出：表单字段有哪些、按钮点击后触发什么动作、页面跳转的目标是什么、有没有条件渲染的逻辑。这一步的输出是一份"页面交互清单"。
第三步，合并成 PRD。把页面交互清单按业务流程重新组织，补上用户角色、使用场景、异常处理，就得到了一份可用的 PRD。
注意：这一步不要让智能体一次性处理所有页面，上下文会爆。我的经验是每次处理 3-5 个页面，处理完一批就保存一次中间结果。
3.2 TDD 任务拆解的粒度控制
PRD 有了之后，下一步是拆任务。这里有个坑：拆得太粗，智能体写代码的时候会跑偏；拆得太细，任务数量爆炸，管理成本比写代码还高。
我试过几种粒度，最后稳定在"一个任务对应一个可独立测试的功能点"。具体标准是：
- 任务描述里必须包含输入、输出、验收条件
- 任务完成后，能写出一条对应的测试用例
- 任务之间的依赖关系明确，没有循环依赖
举个例子，如果 PRD 里有一个"用户登录"功能，我不会拆成"写登录页面""写登录接口""写登录逻辑"这种按技术分层的拆法，而是拆成：
- 用户输入手机号和验证码，点击登录按钮，系统校验验证码正确性
- 验证码正确时，系统生成 token 并跳转到首页
- 验证码错误时，页面显示错误提示，按钮恢复可点击状态
这样拆的好处是，每个任务都是一个完整的"行为单元"，智能体写代码的时候目标很明确，测试的时候也容易验证。
3.3 Git 工作流的约定与自动化
智能体操作 Git 最容易出问题的地方是 commit 混乱。我见过最离谱的情况是，智能体把三个不相关的修改塞进一个 commit，message 写的是"update code"。这种 commit 后面根本没法回溯。
我的做法是在项目根目录放一个.claude/instructions.md文件，里面写清楚 Git 规范：
# Git 规范 ## 分支命名 - 新功能：feat/功能名 - 修复：fix/问题描述 - 文档：docs/文档名 ## Commit Message 格式 type(scope): description type 可选值：feat, fix, docs, refactor, test scope 是模块名 description 用中文，不超过 50 字 ## 提交频率 每完成一个 TDD 任务提交一次，不要攒着一起提交这个文件放在项目里，Claude Code 每次操作 Git 之前都会读它，commit 质量会明显提升。
3.4 验证环节的自动化测试接入
TDD 的核心是"测试先行"，但实际用智能体写代码的时候，我建议反过来：先让智能体写代码，再让它根据任务描述生成测试用例，然后跑测试。原因是智能体对任务描述的理解可能和你的预期有偏差，先写代码能快速暴露偏差，再补测试能验证修正结果。
测试框架的选择看你的技术栈。前端项目我一般用 Vitest，后端用 Jest 或 Pytest。关键是要让智能体能自己跑测试、自己看结果、自己修正。Claude Code 支持执行终端命令，所以这一步可以完全自动化。
4. 完整实操流程：从零到跑通一个真实项目
4.1 环境准备与工具安装
先把基础环境搭好。我假设你用的是 Windows 或者 macOS，Linux 用户应该不需要看这部分。
Git 安装与配置：
Windows 用户去 Git 官网下载安装包，一路默认选项就行。安装完之后打开 Git Bash，配置用户名和邮箱：
git config --global user.name "你的名字" git config --global user.email "你的邮箱"macOS 用户如果装了 Homebrew，直接brew install git就行。
Claude Code 安装：
Claude Code 目前主要通过 npm 安装：
npm install -g @anthropic-ai/claude-code安装完之后，在项目目录下执行claude命令就能启动。如果你在 Windows 上遇到"无法将 claude 项识别为 cmdlet"的报错，检查一下 npm 的全局 bin 目录有没有加到 PATH 里。
注意：Claude Code 需要配置 API Key 才能使用。具体配置方法参考官方文档，这里不展开。
项目初始化：
mkdir my-project && cd my-project git init npm init -y然后把你现有的前端工程代码复制进来，或者从远程仓库 clone 下来。
4.2 用 pdlc-skills 生成第一版 PRD
环境好了之后，开始跑流程。第一步是让智能体读你的前端工程，生成 PRD。
在 Claude Code 里输入这样的指令：
请阅读 src 目录下的所有页面组件，提取每个页面的： 1. 页面名称和路由路径 2. 表单字段及其校验规则 3. 按钮和交互元素的动作 4. 页面跳转关系 然后按照以下结构生成 PRD： - 产品概述 - 用户角色 - 功能列表（按模块分组） - 每个功能的详细描述（包含输入、处理逻辑、输出、异常情况）智能体会花几分钟读代码，然后输出一份 PRD。这份 PRD 不会完美，但能覆盖 80% 的功能点。剩下的 20% 需要你手动补充，主要是业务规则和边界条件。
我一般会把生成的 PRD 保存成docs/PRD.md，然后用 Git 提交一次：
git add docs/PRD.md git commit -m "docs(prd): 基于前端工程生成第一版 PRD"4.3 从 PRD 拆解 TDD 任务列表
PRD 有了之后，下一步是拆任务。指令可以这样写：
请阅读 docs/PRD.md，把每个功能点拆解成可独立开发和测试的任务。 每个任务需要包含： - 任务编号 - 任务描述（一句话说清楚要做什么） - 输入（需要哪些数据或前置条件） - 输出（完成后应该是什么状态） - 验收条件（怎么判断任务完成了） - 依赖任务（如果有） 输出格式用 Markdown 表格。智能体会输出一个任务列表。我一般会检查一遍，把太粗的任务再拆细，把重复的任务合并。然后保存成docs/TASKS.md。
这一步的关键是任务粒度。我的经验是，一个任务对应的代码量控制在 50-200 行之间比较合适。太少说明拆得太细，太多说明拆得太粗。
4.4 逐个任务实现与 Git 提交
任务列表有了之后，就可以开始逐个实现了。对每个任务，在 Claude Code 里输入：
请实现 TASKS.md 中的任务 #1。 要求： 1. 先阅读相关代码文件，理解现有结构 2. 实现功能 3. 写对应的测试用例 4. 跑测试，确保通过 5. 提交 Git，commit message 格式参考 .claude/instructions.md智能体会自动完成这一整套动作。你只需要在它完成后检查一下代码质量和测试结果。
这里有个实操心得：不要一次性让智能体实现多个任务。我试过让它一次做三个任务，结果它把三个任务的代码混在一起，测试也跑不通，排查起来很痛苦。一个任务一个任务来，虽然看起来慢，但总体效率更高。
4.5 验证与迭代
所有任务实现完之后，跑一遍完整的测试套件：
npm test如果有测试失败，让智能体根据失败信息修正。修正完之后再跑一遍，直到全部通过。
然后做一次完整的功能验证：启动开发服务器，手动走一遍核心流程，看看有没有智能体没覆盖到的边界情况。这一步不能省，因为智能体写的代码在逻辑上可能没问题，但在实际交互中可能有体验上的瑕疵。
5. 常见问题与排查技巧实录
5.1 智能体生成的 PRD 太笼统怎么办
这是最常见的问题。智能体读代码的时候，如果代码结构不清晰、注释少、命名不规范，它提取出来的信息就会很粗糙。
解决办法有两个：一是先花时间整理代码结构，把页面组件按功能模块分目录，给关键函数加注释；二是在指令里明确要求"每个功能点必须包含至少一个具体的用户操作示例"。第二个办法见效快，但第一个办法是治本的。
5.2 Git 提交冲突怎么处理
智能体操作 Git 的时候，如果遇到冲突，它可能会卡住或者做出错误的合并决策。我的做法是：在让智能体操作 Git 之前，先手动确保工作区是干净的。具体来说，每次让智能体开始一个新任务之前，先执行git status确认没有未提交的修改，然后git pull拉取最新代码。
如果确实遇到了冲突，不要让智能体自动解决，手动处理完之后再继续。
5.3 测试跑不通但代码看起来没问题
这种情况通常是环境问题或者依赖问题。排查顺序：
- 检查 Node 版本是否匹配（
node -v） - 检查依赖是否安装完整（
npm install） - 检查测试配置文件是否正确
- 检查是否有环境变量缺失
如果以上都没问题，让智能体输出详细的错误日志，根据日志定位。
5.4 智能体理解偏差导致代码跑偏
智能体不是万能的，它对任务描述的理解可能和你的预期有偏差。我的经验是，任务描述里尽量用"用户视角"而不是"技术视角"。比如"用户点击登录按钮后，系统校验验证码"比"实现登录接口的验证码校验逻辑"更容易被正确理解。
如果发现跑偏了，不要让它"改一改"，而是重新描述任务，让它从头实现。改比重写更耗时。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| PRD 内容空洞 | 代码结构混乱、注释少 | 先整理代码结构，或在指令里要求具体示例 |
| Git commit 混乱 | 没有约定规范 | 在.claude/instructions.md里写清楚规范 |
| 测试跑不通 | 环境或依赖问题 | 按顺序检查 Node 版本、依赖、配置、环境变量 |
| 代码跑偏 | 任务描述太技术化 | 改用用户视角描述任务，重新实现 |
| 智能体卡住 | 上下文太长或任务太复杂 | 拆小任务，分批处理 |
| 分支合并冲突 | 工作区不干净 | 操作前先git status和git pull |
6. 一些踩过坑之后总结的实操心得
6.1 关于上下文管理
Claude Code 的上下文窗口虽然大，但也不是无限的。我的经验是，每次对话聚焦一个任务，任务完成后开新对话。不要在一个对话里连续做多个任务，上下文会越来越乱，智能体的表现会下降。
如果任务确实需要参考之前的对话内容，把关键信息保存成文件，在新对话里让智能体读文件。
6.2 关于代码审查
智能体写的代码，我建议至少做一次人工审查。重点看三个地方：一是边界条件处理，二是错误处理，三是安全性相关的地方（比如输入校验、权限判断）。智能体在这些地方容易偷懒。
6.3 关于迭代节奏
不要追求一次跑通整个流程。我的做法是先用一个小功能（比如一个简单的表单页面）跑通全流程，熟悉每个环节的操作和坑点，然后再上大项目。这样试错成本低，学到的东西也更扎实。
6.4 关于工具版本
Claude Code 和 pdlc-skills 都在快速迭代，版本更新可能会带来行为变化。我的建议是，在一个项目周期内锁定版本，不要中途升级。等一个项目做完了，再统一升级，然后在新项目里验证新版本的行为。
6.5 关于文档沉淀
每跑完一个项目，把过程中遇到的问题、解决办法、优化后的指令模板整理成文档。下次做新项目的时候，直接复用这些文档，效率会高很多。我自己的习惯是在项目根目录建一个docs/lessons-learned.md，每次踩坑就记一笔。
这个习惯看起来麻烦，但长期来看回报很高。因为智能体工具的变化很快，但"如何组织工作流""如何写清晰的指令""如何管理 Git"这些底层能力是通用的，沉淀下来就是自己的资产。
最后再分享一个小技巧：如果你在 Windows 上跑 Claude Code 遇到虚拟化相关的报错，检查一下系统的虚拟化功能有没有开启。这个报错跟 pdlc-skills 本身没关系，是运行环境的问题，开启之后就能正常用了。
