Skip to content
Back to search

dev-team

SkillWorks with Claude CodeGitHub

组建一个分工明确的虚拟研发团队来推进软件项目。九个角色:项目经理、产品经理、交互设计师、架构师、开发工程师、测试工程师、安全工程师、技术文档工程师、评审者。覆盖需求、设计、架构、开发、测试、安全、交付全流程,支持多个子 agent 并发协作。当用户要新建项目、加功能、改架构、修复杂 bug、做技术方案,或明确要求"用研发团队/多角色/分工协作"的方式推进时使用。启用前必须先向用户确认。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ancanglee--dev-team-skill/badge.svg)](/listings/ancanglee--dev-team-skill)

HTML

<a href="/listings/ancanglee--dev-team-skill"><img src="/api/listings/ancanglee--dev-team-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

3.1 Prerequisites

- Claude Code, as CLI, desktop app, or IDE extension. This is the reference implementation; section 3.6 covers other tools. - bash - git in the target project is better, but not required.

3.2 User-level install (available in every project)

From the skill directory:

bash scripts/install.sh

It does two things: links the skill to `~/.claude/skills/dev-team` and the nine roles to `~/.claude/agents/`. Anything already installed is skipped, not duplicated.

To run it from elsewhere, use a relative path (adjust to where you actually keep the directory):

bash ../dev-team-skill/scripts/install.sh

The script derives the skill directory from its own location, so you don't pass a path. What it creates are symlinks into that directory. If you move the skill directory later, rerun the install.

Running it again is safe. If a file or a link to somewhere else already has the same name, the script skips it and says so. It won't overwrite your files.

3.3 Project-level install (this project only)

Two forms. Pick the one that matches where you are.

From the skill directory, name the project:

bash scripts/install.sh --project ../my-project

Or install into the current directory:

cd ../my-project
bash ../dev-team-skill/scripts/install.sh --project

The `../my-project` and `../dev-team-skill` above are examples; use your real directory names.

This creates `<project>/.claude/skills/dev-team` and `<project>/.claude/agents/`. Good for teams sharing one setup: commit both `.claude/` and the skill directory, and everyone who clones it is ready. Skill directories can live at different paths on different machines, so putting it in the repo or at a fixed path is your best bet.

3.4 Verify

1. Restart Claude Code. 2. Type `/agents`. You should see all nine roles. 3. Say "use the dev-team to build me a todo app". It should hand you a proposal first, not start writing code.

Skill-only works too, without the agents. The orchestration layer falls back to `general-purpose` and pastes the role definition into the prompt. The difference is no separate tool restrictions or descriptions, and coarser parallel scheduling.

3.5 Installing on another machine

Copy the whole directory over, enter it, and run the same script:

cd dev-team-skill   # use your actual directory name
bash scripts/install.sh

3.6 Using it in other tools (Codex, Cursor, DeepSeek, and friends)

The skill is plain Markdown. Role scope, phases, gates, and templates don't depend on Claude Code. Claude Code is just the reference implementation, and the install scripts only cover its directories. Moving to another harness starts with knowing what travels:

| Part | Portable? | Notes | |---|---|---| | Role definitions, process, templates, scope rules | Yes | Plain text; any tool that can read files can use them | | Auto-trigger, `/dev-team` command | Depends on the tool | Without a skill mechanism, put SKILL.md in the project instructions or system prompt | | Multi-role parallelism | Depends on the tool | If it has subagents, split by role; if not, play the roles sequentially in one session | | Agent frontmatter (tools, model) | No | Claude Code's format; other tools ignore it, so rewrite it per tool | | install / uninstall scripts | No | They only handle `~/.claude` and the project's `.claude/` |

The generic wiring is four steps:

