Skip to content

onboarding.md

Latest commit

 

History

History
263 lines (179 loc) · 14.2 KB

onboarding.md

File metadata and controls

263 lines (179 loc) · 14.2 KB
Raw

Onboarding — dev-skills

新加入团队?这一页带你 30 分钟内跑起来。

60 秒了解这是什么

dev-skills 是团队的工程规范载体。它用轻量 SDD 把需求、方案、实现、验证和 review 串成一条可追踪链路,并提供独立的 Swagger/OpenAPI 文档查询入口。它有三层:

  • 行为基线(references/dev-baseline.md + docs/why-dev-baseline.md):所有 skill 共享的四条原则,以及每条原则关闭的失败模式。
  • Always-on 模板(CLAUDE.md.template / AGENTS.md.template):复制到消费项目根目录后,成为 agent 永远在背景读取的短规则。
  • 场景 skill(dev-auto / dev-design-context / dev-grill-docs / dev-spec / dev-plan / dev-tdd / dev-fix / dev-image-to-code / swagger-doc-skill / dev-verify / dev-code-review / dev-commit-writer / dev-finish):特定时机用 Claude / Codex 跑的检查和文档查询工具。

不是替代你思考的工具,是让你不用每次都重新想团队约定的工具。

安装(5 分钟)

Claude Code 用户

在 Claude Code 里逐行执行:

/plugin marketplace add https://github.com/Jason-chen-coder/dev-skills
/plugin install dev-skills

如果团队 fork 到了别的 owner,把 Jason-chen-coder 替换成实际 owner。

别忘了 CLAUDE.md —— skill 不会自动把团队级 always-on 文件复制到你项目根。第一次装完跑一次:

curl -O https://raw.githubusercontent.com/Jason-chen-coder/dev-skills/master/CLAUDE.md.template
mv CLAUDE.md.template CLAUDE.md   # 重命名后按 <!-- team:fill --> 填团队约定

CLAUDE.md.template 是短版常驻规则。更细的分支、PR、测试、错误处理、日志、feature flag 取舍参考见 docs/team-policy.md。

Codex 用户

