Claude Code 团队 AI 插件实践:从新人上线到全栈自动化的渐进式指南
特别鸣谢 :本文由 南京大翼航空 团队实践沉淀而成,感谢团队在 AI 辅助研发领域的持续探索与投入。
后续规划:本文为 dw 插件生态的总览。后续将为每个 skill 单独撰写详细教程文章,涵盖实战案例、配置细节和踩坑经验,敬请关注。
本文涉及的研发规范体系均基于 Claude Code 的插件机制实现。插件是 Claude Code 官方提供的扩展方式,支持自定义命令、Skill、Hook、Agent 等,是目前团队级 AI 研发规范的推荐落地形态。
开篇:我们为什么要做这套插件
在团队引入 Claude Code 做 AI 辅助开发后,我们很快遇到了几个共性问题:
- 新人上手陡峭:不知道有哪些 skill、怎么装、怎么用
- AI 改动污染主分支:直接在当前分支让 AI 改代码,心里不踏实
- 重复踩坑无沉淀:同一个 Bug 换了个人又让 AI 从头排查
- 全栈流程割裂:后端接口、前端页面、测试各跑各的,契约对不齐
- 命令安全无保障 :担心 AI 一个
rm -rf /把环境搞崩
于是我们设计了一套团队级插件 dw,核心思路是 Skills + Agent Team:Skills 封装可复用的研发流程,Agent Team 负责多角色协作编排,配合 9 个渐进式 Skill 覆盖完整研发链路。
Skill 渐进关系:
bash
work ──→ depend ──→ frontend ──→ backend ──→ test ──→ feature ──→ devops ──→ fix ──→ wiki
│ │ │ │ │ │ │ │ │
环境隔离 依赖管理 前端开发 PRD→API 用例生成 全栈编排 云效运维 Bug修复 知识沉淀
从"把环境搭起来"到"把知识留下来",形成完整闭环。下面我们按这个顺序逐一展开。
核心理念
dw 插件的设计围绕一个核心目标:让 AI 全自动化参与研发流程,同时保证安全、可追溯、可复用。
- Skills 封装流程 :将研发活动(修 Bug、写功能、发版本)封装为可复用的 Skill,团队成员通过
/dw:<skill>统一入口触发 - Agent Team 协作:复杂任务由多 Agent 协作完成,编排者分派、执行者落地、验证者把关
- Hooks 全生命周期守护:危险命令拦截、密钥扫描、MCP 预检、自动格式化------在工具调用层面前置防御,而非事后补救
- Wiki 知识沉淀:每次 Bug 修复、功能迭代的结果写入五层知识库,让 AI 的下一次修复能从历史中学习
典型流程
从收到需求到完成交付的完整链路:
bash
/dw:work → 创建隔离的 AI 工作空间
/dw:depend → 装齐团队共享 skill
/dw:feature → 全栈功能(后端+前端+测试一步到位)
或 /dw:backend → 纯后端(PRD → API + 测试 + 文档)
或 /dw:frontend → 纯前端(设计稿 → 代码)
或 /dw:fix → Bug 修复(多 Agent 协作 + 五级升级)
/dw:test "..." → 补充测试用例
/dw:devops pipeline → 触发流水线 / 部署
/dw:wiki query "..." → 检索/沉淀知识
项目目录结构
bash
dw/
├── .claude-plugin/plugin.json # 插件清单(name/version/commands/skills/hooks)
├── agents/ # Agent 定义(Teammate 角色配置)
│ ├── pm.md
│ ├── dev.md
│ └── qa.md
├── skills/ # 核心能力(9 个 skill,每个含 SKILL.md + references/)
│ ├── work/ # Git worktree 工作空间管理
│ ├── depend/ # 团队 skill 依赖管理
│ ├── frontend/ # 设计稿 → 前端页面
│ ├── backend/ # PRD → 后端 API
│ ├── test/ # 测试用例生成
│ ├── feature/ # 全栈迭代编排
│ ├── devops/ # 云效 DevOps 运维
│ ├── fix/ # Bug 修复主流程
│ └── wiki/ # 五层知识库
├── hooks/hooks.json # 生命周期 Hooks(SessionStart / PreToolUse / PostToolUse / Stop)
├── scripts/ # Hook 引用的实际脚本(安全拦截 / 格式化 / 密钥扫描等)
├── settings.json # 插件配置(Agent Teams 开启 / 模型选择)
├── CLAUDE_STANDARDS.md # 团队规范(每次会话自动注入)
└── team-skills.yaml # 团队共享 skill 清单(depend skill 读取)
数据在目标项目中的落盘位置:
perl
<项目根>/
├── .dw/
│ ├── task/ # 任务清单(手动创建: backend-task.md / frontend-tasks.json 等)
│ ├── memory/ # 快照目录(自动维护,支持断点续跑)
│ └── wiki/ # 知识库(随 git 追踪,五层结构)
├── .env.dw # 云效配置(不入 git!)
└── .gitignore # 必须包含 .env.dw 和 .claude/worktrees/
一、work --- AI 工作空间管理
基于 git worktree 创建隔离的 AI 工作分支(<branch>-ai),自动安装依赖,在新终端启动 Claude,AI 改动不污染主分支。
| 命令 | 说明 |
|---|---|
/dw:work |
基于当前分支创建 AI worktree + 装依赖 + 新终端启动 Claude |
/dw:work sync |
将 worktree 分支 rebase 到最新基准分支 |
/dw:work remove |
删除当前分支对应的 AI worktree 和分支 |
/dw:work clear |
清除 .claude/worktrees/ 下所有 worktree(需输入 yes 确认) |
未忽略则自动追加] C --> D[git pull origin branch] D --> E[worktree add -b branch-ai
已存在则追加时间戳] E --> F[auto-setup
pnpm/cargo/poetry/pip/go] F --> G[新终端启动 Claude] B -- sync --> H[git pull + rebase worktree] B -- remove --> I[安全检查: 不在 worktree 内] I --> J[worktree remove + branch -D] B -- clear --> K[扫描 + 用户确认 yes] K --> L[逐一 remove + branch -D + prune]
二、depend --- 团队 Skill 依赖管理(三级体系)
管理团队共享 skill 依赖,从 YAML 清单读取配置,通过 npx skills 完成安装/更新。分为个人(~/.skills/)、项目(./.skills/)、团队(team-skills.yaml)三个级别。
| 命令 | 说明 |
|---|---|
/dw:depend |
等同 install:补齐清单中缺失的 skill,不动已装 |
/dw:depend install |
显式 install,只补缺不升级 |
/dw:depend update |
git pull 清单 + 升级全部已装 skill 到最新 |
/dw:depend update --dry-run |
预览模式,只打印命令不落地 |
/dw:depend install --only <name> |
单点重试某条安装失败的 skill |
/dw:depend update --scope project |
指定安装到项目级 ./.skills/ |
三、frontend --- 前端开发
dw:frontend 定位前端全流程开发,不仅限于设计稿转页面。覆盖三大场景:设计稿驱动 (MasterGo → 代码)、接口联调 (基于 backend 产出的 API 契约对接)、前端逻辑开发(状态管理、路由、交互逻辑等)。同时三平台并行支持 PC(Vue3+AntDV)、小程序(Taro+Taroify)、H5(Taro H5)。
| 命令 | 说明 |
|---|---|
/dw:frontend |
读取 .dw/task/frontend-tasks.json,按 platform 批量生成页面 |
清单格式(.dw/task/frontend-tasks.json):
| 字段 | 类型 | 说明 |
|---|---|---|
platform |
pc / mini / h5 |
目标平台:PC(Vue3+AntDV) / 小程序(Taro+Taroify) / H5(Taro H5+Taroify) |
tasks[].id |
number | 唯一 ID,用于快照文件名 |
tasks[].url |
string | MasterGo URL(含 file/page_id/layer_id) |
tasks[].filePath |
string | 产出路径(相对 project root) |
tasks[].name |
string | 页面中文名 |
开发决策分支:
页面 + 逻辑 + 接口对接] S5 --> S6[Lint 自检] end
页面生成流程:
四、backend --- 需求驱动的后端全流程
从 PRD 一键落地为「数据库 schema + 三层代码 + 测试 + OpenAPI 文档」,7 步顺序执行,快照断点续跑。支持 4 种技术栈。
| 命令 | 说明 |
|---|---|
/dw:backend |
文件模式:读取 .dw/task/backend-task.md(YAML frontmatter + PRD 正文) |
/dw:backend "<描述>" |
对话模式:自然语言描述需求 |
frontmatter 必填字段:
| 字段 | 值 | 说明 |
|---|---|---|
platform |
node / java / go / python |
技术栈,非法值立即报错 |
module |
string | 模块英文短名(用作快照/目录名) |
outputDir |
string | 代码产出目录(相对 project root) |
platform/module/outputDir + 快照扫描] B --> C["Step 1 需求解析 -> 结构化 JSON"] C --> D["Step 2 Schema 设计 -> migration + entity"] D --> E["Step 3 API 契约 -> 接口清单表格"] E --> F["Step 4 编码实现 -> Controller/Service/DTO"] F --> G["Step 5 测试生成 -> 单测 + 集成"] G --> H[Step 6 OpenAPI 文档] H --> I["Step 7 Lint 自检 -> 两轮自动修复"] I --> J[快照 status=done]
五、test --- 测试用例生成与验证
基于 wiki 历史 + git 近期改动,生成双层测试用例(Layer A 基本执行 / Layer B 复杂组合)。支持等价类、边界值、Pairwise、状态机等多种方法论。8 个降级场景确保外部依赖缺失时不中断流程。
| 命令 | 说明 |
|---|---|
/dw:test "<描述>" |
描述模式:自然语言指定测试目标 |
/dw:test <id> |
单 ID 模式:拉取云效工作项详情后生成 |
/dw:test id1,id2,... |
批量模式:多个 ID 循环执行 |
wiki + git commits] D --> F E --> F F --> G[Step 2 生成双层用例
Layer A 必跑 / Layer B 按需] G --> H[Step 2.5 覆盖率自检
最多 1 轮补全] H --> I{检测到 test runner?} I -- 是 --> J[Step 3 运行测试
失败按维度聚类] I -- 否 --> K[静态验证模式
类型 + lint + 桌面演算] J --> L[报告 + 可信度标签] K --> L
六、feature --- 全栈迭代编排
同时涉及后端 + 前端 + 测试时,由 feature 统一调度三个下游 skill。主会话只做编排不做编码,检索 wiki → 建 Agent Team → 派活 → 契约交接 → 收束汇总。
| 命令 | 说明 |
|---|---|
/dw:feature |
文件模式:读取 .dw/task/feature-task.md |
/dw:feature <id> |
工作项模式:拉取云效工作项详情 |
/dw:feature "<描述>" |
对话模式:自然语言描述全栈需求 |
frontmatter 必填字段(.dw/task/feature-task.md):
| 字段 | 值 | 说明 |
|---|---|---|
platforms.backend |
node / java / go / python / none |
后端平台 |
platforms.frontend |
pc / mini / h5 / none |
前端平台 |
platforms.test |
true / false |
是否派发测试 |
modules.backend[].module |
string | 后端模块名 |
modules.backend[].outputDir |
string | 后端产出目录 |
modules.frontend[].id |
number | MasterGo 设计稿 ID |
modules.frontend[].url |
string | MasterGo URL |
modules.frontend[].filePath |
string | 前端产出路径 |
modules.frontend[].name |
string | 页面中文名 |
+ 自判是否回写 wiki] G --> M
七、devops --- 云效 DevOps 全流程编排
将云效 DevOps 操作从"手工点页面"提升为"一句话驱动"。HITL 守卫所有写操作,长时操作 5 分钟超时支持用户决策,快照支持断点续接。
| 命令 | 说明 |
|---|---|
/dw:devops <自然语言> |
自然语言描述运维意图 |
/dw:devops .dw/task/devops-task.md |
任务清单模式:YAML frontmatter + actions 数组 |
/dw:devops pipeline run <id> |
子命令:触发流水线 |
/dw:devops pipeline list |
子命令:列出流水线 |
/dw:devops pipeline log <runId> |
子命令:查看运行日志 |
/dw:devops mr create source=x target=y title=... |
子命令:创建合并请求 |
/dw:devops branch create name=x |
子命令:创建分支 |
/dw:devops deploy <app> env=<env> |
子命令:创建部署单 |
/dw:devops workitem get <id> |
子命令:查询工作项 |
读 .env.dw 创建快照] B --> C[Phase 1 域识别
工作项/代码/流水线/部署/...] C --> D[Phase 2 HITL 确认
写操作默认需确认] D --> E[Phase 3 执行 + 流式回报
长任务轮询 5min 超时] E --> F[Phase 4 汇总 + 知识沉淀
可选 wiki 回写]
八、fix --- Bug 修复
Bug 修复是最高频的研发活动。dw:fix 将 Bug 单或自然语言描述转化为可合并的修复 MR,完整流程覆盖:wiki 记忆预检 → 探索定位根因 → 任务拆分 → 编码 → 自测 → QA 对抗测试 → 知识沉淀。内置五级升级策略,修复失败时逐级降级,不陷入无限循环。
| 命令 | 说明 |
|---|---|
/dw:fix "<描述>" |
描述模式:自然语言描述 Bug 现象 |
/dw:fix <id> |
单 ID 模式:拉取云效工作项详情后修复 |
/dw:fix id1,id2,... |
批量模式:多个 Bug 串行执行完整修复流程 |
五级升级策略:
| 层级 | 策略 | 触发条件 |
|---|---|---|
| L1 | 标准 Dev+QA 协作修复 | 默认起点 |
| L2 | 重试(换思路/换上下文) | L1 失败 |
| L3 | 查找并调用合适 skill 辅助 | L2 失败 |
| L4 | 多 Dev 并行修复对比 | L3 失败 |
| L5 | 归档为未解决 Bug,报告用户 | L4 失败 |
拉取工作项详情] B -- ">=2" --> E[批量模式
循环 single-mode] C --> F[wiki 记忆预检] D --> F E --> F F --> G[探索定位根因] G --> H[任务拆分] H --> I[Dev 编码] I --> J[Dev 自测] J --> K{自测通过?} K -- 否 --> I K -- 是 --> L[QA 对抗测试] L --> M{QA 通过?} M -- 否 --> N{"轮次小于 3?"} N -- 是 --> I N -- 否 --> O[五级升级策略] M -- 是 --> P[知识沉淀
写入 .dw/wiki/bugs/] P --> Q[创建 MR 到远程分支]
九、wiki --- 五层知识库
受 Karpathy LLM Wiki 启发的轻量级知识库,记录 bug 修复和 feature 迭代全过程。其他 skill 程序化消费:fix 修复后自动录入,feature 可选回写,test/fix 执行前检索历史。
| 命令 | 说明 |
|---|---|
/dw:wiki init |
初始化 .dw/wiki/ 骨架 |
/dw:wiki add bug "<描述>" |
录入 bug 修复记忆(经 Jaccard 去重) |
/dw:wiki add feature "<描述>" --iteration=<迭代> |
录入 feature 迭代记录(五层 pipeline) |
/dw:wiki query "<关键词>" |
检索历史(跨 bugs/features/hubs/concepts) |
/dw:wiki dashboard |
生成 HTML 可视化仪表盘 |
/dw:wiki update <id> --body-file=<path> |
更新条目(body 变化触发版本分裂) |
/dw:wiki evolve --scan-bugs |
bug 簇分析 → skill 改进建议 |
五层结构:
| 层 | 目录 | 角色 |
|---|---|---|
| L0 raw | raw/ |
原始输入一字不改,永久存证 |
| L1 feature | features/ |
Raw 清洗后的全量语义版本,1:1 对应 |
| L2 hub | hubs/ |
按标准化 title 合并同类 feature(编辑距离 ≤2) |
| L3 concept | concepts/ |
从 hub/feature 中提取的原子概念,独立统计 |
| L4 bug | bugs/ |
Bug 直通子图,单独索引(Jaccard ≥0.95 拒绝,≥0.70 合并) |
已有 hub?} E -->|命中| F[合并 hub body] E -->|未命中| G[创建新 hub] F --> H[提取/更新 concepts] G --> H H --> I[重建缓存]
十、Hooks 系统 --- 全生命周期安全网
上面 9 个 skill 是"主动能力",hooks 则是"被动保障"。它们在 Claude Code 会话的各个生命周期节点自动触发,前置拦截风险。
Hook 矩阵
| 事件 | 触发条件 | 行为 | 是否阻断 |
|---|---|---|---|
SessionStart |
每次会话启动 | 注入 CLAUDE_STANDARDS.md 团队规范 |
否 |
UserPromptSubmit |
每次用户输入 | 注入 git 上下文(分支/dirty 文件/worktree) | 否 |
PreToolUse |
匹配 mcp__.* |
MCP 调用前预检依赖(.env.dw / token / npx) |
是(exit 2) |
PreToolUse |
匹配 Bash |
拦截危险命令(rm -rf /, force push to main, fork bomb 等) | 是(exit 2) |
PostToolUse |
匹配 `Write | Edit | MultiEdit` |
PostToolUse |
匹配 `Write | Edit | MultiEdit` |
Stop |
任务完成时 | 桌面通知 | 否 |
各脚本详解
SessionStart --- 规范注入
会话一启动就把 CLAUDE_STANDARDS.md 注入到 Claude 的上下文中。内容包括:核心工作原则、代码规范(单次 ≤ 200 行)、Bug 修复规范、Feature 开发规范、重构规范、Agent 协作协议、知识持久化规范。
UserPromptSubmit --- 上下文注入
每次你按下回车,脚本自动在 prompt 前面追加一段 git 状态信息:
bash
[git-context]
branch: feat/login (ahead 2 / behind 0 vs origin/feat/login)
worktree: /Users/xxx/git/myapp
dirty: 5 files (1 added / 3 modified / 1 deleted)
Claude 不用再主动跑 git status 就能感知仓库状态。
PreToolUse(Bash) --- 危险命令拦截
这是最重要的一道安全防线,拦截清单包括:
rm -rf /或rm -rf ~(含sudo变体)git push --force到main/master/prod/production/releasegit reset --hard到远端主干git clean -fdx/git checkout -- .mkfs.*/dd if=... of=/dev/...- fork bomb
:(){ :|:& };: chmod -R 777 /
命中后 exit 2,Claude 会看到拦截原因并自行改写为更安全的命令。
PostToolUse --- 密钥扫描
代码写入后自动扫描,命中以下任一正则即阻断:
AKIA[0-9A-Z]{16}--- AWS Access Keysk-(ant-)?[A-Za-z0-9_\-]{32,}--- OpenAI / Anthropic API Keygh[pousr]_[A-Za-z0-9]{36,}--- GitHub PATxox[baprs]-[A-Za-z0-9-]{10,}--- Slack Token-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-------- PEM 私钥AIza[0-9A-Za-z_\-]{35}--- Google API Key
对 .env 文件中的密钥只警告不阻断(.env 本来就是放密钥的地方),但会提醒你确认 .gitignore。
PostToolUse --- 自动格式化
文件写入后按扩展名分派格式化工具:
| 扩展名 | 工具链 |
|---|---|
.ts/.tsx/.js/.jsx/.vue/.json/.md/.css/.scss/.html/.yaml |
prettier |
.py |
ruff format → black → python -m black |
.go |
gofmt -w |
.rs |
rustfmt --quiet |
.java |
google-java-format -i |
.sh/.bash |
shfmt -w |
工具不在 PATH 就静默跳过,不影响主流程。
Stop --- 桌面通知
任务完成时发送桌面通知。Windows → BurntToast(未装降级 msg.exe),macOS → osascript,Linux → notify-send。都失败也 exit 0。
十一、总结与最佳实践
10.1 前后端合并一个项目时的注意事项
如果你的项目是前后端合一(比如同一个 git 仓库下既有 src/modules/ 又有 src/views/),feature skill 原生支持这种场景:
- 契约交接机制保证接口对齐:backend 产出 API 契约 → frontend 按契约对接,不会有字段名对不上的问题
- backend 产出 OpenAPI 文档:可直接作为 frontend 的接口参考
- 模块目录独立 :backend 产出在
src/modules/<module>/,frontend 产出在src/views/<page>/,互不冲突 - feature-task.md 同时声明两端配置:一次编排,两端并行产出
10.2 新人上手路径速查
bash
第一步: /dw:depend # 装齐团队 skill
第二步: /dw:work # 创建 AI 工作空间
第三步: 开始编码 # 使用 backend / frontend / fix 等
第四步: /dw:test "..." # 生成测试
第五步: /dw:wiki query "..." # 沉淀和查询知识
场景速查:
| 你要做什么 | 用什么 | 一句话 |
|---|---|---|
| 全栈功能 | /dw:feature |
一条命令搞定多 Agent 协作 |
| 后端接口 | /dw:backend |
PRD → API + 测试 + 文档 |
| 前端页面 | /dw:frontend |
设计稿 → 代码 |
| Bug 修复 | /dw:fix |
多 Agent 协作,五级升级兜底 |
| 生成测试 | /dw:test |
双层用例 + 优雅降级 |
| 运维操作 | /dw:devops |
HITL 守卫,安全第一 |
| 查历史 | /dw:wiki query |
五层知识库检索 |
| 装 skill | /dw:depend |
三级体系,按需安装 |
10.3 慎用部分 MCP 说明
dw 插件依赖三个 MCP 服务,它们在使用前会自动预检(PreToolUse hook),但理解它们的权限边界很重要:
| MCP 服务 | 需要什么 | 哪些 skill 使用 | 注意事项 |
|---|---|---|---|
yunxiao(云效) |
.env.dw(含 Cookie + Token) |
fix, test, feature, devops | Cookie 含完整登录态,权限极高 ,.env.dw 必须在 .gitignore 中 |
mastergo-magic-mcp |
MASTERGO_TOKEN 环境变量 |
frontend, feature | 仅设计稿读取权限,MCP 预检阻断后给出配置指南 |
playwright |
npx 命令可用 |
E2E 测试场景 | E2E 浏览器自动化,需 Node.js 18+ |
核心原则:
- MCP 调用前自动预检,缺配置不是静默失败,而是明确告诉你缺什么、怎么补
.env.dw绝不进 git,Hook 的 secret-scan 也会拦截.env外的密钥- Cookie 过期时 skill 自动降级(fix 单 ID → 描述模式),不会卡死
10.4 安全红线速查
所有以下行为被 Hooks 自动拦截(exit 2),无需担心 AI 越界:
| 红线 | 拦截机制 |
|---|---|
git push --force 到 main/master/prod |
bash-danger-guard.sh |
rm -rf / / rm -rf ~ |
bash-danger-guard.sh |
fork bomb / 写裸盘 / chmod -R 777 / |
bash-danger-guard.sh |
| 代码中硬编码 API Key / Token / 私钥 | secret-scan.sh |
| MCP 调用缺前置依赖 | mcp-availability-check.sh |
附录:关键目录速查
perl
项目根/
├── .dw/
│ ├── task/ # 任务清单(手动创建)
│ │ ├── backend-task.md
│ │ ├── frontend-tasks.json
│ │ ├── feature-task.md
│ │ └── devops-task.md
│ ├── memory/ # 快照(自动维护,支持断点续跑)
│ │ ├── backend/<platform>/<module>.md
│ │ ├── frontend/<platform>/<id>.md
│ │ ├── feature/<name>.md
│ │ └── devops/<slug>.md
│ └── wiki/ # 知识库(随 git 追踪)
│ ├── raw/
│ ├── features/
│ ├── hubs/
│ ├── concepts/
│ └── bugs/
├── .env.dw # 云效配置(不入 git!)
└── .gitignore # 必须包含 .env.dw 和 .claude/worktrees/
本文基于 dw 插件 v1.0.0,持续迭代中。如果你对某个 skill 的设计细节感兴趣,每个 skill 目录下都有完整的
README.md和references/参考文档。
下一步
本文为 dw 插件生态的总览。读完本文,你应该能判断遇到什么问题该用什么 skill。
后续计划:
- 9 篇 skill 详情教程:每个 skill 单独成文,涵盖实战案例、配置细节、参数详解和踩坑经验
- 开源仓库 + Demo 项目:代码和最小可运行示例将在详情文章中同步披露
如果你对某个 skill 特别感兴趣,欢迎在评论区留言,我们会优先输出。
觉得有用?点个赞收藏,更新不迷路。 告别重复劳动:一套插件让 AI 替你写代码、修 │ 痛点切入,动词驱动 │
│ │ Bug、做测试、上生产