夜雨聆风一年踩过的坑，9 个 skills，3 个 agents，全开源了。
你好，我是静远。
今年我们团队全面转向 AI 编码（用 Claude、CodeBuddy 这类工具）。
一年下来，走了很多弯路：
AI 写完代码，过两天发现 spec 跟实现对不上 任务拆得太细，后端做完了前端没人接 上线三个月，技术债积累到改不动
每个问题都让我们返工一遍。
最近我把这些反复踩过的坑，沉淀成了 9 个 skills + 3 个 agents+CLAUDE.md ，形成一套基于 Spec 驱动的开发的标准流程，然后装进一个 Claude 插件，团队里所有项目统一用。
今天开源了。
地址：
https://github.com/jingyuan-opc/ai-coding-plugin一、为什么用插件，而不是直接把 skills 塞进项目？
我们之前是这么干的：在每个项目的 .claude/skills/ 目录里手动塞 skill。
问题很明显：
skill 升级了 10 个项目，10 个项目都要手动改 新人入职要 copy 一份，新旧版本混用 团队不同项目用不同版本，review 时混乱
Claude 的插件机制正好解决这些。
插件 = 一组 skill、agent、command 的打包，通过 marketplace 一键安装、自动更新。
类比：你装 VS Code 扩展是直接装到全局，团队统一版本，而不是每个项目里塞一份。
我用插件做出来后，效果立竿见影：
升级一次，全团队所有项目生效 新人 install一行命令，配置齐了仓库即文档，团队成员都看得到用了什么 skill
二、插件里装了什么？
2.1 Skills
按"编码工作流"的时间线排序：
阶段 1：需求/规格化
soc-spec：把 idea 头脑风暴成 OpenSpec proposal。这是整个工作流最重要的一步，只有需求澄清得足够清晰，后续才能顺利推进。
这是整个工作流的入口。
用法：
/ai-coding:soc-spec 我想做一个用户积分系统skill 会启动两阶段 review：
spec review（subagent 审完整性、YAGNI、任务覆盖度） architect review（架构师 subagent 审架构合理性、模式对齐、代码味道风险）
只有 review 全部通过 + 用户确认，才会进入下一阶段。
关键设计：在呈现设计并获得用户批准之前，skill 严禁调用任何实现工具、写代码、scaffold 项目。这条硬门禁写在 skill 的 HARD-GATE 段，避免"AI 拿到需求立刻动手"的坏习惯。
阶段 2：任务拆分（大需求、新项目时使用）
大部分人对 AI 任务的粒度和拆分方式没有概念，尤其是技术水平一般的同学。
split-task：把需求拆成独立可交付、端到端的切片
v1.1 版本有三条铁律（硬约束）：
端到端：一个切片 = 一个用户能完成的事，覆盖后端 + 前端 + 测试。禁水平切（后端卡 + 前端卡分离）。 用户功能视角：按"用户能做什么"切，不按后端技术模块切。 拆分与排期解耦：拆分阶段只定任务边界，并行/人员/时序是排期的事。
按 5 个切分依据的优先级处理：
类比：split-task 像"独立电影制片人"，一个切片 = 一部能完整上映的短片，不是"摄影师组卡"+"灯光组卡"。
阶段 3：实现
soc-build：用子智能体执行 OpenSpec 任务
这是工作流的核心执行环节。
关键设计：每个任务派发全新的子智能体，不继承会话历史。
为什么这么做？
子智能体获得隔离的上下文和精确构建的指令 编排器的上下文不会随任务数线性爆炸 任务之间不暂停，连续执行
派发载荷只传最小化标识符（task ID + 标题 + spec 路径 + 门禁配置），子智能体自己从磁盘读 proposal.md / design.md / tasks.md 的相关切片。
每个任务完成后，触发任务级验收标准验证：
单元测试已编写并通过（仅本任务范围） 全量测试套件和覆盖率不在任务级检查
任务失败一次重试，连续 2 次失败暂停整个流程通知用户。
阶段 四：归档
soc-archive：把已完成的变更归档，并同步 Spec，使得随着迭代演进，spec 保持最新
变更完成 + 用户验收 → 移到 openspec/changes/archive/。下次 soc-build 不会再把它当活动变更。内部自动触发 openspec-sync-specs，实现 OpenSpec 跨变更同步
多个并行变更时，保持 spec 主线与各 proposal 一致。
此外还整合了几个其他工具：
代码质量
tech-debt-sweep：架构师视角的技术债扫描
核心心智模型是"债务而非快照"。
技术债像金融债一样有三个属性：
本金：修复成本 利息：不修的持续代价 违约风险：什么时候会爆
一次有价值的体检不是"列出所有问题"，而是回答四个问题：
哪些债正在产生利息？（N+1 查询每次请求都跑，比死代码紧急 100 倍） 哪些债的违约风险在升高？（长事务低流量没事，流量上来就死锁） 哪些债不值得修？（死代码躺着不碍事，"清理"它可能踩到隐藏依赖） 债务趋势是什么？（这周比上周更糟还是更好？）
产出顺序：严重度分级 → 关联归并 → 趋势 diff → Plan。
skill 第零步会自动加载上次 baseline（docs/tech-debt/YYYY-MM-DD.md），跟本次扫描 diff，让你看到"这周新增了什么债、修了什么、什么在恶化"。
neat-freak：文档同步
需求文档、技术文档跟代码保持同步
design-taste-frontend：前端设计品味
前端 UI 的视觉一致性、组件复用、设计系统约束。
2.2 3 个 Agents
跟 skills 配合的 agents：
architect：架构师视角
在 soc-spec 流程里负责架构 review，审架构合理性、模式对齐、代码味道风险。跟 skill 内的 spec review 是两个独立环节。
e2e-runner：端到端测试运行
跑全链路测试，验证整个 feature 流程跑通，不是单模块单元测试。
pm：产品经理视角
自己梳理需求然后生成 UI 原型，基于原型再去确认需求。
个人强烈推荐基于原型驱动需求与开发的模式。
2.3 1 个 CLAUDE.md
plugins/ai-coding/CLAUDE.md 是一份团队 AI 编码规则手册：
架构师视角 代码设计优先：高内聚，低耦合、单一职责 全局观：遵循已有模式与规范、复用已有代码等 AI 编码红线（哪些事 AI 不能做）
重要提醒：CLAUDE.md 不会自动同步到项目里。每个新项目要手动复制一份到项目根目录。
三、4 步安装使用
步骤 1：添加 marketplace
打开 Claude Code 会话窗口：
/plugin marketplace add https://github.com/jingyuan-opc/ai-coding-plugin.git步骤 2：安装插件
/plugin install ai-coding@ai-coding-plugin选第一项"Install for you (user scope)"，装到用户目录，所有项目生效。
步骤 3：重载插件
/reload-plugins步骤 4：开始用
/ai-coding:soc-spec 我要做一个xxx 功能完整工作流：
soc-spec（需求 + 规格） ↓soc-build（子智能体实现） ↓soc-archive（归档）插件更新
在 Claude 会话里找到已安装的插件 → 回车进去 → 选"更新"。然后 /reload-plugins。
四、实战效果对比
我们用一个真实场景对比：做一个用户积分系统。
没有插件的纯 AI 编码流程
你："帮我想一个积分系统的方案" → AI 给你一个泛泛的方案 你："开始写代码" → AI 立刻动手 一周后你发现：方案跟实现对不上，AI 改了一版跟你确认的又不一样 你又花 3 天整理 spec，让 AI 按 spec 重做 3 周过去，技术债积累，开始缝缝补补
用 ai-coding 插件的流程
你： /ai-coding:soc-spec 我要实现 xx 功能→ 头脑风暴 + 两阶段 review你： /ai-coding:soc-build实现xxAI完成后，你检查没问题后： /ai-coding:soc-archive→ 归档
写在最后
回头看这个插件的演化过程，本质上就是把团队一年踩过的坑变成了工具。
spec 不对齐 → 强制两阶段 review 任务拆错 → 强制端到端切片 上下文爆炸 → 子智能体隔离 技术债失控 → 趋势 diff 而非快照
这些 skill 不是凭空设计出来的，是被问题"逼"出来的。
这也是为什么我愿意开源：AI 编码的坑，每个团队都会踩。我们踩过一遍，你不用再踩。
地址再发一遍：
https://github.com/jingyuan-opc/ai-coding-plugin如果觉得有用，欢迎 star、fork、提 issue、提 PR。
如果团队里有更好的实践，也欢迎分享出来，让这个插件越用越好。
静远，一个在AI时代坚持手把手带你上车的普通人。