当前 Codex 兼容方式是复制 skills/* 到 $CODEX_HOME/skills:

git clone https://github.com/Jason-chen-coder/dev-skills.git
cd dev-skills
bash scripts/install-codex-skills.sh

如果需要团队级 always-on 规则,复制 Codex 模板到项目根:

curl -O https://raw.githubusercontent.com/Jason-chen-coder/dev-skills/master/AGENTS.md.template
mv AGENTS.md.template AGENTS.md   # 重命名后按 <!-- team:fill --> 填团队约定

AGENTS.md.template 与 CLAUDE.md.template 保持同一套短规则,只是面向 Codex / OpenCode 的文件名。

npx skills 用户

跨 agent CLI 安装方式:

npx skills add Jason-chen-coder/dev-skills              # 项目级
npx skills add Jason-chen-coder/dev-skills --global     # 全局

验证项目级安装:

ls .claude/skills/
# 应看到 dev-auto / dev-design-context / dev-grill-docs / dev-spec / dev-plan / dev-tdd / dev-fix / dev-image-to-code / swagger-doc-skill / dev-verify / dev-code-review / dev-commit-writer / dev-finish

其他 agent CLI(Cursor / Gemini CLI)

按对应工具的 skill 机制安装完整目录,保留 SKILL.md、references/、scripts/ 等文件及相对路径。仅复制 SKILL.md 会漏掉基线和执行依赖。工具没有原生 skill 支持时,保留完整目录,在 rules 中说明触发条件和入口路径,执行相关任务时再加载所需内容;具体接入路径按该工具当前文档或团队约定确认。

升级

升级只更新 skill 文件,不会自动覆盖你项目里的 CLAUDE.md / AGENTS.md。如果模板更新了,需要自己对比后同步。

Claude Code

/plugin update dev-skills

如果没生效,卸载后重装:

/plugin uninstall dev-skills
/plugin install dev-skills

Codex

Codex 当前是复制目录安装,升级时需要重新同步:

cd dev-skills
bash scripts/install-codex-skills.sh --upgrade

npx skills

npx skills update

如果你的版本没有 update,用 force 重新安装:

npx skills add Jason-chen-coder/dev-skills --force
npx skills add Jason-chen-coder/dev-skills --global --force

第一次跑(15 分钟)

跑通一遍最常用的 dev-code-review:

  1. 选一个范围明确的实际改动,或在临时练习仓库准备一个 diff。

  2. 别 commit,先在 Claude Code / Codex 里说:

    准备 commit,review 一下

  3. Claude / Codex 会按 dev-code-review 审查,先列有证据的问题,再给简短结论;报告长度随实际问题调整,不必填空检查表。例如:

    ━━━ Dev Code Review ━━━
Verdict   : ✅ READY  /  ⚠ FIX P1  /  ❌ BLOCK  /  INCOMPLETE
...

  4. 处理确认的问题;如果是 INCOMPLETE,先补影响判断的证据。

  5. 有修改时再审查改后的结果。✅ READY 只覆盖已审查范围;需要提交时另按授权执行,commit message 仅在用户要求或已授权提交流程中生成。

第一次完整跑下来你就懂了。

十三个 skill 怎么选

先记用户入口,再理解流程门禁。你不需要主动点名每个 skill。

用户入口

我想… 用哪个
不知道下一步该跑哪个 / 失败了想恢复 dev-auto(入口推荐器,只指路)
写代码前对模糊需求做对齐,并按需沉淀术语 / 决策 dev-grill-docs
旧提示或旧工作流里写着 dev-spec dev-spec(兼容入口,等价于 dev-grill-docs --spec-only)
需求已对齐,要把 spec 转成可执行和可验证的实施 plan(尤其复杂功能 / 高风险改动) dev-plan
修 bug:复现 + 假设 + 反向追溯 + 修 root cause + defense-in-depth + regression test + pattern analysis dev-fix
给 UI 截图 / 设计图生成代码,并保留 input、tab、select、button 等真实控件 dev-image-to-code
查询 Swagger / OpenAPI / Knife4j 文档里的模块、接口、请求响应或完整类型,或导出完整 Markdown / JSON swagger-doc-skill
写完代码,commit 前要严格把关 dev-code-review

流程门禁和特殊入口

类型 Skill 什么时候出现
流程门禁 dev-tdd feature / hotfix / refactor 按行为和风险选择测试;新增行为优先先测后改,重构可用原实现已通过的行为刻画测试,低影响改动可复用适当检查。
流程门禁 dev-verify 声称完成 / fixed / ready 前,由 agent 要求 fresh evidence。
流程门禁 dev-finish 验证和 review 通过后,用于 merge / PR / keep / discard。
一次性设置 dev-design-context UI / landing page / 产品界面首次进入项目前,让 agent 先理解设计方向。
看图写页面 dev-image-to-code 用户提供 UI 图后,分析图片、解决关键缺口、实现页面并做截图 / 交互验证;设计尺寸可从图片元数据兜底。
需求对齐 dev-grill-docs 拷问术语、边界和决策,生成 spec artifact;稳定内容可写入 CONTEXT.md / ADR。
消息生成 dev-commit-writer 明确只想要 commit message 时使用;不代表已通过 review 或授权执行 commit。

dev-code-review 在用户要求或已授权提交流程中,可在通过后给出 commit message,通常无需再跑 dev-commit-writer;用户后续单独请求 message 时仍可使用。 dev-design-context 用于首次建立或明确重设设计方向,会写 .design-context.md;已有充分设计依据时无需重复执行。 dev-image-to-code 要求 UI 图;缺设计尺寸时读取图片元数据作为暂定基准。裁剪/缩放会影响还原、关键文案或隐藏业务仍不清时才问,可逆的视觉细节参考图片和项目惯例。 swagger-doc-skill 支持 Swagger UI、OpenAPI JSON/YAML、Knife4j、FastAPI docs 和 Redoc。它可列模块/tag、接口,查看单个接口的请求/响应,输出完整 schema / model / DTO,或导出整份 Markdown / JSON API 文档。对话里可以说 用 swagger-doc-skill 查询这个 Knife4j 文档的模块、接口和完整类型: <docs-url>。 Swagger source 只在当前 chat复用:当前 chat 只有一个已确认来源时可继续追问;出现多个来源时必须先确认,不能跨 chat 继承。项目配置只在显式传入 --config <path> 时读取,不得把 chat 中的 URL、token 或 header 自动写入共享配置。 需求清楚、范围小的工作可直接实施并做适当检查。业务含义、权限或不可逆操作仍有关键缺口时用 dev-grill-docs 对齐;需要需求文档时生成 spec。复杂或高风险工作先做 dev-plan,已有需求和方案可直接复用;已有授权覆盖的工作持续推进,不用在每个 skill 边界再次确认。 dev-spec 只保留兼容触发,实际按 dev-grill-docs --spec-only 执行,不会写 CONTEXT.md / ADR。 dev-fix 与 dev-grill-docs 是平行入口 —— 需要梳理的新需求走 dev-grill-docs,bug 报告走 dev-fix。feature / hotfix / refactor 的直接编码路径用 dev-tdd;bug 路径由 dev-fix 负责复现、根因修复和回归证据,之后在 dev-verify → dev-code-review 合流。 dev-auto 是可选入口推荐器,不调起任何 skill,只读 .claude/artifacts/ 推断当前 phase 并建议下一步。也支持 --status / --next / --recover。

必读文档(按顺序看,~25 分钟)

  1. README.md —— 整体结构 5 分钟。
  2. docs/sdd-workflow.md —— SDD 在 workflow 和 multi-agent 里的接法 5 分钟。
  3. references/dev-baseline.md —— 四条基线原则 5 分钟。
  4. docs/why-dev-baseline.md —— 每条原则背后的失败模式 5 分钟。
  5. CLAUDE.md.template 或 AGENTS.md.template —— 短版 always-on 规则 5 分钟(注意:需复制到项目根并改名才生效)。
  6. 你日常会用的 skill 的 SKILL.md(选你感兴趣的一个先读) —— 5 分钟。

后续按需查阅:

  • docs/team-policy.md —— 分支 / PR / 测试 / 错误处理 / 日志等详细团队治理参考。
  • docs/multi-agent-policy.md —— 支持多 agent runtime 时的分工、ownership、verifier / reviewer 协议。
  • references/team-conventions.md —— 写到具体语言时查。
  • skills/dev-code-review/references/lang-conventions.md —— 跨语言通用规范(dev-code-review 专属)。
  • references/calibration-cases.md —— 检查触发路由、关键缺口、已授权续做、独立评审和验证证据边界;将用例输入与预期观察分开执行。按需参考结果观察与下游项目 DORA 观察,不增加必填记录。
  • node scripts/calibrate-skills.mjs list —— 查看已落地的离线校准场景;prepare 创建独立临时工作区,交给 agent 实际执行后再 check。仓库 CI 检查运行器自身,Agent 行为结论还需独立检查实际回答与操作证据。
  • skills/dev-verify/references/project-verification.md —— 项目验证方法需要反复复用时查阅;优先使用现有脚本和测试,不要求每次验证都新建文档。

Multi-agent 使用说明

如果你的工具支持多 agent,先把它当成高级模式使用,不要让 skill 自动互相调用。

推荐分工:

  • 主 agent:负责用户沟通、拆分任务、最终整合、git 操作和完成声明。
  • explorer:查调用链、类似实现、设计系统和约定。
  • worker:只改明确分配的文件或模块,并对照任务契约交付相应验证证据。
  • verifier:独立跑验证命令,对照任务契约检查完成声明是否有证据。
  • reviewer:独立看 diff,对照需求和相关 spec / ADR / fix artifact 做提交前判断,不参与实现。

使用前先读 docs/sdd-workflow.md 和 docs/multi-agent-policy.md。委派须符合用户授权或适用规则;子 agent 的任务要写清楚 objective、source requirement / artifact、write scope、do-not-edit、verification expected 和 output required。简单任务可直接引用当前请求,不用另造文档。

常见 pitfall(踩坑预警)

「Claude 报了一堆 P2,我都要修吗?」 不。P2 是可选的,你可以选择不修但要在 PR 里一句话解释(例如「P2 注释问题暂不处理,本 commit 仅修 bug」)。P0 / P1 必须处理。

「Claude 说 ❌ BLOCK 但我觉得没问题」 两步走:(1) 确认你不是漏看了 baseline / CLAUDE.md / AGENTS.md 的某条硬规则(尤其 secret / 闭环);(2) 如果你确信 skill 判错了,在 PR 里覆盖判定 + 解释,然后开 issue 反馈这个 case。

「skill 没识别出我用的语言怎么办?」 skills/dev-code-review/references/lang-conventions.md 里有「其他语言」段落兜底。如果你常用某语言但 conventions 不全,提 PR 补。

「我的改动跨了 5 个文件,review 报告太长」 先看改动是否服务同一意图、这些文件是否都是必要范围,以及结果能否独立验证。一次行为变更可能同时涉及实现、调用方、持久化、文案和测试,文件数不能直接证明 scope creep。只有混入可独立交付的其他意图时才拆分;review 报告应聚焦真实问题和验证缺口。

「我上传到团队仓库的 skill 设置,别人看不到」 确认你 commit 的是 skill 仓库本身,而不是消费 skill 的项目。skill 安装路径在 ~/.claude/skills/,不进版本控制。

出问题找谁

问题类型 找谁
安装 / 工具相关 团队群提问
规则有 bug / 误判 开 issue
想加新 skill 先看 CONTRIBUTING.md,然后开 issue
紧急(线上事故牵涉到 skill 输出) 直接联系 leader,事后再走流程

第一周建议

  • 至少跑 3 次 dev-code-review,熟悉报告格式。
  • 至少跑 1 次 dev-grill-docs,体验需求拷问和 spec artifact 生成(很多人这一步会「啊原来我没想清楚」)。旧提示里的 dev-spec 仍可用,但只是 spec-only 兼容入口。
  • 找一份可访问的 Swagger/OpenAPI/Knife4j 文档跑 1 次 swagger-doc-skill,分别查看模块、接口和完整类型定义;需要交付时再导出 Markdown / JSON。
  • 把 references/calibration-cases.md 的 case 自己跑一遍,对照 canonical answer,这是最快内化 baseline 的方式。

卡住超过 30 分钟一定要问。规范是为了减少摩擦,不是制造摩擦。