1. Put the whole directory into the project, e.g. `.dev-team/`. 2. Tell the tool to read the entry point. Either add an `AGENTS.md` at the project root (Codex and similar) or `.cursor/rules/dev-team.mdc` (Cursor), or just say "read .dev-team/SKILL.md first" at the start of a session. The entry point needs three things: read `SKILL.md` and `references/roles-and-scope.md`; read `agents/<role>.md` when a role is needed; write outputs to the docs root (`docs/` by default, `docs/dev-team/` for existing projects). 3. Assign roles according to the tool's concurrency:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 255 lines
  1. ---
  2. name: dev-team
  3. version: 1.0.0
  4. description: 组建一个分工明确的虚拟研发团队来推进软件项目。九个角色:项目经理、产品经理、交互设计师、架构师、开发工程师、测试工程师、安全工程师、技术文档工程师、评审者。覆盖需求、设计、架构、开发、测试、安全、交付全流程,支持多个子 agent 并发协作。当用户要新建项目、加功能、改架构、修复杂 bug、做技术方案,或明确要求"用研发团队/多角色/分工协作"的方式推进时使用。启用前必须先向用户确认。
  5. ---
  6. # 研发团队(dev-team)
  7. 九个角色分工推进软件项目。职责边界、产出物、Gate、并发规则、冲突仲裁全在 `references/roles-and-scope.md`,遇到分歧以那份文档为准。本文件只讲怎么把角色编排起来。
  8. ## 0. 先判断两件事
  9. ### 0.1 规模
  10. 不是所有任务都需要开会。先判规模:
  11. | 规模 | 特征 | 启用 |
  12. |---|---|---|
  13. | 小 | 单模块、几天内、无外部依赖 | 项目经理 + 开发 + 测试(架构师按需) |
  14. | 中 | 多模块,需要前后端或并行开发 | 主要角色,可按 `references/roles-and-scope.md` 第 7 节的规则兼岗 |
  15. | 大 | 多端、多模块、有安全合规或交付要求 | 九个角色全部启用,按波次并发 |
  16. 不适用:一行改动、纯问答、查资料、只需要一个意见。这些直接做,不要走流程。
  17. ### 0.2 项目类型
  18. | 类型 | 判断依据 | 起点 |
  19. |---|---|---|
  20. | 新项目 | 空目录,或只有空骨架 | 立项 |
  21. | 已有项目 | 有可运行的代码、构建配置,或别人留下的文档 | 现状盘点 |
  22. 已有项目的三条铁律:
  23. - 不改动既有目录结构,不移动、不重命名已有文件。
  24. - 不按本 skill 的偏好重排项目。产出写进自己的文档根,不污染原结构。
  25. - 先跑通现有构建和测试,再动手改。
  26. ## 1. 启动前必须确认
  27. ### 1.1 新项目
  28. 给用户一页提案,等确认后再动手。提案不长,五项:
  29. ```
  30. 目标:<一句话>
  31. 范围:做 <...>;不做 <...>
  32. 角色:<启用哪些,为什么>
  33. 阶段:<需求 → 设计 → 架构 → 开发 → 测试 → 安全 → 交付 → 发布>,停在需求冻结 / 架构冻结 / 发布前
  34. 产出:<文档根下的目录与关键文件>
  35. 主要风险或不确定项:<...>
  36. ```
  37. 用户确认前不建文档、不写代码。用户提出调整,更新提案再确认一次。
  38. ### 1.2 已有项目
  39. 先盘点,再提案,只确认一次。
  40. 盘点由架构师主导,测试和安全补充,产出 `<文档根>/07-project/audit.md`(模板 `references/templates/project-audit.md`),至少覆盖:
  41. - 项目做什么,技术栈是什么
  42. - 构建、运行、测试命令能不能真的跑通
  43. - 目录与模块边界,实际结构和文档写的是否一致
  44. - 现有文档在哪,哪些可信、哪些过期
  45. - 测试现状:有没有测试,现在是不是绿的
  46. - 部署方式与环境
  47. - 技术债和已知风险
  48. - 与本 skill 规范的差距。记下来,不要求一次补齐
  49. 盘点完确定文档根:
  50. - 项目没有 `docs/`,或 `docs/` 是空的 → 用 `docs/`
  51. - 项目已有 `docs/` 且结构不同 → 用 `docs/dev-team/`,原 `docs/` 一个字不动
  52. - 用户指定位置 → 听用户的
  53. 把选择写进 audit.md 的「文档根约定」一节,后续所有产出都相对这个根。
  54. 然后给迭代提案(模板 `references/templates/iteration-brief.md`)。内容同 1.1,另外加两项:影响哪些模块、怎么回滚。用户确认后进入正常流程,只覆盖本次变更范围。
  55. 盘点结论和迭代提案合并成一次确认,不额外加停点。
  56. ## 2. 初始化
  57. 在目标项目根目录运行:
  58. ```bash
  59. bash <skill-dir>/scripts/init-docs.sh <项目根>
  60. ```
  61. 已有项目用独立文档根,不动原目录:
  62. ```bash
  63. bash <skill-dir>/scripts/init-docs.sh <项目根> --docs-dir docs/dev-team
  64. ```
  65. 脚本只创建目录和 `<文档根>/README.md`,已存在的文件一律不覆盖。项目已有 `docs/` 结构时直接复用,或换到独立根,不要重排。
  66. 派第一个角色之前,先通读 `references/roles-and-scope.md`。角色的职责边界、决策权、仲裁规则都以它为准,不要凭印象分配。
  67. ## 3. 角色与调用方式
  68. 角色定义在 `agents/<role>.md`。调用时优先用已安装的角色 agent:
  69. ```
  70. Agent(
  71. description: "架构师 · 后端架构",
  72. subagent_type: "architect",
  73. prompt: "..."
  74. )
  75. ```
  76. 同名 agent 不存在时,用 `general-purpose`,prompt 开头贴上 `agents/<role>.md` 全文,并说明"你现在是这个角色"。
  77. 每次 spawn 的 prompt 必须包含七项:
  78. 1. 角色与本次任务
  79. 2. 必读输入(文件路径,含契约)
  80. 3. 产出(文件路径 + 使用的模板)
  81. 4. 约束(只能改哪些文件、不能做什么)
  82. 5. 完成标准(对应角色的 DoD)
  83. 6. 回报格式(产出、验证、偏差、风险、阻塞)
  84. 7. 失败预算与停止条件:同一错误连续两次即停,单任务最多三次尝试
  85. 子 agent 之间不口头传话,只通过文件交接。下游读不到上游产出时,写进报告的偏差里,不要自己补。
  86. prompt 里带上 skill 目录的绝对路径,子 agent 读 `references/roles-and-scope.md` 时才有依据。
  87. ## 4. 阶段与波次
  88. 新项目从立项开始;已有项目先做现状盘点(第 0 波),再按同一张表推进。两种情况下,每个阶段都只覆盖本次范围,不是重做整个项目。
  89. | 阶段 | 主导 | 产出 | 是否停 |
  90. |---|---|---|---|
  91. | 立项 | 项目经理 | 项目章程 | 自动 |
  92. | 需求 | 产品经理 | PRD、验收标准、NFR | 用户确认(需求冻结) |
  93. | 设计 | 交互设计师 | 交互流程、原型、状态矩阵、视觉规范 | 自动 |
  94. | 架构 | 架构师 | 架构文档、ADR、接口契约、模块划分 | 用户确认(架构冻结) |
  95. | 开发 | 开发工程师 | 代码、单测、自测记录 | 自动 |
  96. | 测试 | 测试工程师 | 测试报告、缺陷分级 | 自动 |
  97. | 安全 | 安全工程师 | 安全报告、高危清零 | 自动,高危即停 |
  98. | 交付 | 技术文档工程师 | 交付手册、测试/部署/排障手册 | 自动 |
  99. | 发布 | 项目经理 + 用户 | 发布说明、回滚预案 | 用户确认(发布前) |
  100. ### 并发规则
  101. - 同一波次内能并行就并行,下一波等上一波文件落盘。按依赖分层,不要一次放出所有 agent。
  102. - 契约先行。接口、数据结构、组件边界冻结后才开开发波次,否则并行度越高返工越多。
  103. - 单写者。同一文件同一时刻只有一个 agent 写。共享文件(路由表、依赖清单、设计 token、配置文件)由 owner 统一改。
  104. - 每个子 agent 只读契约和自己的输入,只写自己的产出文件。
  105. - 波次结束由主流程核对:产出文件是否存在、是否符合模板、契约有没有被擅自修改。
  106. 中型项目的典型波次:
  107. 1. 产品拆模块 → 并行写 PRD 章节 → 产品统稿
  108. 2. 交互设计按页面并行;架构按端并行(移动端、前端、后端、数据、网络、基础设施)
  109. 3. 架构师串行汇总:定契约、定模块边界 → 架构冻结
  110. 4. 开发按模块并行;测试用例并行设计;安全威胁建模并行
  111. 5. 架构师串行集成;测试执行与回归
  112. 6. 安全评审与修复;文档各部分并行编写
  113. 7. 评审者扫描;交付走查;发布 gate
  114. ## 5. Gate 怎么处理
  115. 三个必停点:**需求冻结、架构冻结、发布前**。其余 Gate 由角色之间自动流转,结论写进文档。
  116. 三个停点前,先让评审者把待确认的产出扫一遍,报告随 Gate 一起交给用户。发布前的 Gate 还要附上安全结论和测试报告,缺一份都不算通过。
  117. 停下来时给用户:
  118. ```
  119. 【Gate:需求冻结】
  120. 完成:<关键产出与路径>
  121. 证据:<测试/评审结论、关键指标>
  122. 未决:<待确认项>
  123. 风险:<残余风险>
  124. 选项:A 通过 / B 修改后重审 / C 缩小范围
  125. ```
  126. 不是必停点但必须立刻停的情况:
  127. - 安全高危否决
  128. - 需求冲突或范围蔓延,超出已确认的 in / out
  129. - 两个角色结论互斥,仲裁规则覆盖不到
  130. - 用户要求暂停
  131. 不要用"我认为可以继续"替代用户确认。三个停点没有确认就不往下走。
  132. ## 6. 产出物
  133. 文档根固定(默认 `docs/`,已有项目可以用 `docs/dev-team/`),下面所有路径都相对文档根。详细清单见 `references/templates/README.md`:
  134. ```
  135. docs/
  136. 01-product/ prd.md user-flow.md
  137. 02-design/ interaction.md states.md ui-spec.md tokens.json prototype/
  138. 03-architecture/ architecture.md contracts.md api/ adr/ diagrams/
  139. 04-dev/ development-plan.md tech-debt.md
  140. 05-test/ test-plan.md cases.md report.md
  141. 06-security/ threat-model.md review.md
  142. 07-project/ charter.md plan.md risks.md decisions.md audit.md iteration.md blocked.md status/ reviews/
  143. 08-manual/ index.md overview.md usage.md test-manual.md deployment.md troubleshooting.md
  144. ```
  145. 每份文档开头三行:给谁看、解决什么问题、当前状态(草案 / 已确认 / 已废弃)。废弃的不删,标注替代它的文件。
  146. 流程、结构、状态、时序必须配图,图用 Mermaid 写在文档里,每张图配一句结论。不产出 draw.io、Visio 等二进制文件。
  147. 待决策的地方标「待确认」,列选项和建议,不要埋在正文里。
  148. ## 7. 并发冲突怎么收
  149. - 契约变更:走变更单,架构师批,相关下游任务暂停,等新契约明确再恢复。
  150. - 文件冲突:靠单写者规则预防,不靠事后合并。共享文件冲突由 owner 裁定。
  151. - 新依赖:暂停被依赖的任务,不硬并行。
  152. - 结论冲突:按 `references/roles-and-scope.md` 第 4.3 节的仲裁表处理。
  153. ## 8. 语言
  154. - 文档中文。代码注释、commit message、PR 描述英文。变量名、API 名、文件名英文。
  155. - 与用户对话中文,专业术语保留英文。
  156. ## 9. 收尾
  157. 全部 Gate 通过后:
  158. - 技术文档工程师交付 `08-manual/`;已有项目优先更新既有手册,没有才新建。测试按手册走一遍,安全检查敏感信息。
  159. - 项目经理输出结项摘要:交付了什么、遗留风险、后续建议。
  160. - 不自动 git commit 或 push,除非用户要求。
  161. - 不做用户没要求的发布、部署或外发动作。
  162. ## 10. 失败、重试与跳出
  163. 完整规则见 `references/loop-control.md`。三条硬规则:
  164. 1. 同一动作配同一错误,连续两次就停。第三次必须换方案,否则按死循环处理。
  165. 2. 单任务最多 3 次尝试;修 bug 最多 3 轮;评审返工最多 2 轮。到线就停。
  166. 3. 连续两次没有新产出、没有新增通过项、没有解决未知,算没有进展,停。
  167. 停下时做四件事:
  168. - 不启动依赖该任务的下游角色。
  169. - 写阻塞报告到 `<文档根>/07-project/blocked.md`,模板 `references/templates/blocked-report.md`。
  170. - 向用户显式报告:哪项没完成、试过什么、卡在哪、需要谁决定、有哪些选项。
  171. - 把阻塞项写进状态报告和未完成清单,不要藏在总结里。
  172. 禁止用「继续尝试」代替停止,也禁止把失败说成基本完成。下游角色不得替上游补产出或猜结论。
  173. ## 11. 每波结束的自检
  174. - 产出文件存在,符合模板,有状态标记
  175. - 契约没被未经批准地改动
  176. - 每个未完成项都有 owner 和下一步
  177. - 没有静默失败:未完成项要么有 owner,要么已写进 blocked.md
  178. - 需要用户决策的事项已经列出来,没有被静默跳过
  179. - 已有项目:原目录结构没被动过,现有构建和测试跑通
README.md · README · 352 lines
  1. # dev-team
  2. **English** | [中文](README.zh-CN.md)
  3. A virtual R&D team for AI coding tools. Nine roles, a staged process for software projects, and multiple subagents running in parallel. New projects start at kickoff; existing projects get audited first. The reference implementation is Claude Code — other tools are covered in section 3.6.
  4. This guide covers install, usage, and troubleshooting.
  5. ## 1. What it does
  6. Hand it a development task and it will:
  7. - Give you a one-page proposal first (goal, scope, roles, phases, deliverables). Nothing starts until you confirm.
  8. - Move through requirements → design → architecture → development → testing → security → delivery → release.
  9. - Stop for you at three points only: requirements freeze, architecture freeze, pre-release.
  10. - Parallelize where it can. Several developers on different modules, or the architect running front-end and back-end architecture subtasks at once.
  11. - For an existing project, audit what's there before changing anything, then iterate within the change scope without touching the original directory layout.
  12. - Stop itself when stuck. Same error twice, or three attempts on one task, and it writes a blocked report rather than retrying forever.
  13. - Write deliverables to the project's docs root (`docs/` by default; existing projects often use `docs/dev-team/`), and hand over a human-facing manual at delivery.
  14. What it won't do: make business decisions for you, accept security risk on your behalf, or run git commit and deploy.
  15. ## 2. Layout
  16. ```
  17. dev-team-skill/
  18. ├── SKILL.md Orchestration entry: kickoff, waves, gates, output rules
  19. ├── README.md This file (English)
  20. ├── README.zh-CN.md Chinese version
  21. ├── LICENSE Apache License 2.0
  22. ├── NOTICE Attribution notice
  23. ├── agents/ Nine role definitions
  24. │ ├── project-manager.md
  25. │ ├── product-manager.md
  26. │ ├── interaction-designer.md
  27. │ ├── architect.md
  28. │ ├── developer.md
  29. │ ├── test-engineer.md
  30. │ ├── security-engineer.md
  31. │ ├── tech-writer.md
  32. │ └── red-team.md
  33. ├── references/
  34. │ ├── roles-and-scope.md Single source of truth for role scope, gates, arbitration, boundaries
  35. │ ├── loop-control.md Failure budgets, retry caps, breakout protocol
  36. │ └── templates/ 17 document templates
  37. └── scripts/
  38. ├── init-docs.sh Set up the docs/ skeleton in a project
  39. ├── install.sh One-command install
  40. └── uninstall.sh One-command uninstall
  41. ```
  42. ## 3. Install
  43. ### 3.1 Prerequisites
  44. - Claude Code, as CLI, desktop app, or IDE extension. This is the reference implementation; section 3.6 covers other tools.
  45. - bash
  46. - git in the target project is better, but not required.
  47. ### 3.2 User-level install (available in every project)
  48. From the skill directory:
  49. ```bash
  50. bash scripts/install.sh
  51. ```
  52. It does two things: links the skill to `~/.claude/skills/dev-team` and the nine roles to `~/.claude/agents/`. Anything already installed is skipped, not duplicated.
  53. To run it from elsewhere, use a relative path (adjust to where you actually keep the directory):
  54. ```bash
  55. bash ../dev-team-skill/scripts/install.sh
  56. ```
  57. The script derives the skill directory from its own location, so you don't pass a path. What it creates are symlinks into that directory. If you move the skill directory later, rerun the install.
  58. Running it again is safe. If a file or a link to somewhere else already has the same name, the script skips it and says so. It won't overwrite your files.
  59. ### 3.3 Project-level install (this project only)
  60. Two forms. Pick the one that matches where you are.
  61. From the skill directory, name the project:
  62. ```bash
  63. bash scripts/install.sh --project ../my-project
  64. ```
  65. Or install into the current directory:
  66. ```bash
  67. cd ../my-project
  68. bash ../dev-team-skill/scripts/install.sh --project
  69. ```
  70. The `../my-project` and `../dev-team-skill` above are examples; use your real directory names.
  71. This creates `<project>/.claude/skills/dev-team` and `<project>/.claude/agents/`. Good for teams sharing one setup: commit both `.claude/` and the skill directory, and everyone who clones it is ready. Skill directories can live at different paths on different machines, so putting it in the repo or at a fixed path is your best bet.
  72. ### 3.4 Verify
  73. 1. Restart Claude Code.
  74. 2. Type `/agents`. You should see all nine roles.
  75. 3. Say "use the dev-team to build me a todo app". It should hand you a proposal first, not start writing code.
  76. Skill-only works too, without the agents. The orchestration layer falls back to `general-purpose` and pastes the role definition into the prompt. The difference is no separate tool restrictions or descriptions, and coarser parallel scheduling.
  77. ### 3.5 Installing on another machine
  78. Copy the whole directory over, enter it, and run the same script:
  79. ```bash
  80. cd dev-team-skill # use your actual directory name
  81. bash scripts/install.sh
  82. ```
  83. ### 3.6 Using it in other tools (Codex, Cursor, DeepSeek, and friends)
  84. The skill is plain Markdown. Role scope, phases, gates, and templates don't depend on Claude Code. Claude Code is just the reference implementation, and the install scripts only cover its directories. Moving to another harness starts with knowing what travels:
  85. | Part | Portable? | Notes |
  86. |---|---|---|
  87. | Role definitions, process, templates, scope rules | Yes | Plain text; any tool that can read files can use them |
  88. | Auto-trigger, `/dev-team` command | Depends on the tool | Without a skill mechanism, put SKILL.md in the project instructions or system prompt |
  89. | Multi-role parallelism | Depends on the tool | If it has subagents, split by role; if not, play the roles sequentially in one session |
  90. | Agent frontmatter (tools, model) | No | Claude Code's format; other tools ignore it, so rewrite it per tool |
  91. | install / uninstall scripts | No | They only handle `~/.claude` and the project's `.claude/` |
  92. The generic wiring is four steps:
  93. 1. Put the whole directory into the project, e.g. `.dev-team/`.
  94. 2. Tell the tool to read the entry point. Either add an `AGENTS.md` at the project root (Codex and similar) or `.cursor/rules/dev-team.mdc` (Cursor), or just say "read .dev-team/SKILL.md first" at the start of a session. The entry point needs three things: read `SKILL.md` and `references/roles-and-scope.md`; read `agents/<role>.md` when a role is needed; write outputs to the docs root (`docs/` by default, `docs/dev-team/` for existing projects).
  95. 3. Assign roles according to the tool's concurrency:
  96. - With subagents: treat `agents/*.md` as each role's system prompt and dispatch waves as SKILL.md describes.
  97. - Without them: play the roles one at a time in a single session and reread the role file before switching. Roles hand off through files under the docs root, not through conversational memory.
  98. 4. Gates, stop points, and output structure stay as they are. None of that depends on the tool.
  99. A startup prompt you can copy:
  100. ```
  101. Read .dev-team/SKILL.md and .dev-team/references/roles-and-scope.md.
  102. Run this project the dev-team way: give me the kickoff proposal first, and wait for my confirmation before starting.
  103. When a role is needed, read .dev-team/agents/<role>.md and follow its scope, outputs, and report format exactly.
  104. Play one role at a time, and hand off between roles through files under the docs root.
  105. ```
  106. Two caveats:
  107. - Support for subagents, rule files, and slash commands varies across Codex, Cursor, and DeepSeek harnesses, and shifts between versions. This guide guarantees the content is portable; the actual wiring follows whatever the current tool documents. Don't assume `agents/*.md` will be picked up automatically.
  108. - Concurrency is where the difference bites hardest. Tools without subagents can only go serially, so waves have to be pushed along by hand. More effort, same process and outputs.
  109. ## 4. First run
  110. ```
  111. You: Use dev-team to build me a team weekly-report system.
  112. Claude:
  113. 【Kickoff proposal】
  114. Goal: let a 5–10 person team submit and read weekly reports
  115. Scope: build submit, view, remind; skip the permission system and mobile
  116. Roles: project manager, product manager, architect, developer, tester, tech writer
  117. Phases: requirements → design → architecture → development → testing → delivery → release
  118. Stop points: requirements freeze, architecture freeze, pre-release
  119. Deliverables: PRD, architecture, test report, delivery manual under docs/
  120. Risks: weekly reports carry sensitive data, so a security review is needed; the reminder feature depends on a third-party service
  121. You: Confirmed, but add a security review and build the permission system.
  122. Claude: (updates the proposal) ... starts after you confirm.
  123. ```
  124. Once work starts, it will:
  125. 1. Create the docs root (`docs/` for a new project, `docs/dev-team/` for an existing one)
  126. 2. Dispatch the product manager to write the PRD
  127. 3. Stop and ask you at requirements freeze
  128. 4. Move architecture and development forward in waves
  129. 5. Hand over a human-facing manual in `docs/08-manual/`
  130. ## 5. How a project moves
  131. | Phase | Lead | Output | Stops? |
  132. |---|---|---|---|
  133. | Kickoff | Project manager | Project charter | Auto |
  134. | Requirements | Product manager | PRD, acceptance criteria, NFRs | Stop (requirements freeze) |
  135. | Design | Interaction designer | Flows, prototype, state matrix | Auto |
  136. | Architecture | Architect | Architecture doc, interface contracts, module split | Stop (architecture freeze) |
  137. | Development | Developers | Code, unit tests, self-test notes | Auto |
  138. | Testing | Test engineer | Test report, defect severity | Auto |
  139. | Security | Security engineer | Security report, high-severity issues cleared | Auto; stops on any high-severity finding |
  140. | Delivery | Tech writer | Delivery, deployment, and troubleshooting manuals | Auto |
  141. | Release | Project manager + you | Release notes, rollback plan | Stop (pre-release) |
  142. At a stop point you get: what's done, where the evidence is, what's still open, residual risk, and three options A/B/C. It won't move on without your confirmation.
  143. ### Existing projects
  144. One extra step of audit up front, fewer changes afterward:
  145. 1. **Audit.** The architect, with testing and security, reads the code, runs the build and tests, and checks existing docs. Output goes to `07-project/audit.md`. Read-only: your directories stay untouched.
  146. 2. **Pick the docs root.** If the project already has a `docs/` with a different structure, dev-team output goes to `docs/dev-team/` and the original `docs/` is left alone.
  147. 3. **Iteration proposal.** What this round does, which modules it touches, how it's accepted, how it rolls back — confirmed once, together with the audit findings.
  148. 4. **Same table from there.** Each phase covers only the change scope: requirements describe the impact surface, architecture covers the delta, testing carries a regression scope.
  149. ### When it gets stuck
  150. The same action producing the same error twice stops it. One task gets at most three attempts, review rework at most two rounds, and two consecutive rounds without progress also count as stuck. It doesn't push through — it writes `07-project/blocked.md` with unfinished items, attempts made, evidence, and the options it sees, and hands that to you.
  151. ## 6. Roles
  152. | Role | When it joins | Main outputs |
  153. |---|---|---|
  154. | Project manager | Throughout | Charter, plan, risks, status reports, decision log |
  155. | Product manager | Requirements, and later change requests | PRD, acceptance criteria, non-goals |
  156. | Interaction designer | After requirements freeze | User flows, state matrix, HTML/CSS prototype, design tokens |
  157. | Architect | After requirements freeze; also tech owner and lead code reviewer | Architecture doc, ADRs, interface contracts, module boundaries, review verdicts |
  158. | Developer | After contracts freeze; multiple instances in parallel | Code, unit tests, module notes |
  159. | Test engineer | After requirements freeze (test cases run alongside development) | Test plan, cases, automation, test report |
  160. | Security engineer | Joins at the architecture phase | Threat model, security reviews, release checks |
  161. | Tech writer | Delivery phase | Five docs: delivery, usage, testing, deployment, troubleshooting |
  162. | Red team | Three key checkpoints | Review reports, list of unverified assumptions |
  163. Roles can be merged for smaller projects. The rules are in section 7 of `references/roles-and-scope.md`. Three lines can't be crossed: developers can't accept their own work, whoever splits the modules can't also own the integration acceptance, and the red team stays independent.
  164. ## 7. What you control
  165. - **Stop points**: requirements freeze, architecture freeze, pre-release. Everything else flows automatically, with results written to docs you can read later.
  166. - **Interrupt any time**: "pause" prints the current state and next step; "switch roles" reassigns work.
  167. - **Change the scale**: say "this is a small project, don't bring everyone" and it drops to 2–3 roles.
  168. - **Change the stop points**: say "no need to wait for me at architecture" and it complies. For a lasting change, see section 9.
  169. - **Reject**: every gate has a "revise and re-review" option.
  170. - **Kill a stuck task**: say "stop, write a blocked report" and it stops retrying and gives you options.
  171. ## 8. Where outputs go
  172. `docs/` for new projects; `docs/dev-team/` is recommended for existing ones. Paths below are relative to the docs root.
  173. ```
  174. docs/
  175. 01-product/ prd.md user-flow.md
  176. 02-design/ interaction.md states.md ui-spec.md tokens.json prototype/
  177. 03-architecture/ architecture.md contracts.md api/ adr/ diagrams/
  178. 04-dev/ development-plan.md tech-debt.md
  179. 05-test/ test-plan.md cases.md report.md
  180. 06-security/ threat-model.md review.md
  181. 07-project/ charter.md plan.md risks.md decisions.md audit.md iteration.md blocked.md status/ reviews/
  182. 08-manual/ index.md overview.md usage.md test-manual.md deployment.md troubleshooting.md
  183. ```
  184. Initialize an existing project:
  185. ```bash
  186. bash scripts/init-docs.sh <project-root> --docs-dir docs/dev-team
  187. ```
  188. - Start each document with: who reads it, what problem it solves, and status (draft / confirmed / deprecated).
  189. - Flow, architecture, and state diagrams go in the doc as Mermaid, so they get reviewed with the code.
  190. - You can create the directory structure with `bash scripts/init-docs.sh <project-root>`. The script never overwrites existing files.
  191. ## 9. Customizing
  192. | What you want to change | Where | Watch out |
  193. |---|---|---|
  194. | Role scope | `references/roles-and-scope.md` and `agents/<role>.md` | Keep both in sync; the former is the authority, the latter is execution |
  195. | Orchestration, waves, gates | `SKILL.md` | Don't redefine scope in SKILL.md; point back to the role files |
  196. | Document templates | `references/templates/` | After editing, check the paths referenced in SKILL.md and the agent files |
  197. | Language | Section 8 of `SKILL.md` and each agent file | Doc language and code-comment language are specified separately |
  198. | Stop points | Section 5 of `SKILL.md` | Fewer stops, more risk; more stops, less throughput |
  199. | Directory structure | `scripts/init-docs.sh`, section 6 of `SKILL.md`, template index | Change all three together |
  200. Upgrading: the skill directory is a symlink, so file edits take effect immediately. Restart the session. If you've customized role files, keep your own copy somewhere to avoid losing it in a future update.
  201. ## 10. FAQ
  202. **Q: Why didn't it trigger automatically?**
  203. Skills match on their description. Say "run this project with the dev-team", or type `/dev-team`.
  204. **Q: Does a small change really need nine roles?**
  205. No. It judges the scale first, and you can say it's a small project and keep only what's needed.
  206. **Q: I just want one role to do something.**
  207. Name it: "have the architect review this design". No need to run the whole process.
  208. **Q: The role agents aren't working.**
  209. Check `ls ~/.claude/agents/` — all nine files should be there and the symlinks intact (`readlink` shows the real path). Then restart Claude Code. Without the agents, the skill falls back to `general-purpose`: usable, less strict.
  210. **Q: Multiple agents changed the same file and conflicted.**
  211. The orchestration layer prevents this with a single-writer rule: one agent writes a given file at a time, and shared files are edited by their owner. If conflicts still happen, the module boundaries were cut badly — have the architect redraw them.
  212. **Q: The project already has a docs/ directory.**
  213. The init script doesn't overwrite existing files. You can reuse the directory; if the naming differs, tell Claude to follow the existing structure.
  214. **Q: Token usage is high.**
  215. Parallelism costs money. Shrink the scale, use fewer roles, or run just one phase. Skip the full review on small projects.
  216. **Q: The delivery manual doesn't match the code.**
  217. The manual requires every step to be verified for real. If you find a mismatch, have the tech writer rerun that step. If the code itself is wrong, route it to the owner — don't patch the manual to paper over it.
  218. **Q: Can I use it for non-software projects?**
  219. Not really. Roles, contracts, and tests are designed around software development; forcing them elsewhere gets awkward.
  220. **Q: Is it safe? Aren't the permissions too broad?**
  221. The developer, tester, security, and tech writer roles have Bash access, so they can run builds and tests. You'll be asked to approve commands on first run — read each one. Don't put production credentials in the session, and don't run it in a directory without backups.
  222. **Q: Can it get stuck in a loop?**
  223. It has hard budgets: the same action with the same error twice stops it, one task gets at most three attempts, review rework at most two rounds, and two consecutive no-progress rounds also count as stuck. At the limit it writes `07-project/blocked.md` and hands you the unfinished items and options. No endless retries.
  224. **Q: I already have a project whose layout differs from this skill. Do I need to restructure it?**
  225. No. It reads the code, runs the build and tests, audits existing docs, and writes `07-project/audit.md`. Documentation goes into a separate `docs/dev-team/`; the original directory is never moved or renamed. After that it only iterates within the current change scope.
  226. **Q: Can I use it in Cursor, Codex, or DeepSeek?**
  227. Yes, but the install scripts only cover Claude Code. Wire other tools by hand as described in 3.6; the tools and model fields in the role files need rewriting for each tool's mechanism.
  228. ## 11. Uninstall
  229. From the skill directory:
  230. ```bash
  231. bash scripts/uninstall.sh
  232. ```
  233. Project-level:
  234. ```bash
  235. bash scripts/uninstall.sh --project ../my-project
  236. ```
  237. The script only removes symlinks that point at this skill. Same-named files that aren't symlinks stay, with a notice. Generated `docs/` and your code are untouched.
  238. Those scripts only handle Claude Code's two directories. For other tools, delete the `.dev-team/` you placed in the project and the rule file you added.
  239. If the skill directory is already gone, the script is gone with it. Clean up the two locations by hand:
  240. ```bash
  241. rm ~/.claude/skills/dev-team
  242. rm ~/.claude/agents/{project-manager,product-manager,interaction-designer,architect,developer,test-engineer,security-engineer,tech-writer,red-team}.md
  243. ```
  244. ## 12. Limits
  245. - Subagents don't share conversational memory; they hand off through files. So the quality of each artifact decides whether the next stage can pick it up.
  246. - Parallelism is bounded by model rate limits and cost. Don't open a wave too wide.
  247. - Role judgment is model judgment, not real domain expertise. Security findings, compliance findings, and architecture decisions still need a human signature.
  248. - The delivery manual requires hands-on verification. Agents can't verify environments they can't reach and will flag that in the report; a human fills the gap.
  249. - In other tools, subagent parallelism and auto-triggering depend on the host. Outside this skill's control.
  250. - The audit of an existing project is based on code and current docs. Missing history can lead to wrong conclusions. Confirm the audit once before changes begin.
  251. - Budgets are hard limits but don't catch every dead end. If you see it spinning in place, call a stop.
  252. ## License
  253. Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.