一人 AI 软件公司 · Claude Code 插件架构设计

用 Claude Code Plugin 的标准格式,把「产品 → 设计 → 开发 → 测试 → 部署」全流程组织成一个有角色分工、可被自动调度的虚拟公司。

本文档定义架构、命名规范与全局约定 ,并与插件 hbteck-software-company/ 的实际实现保持同步。

当前状态:插件已整体落地 ------1 个 CTO 主线程(CLAUDE.md)+ 12 个命令 + 9 个子代理 + 11 个技能 + 4 个钩子 + MCP 接入均已就绪。后续以「在既有架子上迭代」为主。

一、核心心智模型:5 类组件 = 公司的 5 个层面

插件组件	对应公司角色	谁来触发	特点
`agents/`	员工花名册(每个专家)	Claude 自动派活或你点名	独立上下文,各司其职
`commands/`	老板的指令(你发话)	你手动 `/命令`	流程入口,一句话启动一个环节
`skills/`	公司 SOP / 规范手册	Claude 干活时自动查阅	渐进式加载,知识沉淀
`hooks/`	质检流水线的自动卡点	系统事件自动触发	强制执行,不可绕过
`.mcp.json`	接入的外部系统	工具调用	GitHub、数据库、云等

一句话总结:

commands 是「叫谁干」,agents 是「谁来干」,skills 是「按什么规矩干」,hooks 是「干完自动查」,mcp 是「用什么外部工具」。

贯穿全局的总原则:主线程只调度 + 读结论,重活一律丢子代理。

CTO(主线程)负责拆解、派活、读取各子代理回传的简短结论并拍板;通读产物、审查代码、跑测试等"重读重算"的活,一律交给独立上下文的子代理去做,只回传精简结果。这样主线程上下文始终精简、不被撑爆------这也是 Claude Code 子代理"隔离上下文"机制的核心价值。

二、命名规范

2.1 基础规则(硬性)

对象	规范	示例
所有目录 / 文件	kebab-case(小写 + 连字符),Claude Code 强制要求	`dev-backend.md`
插件名 `name`	kebab-case,全局唯一,会成为命令前缀	`hbteck-software-company`
frontmatter `name`	必须 kebab-case,≤ 64 字符	`name: qa-reviewer`

2.2 部门前缀(本项目统一约定)

所有 agents / commands / skills 一律以部门前缀开头,一眼看出归属:

部门	前缀	含义
产品部	`pd-`	Product
研发部	`dev-`	Engineering
质量部	`qa-`	Quality Assurance
运维部	`ops-`	Operations
通用 / 横向	`x-`	Cross-cutting

唯一例外 :cto 是顶层统领角色(你的唯一交互入口),不归属任何部门、不带前缀 ;且它不是子代理 ,而是主线程身份(落在 CLAUDE.md + /x-ship-it 命令,详见第四节)。

2.3 各类文件命名约定

类型	命名格式	示例	调用方式
agent	`<前缀>-<角色>.md`	`dev-backend.md`	自动派活 / 点名
command	`<前缀>-<动作>.md`	`dev-deploy.md`	`/hbteck-software-company:dev-deploy`
skill	`<前缀>-<主题>/`	`dev-backend-standards/`	自动加载 / `/skill`
skill 章节	`chapters/<单一主题>.md`	`chapters/prd-structure.md`	按需加载
skill 参考资料	`references/<主题>.md`	`references/分层结构.md`	按需加载(可中文名)
hook 脚本	`<时机>-<动作>.sh`	`pre-check-secrets.sh`	事件触发

chapters/ vs references/ :两者都用于「渐进式披露」的细节文件------chapters/ 放本插件自撰的拆分章节(kebab-case),references/ 放沉淀进来的既有规范/方言/组件清单(可保留中文文件名,如 达梦数据库设计规范.md)。SKILL.md 正文只放索引与最常用规则,细节按需引用。

2.4 产物命名与存放规范

解决"流程产物存哪、叫什么、怎么管版本"。所有流程产物统一放进项目的 docs/ 目录 (代码本身仍在 backend/、frontend/ 等代码目录,不进 docs)。

组织方式:功能优先,角色(阶段)其次 ------ docs/<功能>/<阶段>/<产物>。

为什么是「功能优先」而非「角色优先」:

一个功能从需求 → 设计 → 测试 → 部署是一条独立流水线 ,产物放一起,交接与回溯最顺(架构师读 docs/<功能>/01-pd/、写 docs/<功能>/02-design/,就近取材)。
若「角色优先」(顶层先分 01-pd/、02-design/、04-qa/),一个功能的故事会被打散到各顶层目录,看一个功能要四处翻。
「功能优先」便于按功能整体归档、版本对比,多功能并行互不干扰。

目录结构:

text 复制代码

docs/
├── _project/                       # 项目级(跨功能)文档,不属于某个具体功能
│   ├── overview.md                 #   项目总览 / 范围
│   ├── architecture.md             #   全局架构 + 统一语言(DDD 术语表)
│   └── conventions.md              #   全局约定(命名、技术栈等)
│
├── <功能名>/                      # 每个功能/需求一个目录;kebab-case,唯一且表意,如 user-auth(不加日期前缀)
│   ├── 01-pd/
│   │   └── prd.v1.md               #   pd-manager:需求 + 功能设计
│   ├── 02-design/
│   │   ├── architecture.v1.md      #   dev-architect:该功能架构设计
│   │   ├── api.v1.yaml             #   dev-architect:API 契约(OpenAPI)
│   │   └── db.v1.md                #   dev-database:库表设计(DDL/迁移脚本在代码库 migrations/)
│   ├── 03-dev/
│   │   ├── change-summary-be.v1.md #   dev-backend:后端变更摘要(代码在 backend/)
│   │   └── change-summary-fe.v1.md #   dev-frontend:前端变更摘要(代码在 frontend/，与 be 分文件避免并行覆盖)
│   ├── 04-qa/
│   │   ├── test-report.v1.md       #   qa-tester:测试 / 覆盖率报告
│   │   └── review-report.v1.md     #   qa-reviewer:代码 + 安全审查(PASS/FAIL)
│   ├── 05-ops/
│   │   ├── deploy.v1.md            #   ops-deployer:部署记录 / 配置说明
│   │   └── release-notes.v1.md     #   ops-deployer:发布说明
│   └── CHANGELOG.md                #   该功能产物的版本变更记录
│
└── _archive/                       # (可选)废弃 / 历史功能归档

前缀约定:功能目录用 <功能名> (kebab-case,需唯一且能表意,如 user-auth;不加日期前缀,避免迭代时日期误导,产出日期记到 frontmatter 的 date);阶段目录用 NN-角色 (按流水线顺序固定编号:01-pd → 02-design → 03-dev → 04-qa → 05-ops,一眼看清环节先后)。

文件命名格式 :<产物名>.v<主版本>.<扩展名>,全小写 kebab-case。

<产物名>:用下表的固定词(prd / architecture / api / db / test-report ...),下游靠它稳定引用。
v<主版本>:整数主版本,每次重大修订 +1,旧版本保留不删便于追溯(小修订直接覆盖当前版本,细节历史交给 git)。
例:prd.v1.md 改版为 prd.v2.md;api.v3.yaml。

每份文档头部加元信息块(YAML frontmatter),把版本与依赖关系沉到文件里:

yaml 复制代码

---
artifact: prd                 # 产物类型(固定词,见下表)
feature: user-auth            # 所属功能
version: 1                    # 主版本号
status: draft                 # draft / in-review / approved
author: pd-manager            # 产出该产物的角色
based_on:                     # 上游依赖(产物@版本),记录链路便于追溯
  - overview@_project
date: 2026-06-04
---

status 配合 3 个审批门禁:只有 approved 才允许进入下一阶段。
based_on 记录"我基于上游哪个版本产出";上游升版本时,据此判断下游是否需要重做。
yaml 产物(api.vN.yaml)不套 markdown frontmatter ,同义元数据写进 OpenAPI info 扩展字段:info.version / info.x-feature / info.x-status / info.x-author / info.x-based-on。
过程报告版本号 (test-report/review-report/deploy/release-notes)= 本次交付批次号,与当次最高契约/产物版本对齐;同批次重跑覆盖同版本。
表引用清单固定文件名 02-design/tables.vN.md(列出本功能用到的表:表名 + 中文名)。

角色 → 产物 → 路径对应表 (路径相对 docs/<功能>/):

角色	产物	文件路径
`pd-manager`	PRD(需求 + 功能设计)	`01-pd/prd.vN.md`
`dev-architect`	架构设计	`02-design/architecture.vN.md`
`dev-architect`	API 契约(OpenAPI)	`02-design/api.vN.yaml`
`dev-database`	数据库设计	`02-design/db.vN.md`(DDL / 迁移脚本在代码库 `migrations/`)
`dev-database`	表引用清单	`02-design/tables.vN.md`(表名 + 中文名)
`dev-backend`	后端变更摘要	`03-dev/change-summary-be.vN.md`(代码在 `backend/`)
`dev-frontend`	前端变更摘要	`03-dev/change-summary-fe.vN.md`(代码在 `frontend/`)
`qa-tester`	测试 / 覆盖率报告	`04-qa/test-report.vN.md`
`qa-reviewer`	审查报告(代码 + 安全,PASS/FAIL)	`04-qa/review-report.vN.md`
`ops-deployer`	部署记录 / 发布说明	`05-ops/deploy.vN.md`、`05-ops/release-notes.vN.md`
`x-writer`	使用文档 / 总文档	功能级放 `<功能>/`;项目级放 `docs/_project/` 或根 `README.md`

三、完整目录架子(已落地实现)

下面是插件的实际结构,与磁盘上的 hbteck-software-company/ 一致。references/ 内大量细化规范/方言/组件清单文件用「...」省略,仅标注其用途。

text 复制代码

hbteck-software-company/
├── .claude-plugin/
│   └── plugin.json                      # 插件清单:名称/版本/作者/元数据
│
├── CLAUDE.md                            # 【CTO 人设/护栏】主线程身份:唯一入口、永远委派、守 3 门禁、
│                                        #   含 主流程 + 变更/迭代编排 + 产物契约 + 知识沉淀 + 汇报格式
│
├── commands/                            # 【老板指令】流程入口,你 /xxx 启动一个环节(共 12 条)
│   ├── x-ship-it.md                     #   通用 · CTO 全链路一键编排器(从一句话目标到上线 + 守 3 门禁)
│   ├── x-change.md                      #   通用 · CTO 变更/迭代编排器(影响分析 → 最小面重做 → 守对应门禁)
│   ├── x-new-project.md                 #   通用 · 初始化新项目工作区(脚手架,生成代码 + docs/)
│   ├── x-doc.md                         #   通用 · 文档环节 → x-writer
│   ├── pd-spec.md                       #   产品 · 需求规格 + 功能设计(PRD)→ pd-manager(★① 需求确认)
│   ├── dev-design.md                    #   研发 · 架构设计 + API 契约(OpenAPI)→ dev-architect(★② 设计确认)
│   ├── dev-db.md                        #   研发 · 库表设计 + DDL/迁移脚本 → dev-database(随 ②)
│   ├── dev-backend.md                   #   研发 · 后端代码 → dev-backend(与前端可并行)
│   ├── dev-frontend.md                  #   研发 · 前端代码 → dev-frontend(与后端可并行)
│   ├── qa-test.md                       #   质量 · 测试(单元/集成/E2E + 覆盖率)→ qa-tester
│   ├── qa-review.md                     #   质量 · 代码 + 安全审查(只读)→ qa-reviewer
│   └── ops-deploy.md                    #   运维 · CI/CD + 部署上线 + 监控告警 → ops-deployer(★③ 上线前确认)
│
├── agents/                              # 【员工花名册】9 个专家(均为「终端执行者」,不调度他人)
│   ├── pd-manager.md                    # 产品部 · 产品经理
│   ├── dev-architect.md                 # 研发部 · 系统架构师
│   ├── dev-database.md                  # 研发部 · 数据库设计师
│   ├── dev-backend.md                   # 研发部 · 后端开发专家(DDD 7 层 Java/Spring)
│   ├── dev-frontend.md                  # 研发部 · 前端开发专家(Vue 3 + Arco + Tailwind + TS)
│   ├── qa-tester.md                     # 质量部 · 测试专家
│   ├── qa-reviewer.md                   # 质量部 · 代码审查专家(只读:tools 去掉 Write/Edit)
│   ├── ops-deployer.md                  # 运维部 · 部署专家
│   └── x-writer.md                      # 横向 · 技术文档(model: sonnet)
│
├── skills/                              # 【公司 SOP】11 个规范/工具技能(渐进式披露)
│   ├── pd-prd-standards/                #   产品 · PRD 编写规范(SKILL + chapters/ + templates/ + references/)
│   ├── dev-architecture-standards/      #   研发 · 架构设计 + DDD 领域建模 + 接口契约(references/ 接口清单与详细设计)
│   ├── dev-db-standards/                #   研发 · 数据库设计规范(references/ 方言:达梦 DM、MySQL + 模板)
│   ├── dev-backend-standards/           #   研发 · 后端 Java 编码规范(references/ 分层/公共工具/技术组件,paths 自动挂载)
│   ├── dev-backend-codegen/             #   研发 · DDL → DDD 7 层 Java 骨架生成器(scripts/generate.py + templates/*.j2)
│   ├── dev-frontend-standards/          #   研发 · 前端 Vue 3 编码规范(references/ 工程目录/组件清单,paths 自动挂载)
│   ├── qa-test-standards/               #   质量 · 测试规范(references/ 自动化测试报告规范)
│   ├── qa-review-standards/             #   质量 · 代码审查规范(只读,references/ 质量检查与接口审查)
│   ├── ops-deploy-standards/            #   运维 · 部署上线规范(CI/CD、密钥、健康检查、回滚)
│   ├── x-doc-standards/                 #   横向 · 技术文档规范(README/使用文档/发布说明)
│   └── x-new-project/                   #   通用 · 新项目脚手架(chapters/ + scripts/ + templates/ 前后端一体)
│
├── hooks/                               # 【自动质检卡点】系统事件触发
│   ├── hooks.json                       #   钩子配置总表(路径用 "${CLAUDE_PLUGIN_ROOT}" 引用)
│   ├── pre-block-dangerous-bash.sh      #   PreToolUse(Bash):拦截危险命令(rm -rf 等)
│   ├── pre-check-secrets.sh             #   PreToolUse(Edit|Write):提交前扫描密钥泄露
│   ├── post-auto-format.sh              #   PostToolUse(Edit|Write):改完文件自动格式化
│   └── post-run-tests.sh                #   PostToolUse(Edit|Write):改代码后自动跑测试
│
├── .mcp.json                            # 【外部系统】GitHub / 数据库(postgres)等接入
└── README.md                            # 公司说明书:角色清单 + 流程图 + 用法

可选(以后需要再加):bin/(挂到 PATH 的可执行脚本)、settings.json(插件默认配置)、.lsp.json(语言服务)、monitors/(后台监控)。

技能与角色的对应 :每个执行角色配一份「标准规范」技能(*-standards);研发侧额外配两份工具型 技能------dev-backend-codegen(DDL→DDD 7 层骨架代码)与 x-new-project(整仓脚手架)。dev-backend-standards / dev-frontend-standards / dev-db-standards 用 frontmatter 的 paths 声明文件后缀(**/*.java、**/*.vue、**/*.sql 等),改到对应文件时自动挂载。

四、组织架构(角色 → 部门一级一级细分)

text 复制代码

hbteck-software-company（一人 AI 软件公司）
└── cto【主线程,非子代理】       CTO · 你的唯一交互入口,统领全局、分配任务、阶段门禁、汇报
    │                              (人设/护栏在 CLAUDE.md;编排流程在 /x-ship-it 命令)
    ├── 产品部 pd-
    │   └── pd-manager             产品经理
    ├── 研发部 dev-
    │   ├── dev-architect          系统架构师
    │   ├── dev-database           数据库设计师
    │   ├── dev-backend            后端开发专家
    │   └── dev-frontend           前端开发专家
    ├── 质量部 qa-
    │   ├── qa-tester              测试专家
    │   └── qa-reviewer            代码审查专家
    ├── 运维部 ops-
    │   └── ops-deployer           部署专家
    └── 横向 x-
        └── x-writer               技术文档

角色边界说明

cto 是主线程,不是子代理 :Claude Code 里子代理不能再调用子代理 (Agent/Task 工具在子代理上下文中被静默剥离)。若把 CTO 写成 agents/cto.md 并当子代理调用,它就无法派活给其它专家,调度直接失效。因此 CTO 不放 agents/,而是落在主线程 :人设与硬护栏写进根目录 CLAUDE.md,可执行的编排流程写进 commands/x-ship-it.md(命令跑在主线程,能派子代理);hooks 做兜底强约束。

其余 9 个角色都是「终端执行者」:各自在独立上下文里干完一件事、产出一份产物、交回主线程(CTO),彼此之间不直接通信。

评审走「委派 + 只读结论」,严防撑爆 CTO 上下文 :CTO 是汇总+门禁点,但不亲自通读每份产物 (否则把每份 PRD、每份代码全读进主线程,上下文很快就爆)。产物是否符合要求,由 CTO 派 qa-reviewer(代码/安全)、qa-tester(测试)在各自独立上下文里审查 ,只回传简洁的 PASS/FAIL 结论 + 关键问题;CTO 仅据这些结论判断是否达预期、放行或打回。文档类产物(PRD / 设计)则在人工审批门禁处由你过目。------对应现实里 leader 不逐字读代码,而是看 QA 验收结论再拍板。

角色取舍标准:一个角色只在「产出独立可审阅的交付物 + 触发边界清晰不重叠」时才占一个 agent 名额;只是「一个步骤」或「一套规范」的,落为 command / skill / hook。

研发部采用「分工制」 :接口契约在架构阶段定死(OpenAPI),dev-backend / dev-frontend 各自 code to contract、可并行、边界清晰;前后端对接由 qa-tester 的集成测试覆盖。

审查/审计类只读边界 :qa-reviewer 的 tools 去掉 Write/Edit,只读代码与 diff,保证审查独立性;可自动化的安全检查下沉到 hook(如 pre-check-secrets.sh)。

4.1 各角色职责与产物清单(必读)

产物即「契约」:上游的输出产物 = 下游的输入产物 ,流水线靠这套产物稳定串起来。下表只描述「产物是什么」;具体存放路径、文件命名与版本规范见 2.4 产物命名与存放规范。
说明:cto 不是 agents/ 里的子代理 ,而是主线程身份(CLAUDE.md + /x-ship-it 命令);下表其余 9 个才是 agents/*.md 子代理。

角色	一句话职责	必需输入产物(上游交接)	输出产物(下游依赖)	门禁
cto(主线程)	接目标→拆任务→按主流程派各子代理→派 qa-reviewer/qa-tester 审查产物、只读其 PASS/FAIL 结论判断是否达预期→在审批点暂停汇报	你的一句话目标 / 需求 + 各子代理回传的结论摘要(不通读产物全文)	任务拆解计划、各阶段判断结论、各阶段汇报、最终交付汇总	主持 3 个门禁
pd-manager	把模糊想法转成稳定的工程契约(需求规格 + 功能设计合一)	cto 转达的目标 / 原始想法	PRD(需求与功能设计说明书):范围、用户故事、功能清单、页面与交互说明、验收标准、非功能需求、开放问题	① 需求确认
dev-architect	把 PRD 翻成技术蓝图	PRD	架构设计(模块划分 / 领域模型 )+ API 契约(OpenAPI)+ file-by-file 实现顺序	② 设计确认
dev-database	据领域模型与 API 契约设计数据库	架构设计、API 契约	数据库设计 + DDL / 迁移脚本	② 设计确认
dev-backend	据 API 契约 + DDL + 架构设计，实现后端代码与业务逻辑	API 契约、DDL、架构设计、PRD	后端代码 + 一段「变更摘要」给 qa;不动前端	---
dev-frontend	据 API 契约 + 功能设计,实现页面与交互	API 契约、架构设计、PRD	前端代码 + 一段「变更摘要」给 qa;不动后端	---
qa-tester	把每条验收标准映射成测试,写并跑单元/集成/E2E,覆盖前后端联调路径	PRD(验收标准)、前后端代码、API 契约	测试代码 + 测试 / 覆盖率报告(PASS/FAIL)	---
qa-reviewer	只读审查 diff:对照验收标准/规范/最佳实践 + 安全审查	代码 diff、上游「变更摘要」、规范 skill	审查报告(代码审查发现 + 安全发现,PASS/FAIL + 文件:行号);不写代码	---
ops-deployer	CI/CD 流水线、构建与部署上线 + 配置监控/告警/日志	通过审查与测试的代码、部署目标/环境	CI/CD 配置、部署脚本、部署日志、监控/告警配置	③ 上线前确认
x-writer	汇总各环节产物写文档	全流程产物	README / 使用文档 / 发布说明	---

交接链一图流 :

目标 → [pd-manager] PRD → [dev-architect] 架构设计 + API 契约 → [dev-database] 数据库设计/DDL → [dev-backend] 后端代码 + [dev-frontend] 前端代码(并行,各自 code to contract)→ [qa-tester] 测试报告 + [qa-reviewer] 审查报告 → [ops-deployer] 部署 → [x-writer] 文档

五、主流程(全链路如何串起来)

text 复制代码

你的想法
  │
  ▼  /pd-spec            pd-manager      → PRD(需求规格 + 功能设计)               ★① 需求确认
  ▼  /dev-design         dev-architect   → 架构设计 + API 契约(OpenAPI)            ★② 设计确认
  ▼  /dev-db             dev-database    → 数据库设计 + DDL/迁移脚本                 （随设计确认)
  ▼  /dev-backend  ┐     dev-backend     → 后端代码 + 变更摘要
  ▼  /dev-frontend ┘     dev-frontend    → 前端代码 + 变更摘要         （并行,各自 code to contract)
  ▼  /qa-test            qa-tester       → 测试代码 + 测试/覆盖率报告(含联调验证)
  ▼  /qa-review          qa-reviewer     → 审查报告(代码审查 + 安全,只读,PASS/FAIL)
  ▼  /ops-deploy         ops-deployer    → 部署上线 + 监控/告警配置                    ★③ 上线前确认
  ▼  /x-doc              x-writer        → 文档 / 使用文档 / 发布说明

  /x-ship-it = 一键串起以上全部环节,由 cto 担任总指挥
               (负责拆解任务、上下文交接、阶段门禁校验、在审批点暂停等你拍板)

说明:dev-backend 与 dev-frontend 因有 API 契约(OpenAPI)可并行 ;联调不再设独立环节,由 qa-test 的集成/E2E 测试覆盖。设计阶段 dev-database 依赖 dev-architect 的领域模型与契约,串行(不要并行派这两位),二者同属 ② 门禁一并确认。
实际使用中,你只需和 cto 对话 下达目标,由它自动调用上述各环节的命令与专家;以上单个 /命令 是需要单独执行某环节时的手动入口。

3 个人工审批卡点(由你拍板) :需求确认 → 设计确认 → 上线前确认。其余环节自动流转。

这 3 个卡点由 cto 负责暂停并向你汇报。

5.1 变更 / 迭代主流程(`/x-change`)

新功能从零起走 /x-ship-it;已有功能的需求变更或版本迭代走 /x-change 。核心原则:不是推倒重来,而是按「影响面最小」重做------只重做受影响的产物链,无关产物原样复用。

text 复制代码

你的变更诉求(目标功能 + 改什么)
  │
  ▼  ① 建变更分支 + 登记      cto       → change/<功能>-<简述> 分支 + CHANGELOG 记「变更意图」
  ▼  ② 影响分析(关键)        cto       → 读各产物 frontmatter 的 based_on,逆推受影响产物链与重入起点
  ▼  ③ 最小面重做             子代理     → 从「受影响的最上游一棒」按主流程重新派活
  │       · 需求范围变  → 起点 pd-manager,整链重走,过 ★①②③
  │       · 仅接口字段变 → 起点 dev-architect,api 升版,前后端按新契约重对账,过 ★②
  │       · 仅修 bug/优化 → 起点 dev-backend/dev-frontend,无新增门禁
  ▼  ④ 回归                   qa-tester → 跑回归(变更点 + 本功能波及面 + 跨功能波及面),基线取上次发布 tag
  ▼  ⑤ 审查                   qa-reviewer→ 审本次 diff(只读,PASS/FAIL)
  ▼  ⑥ 部署(如需)           ops-deployer→ 部署 + 监控                                ★③ 上线前确认
  ▼  ⑦ 文档与变更记录         x-writer  → 更新使用文档/发布说明 + 补全 CHANGELOG 明细与「当前生效版本组合」表

改版还是升版 :在途未发布 (当前版本 status 未到 approved/未上线)→ 原地改当前版本号,不另存新版;已通过门禁/已上线 后再变更 → 才另存 v<N+1>,旧版保留。

同功能演进 vs 独立大版本 :任一为「是」即按独立大版本------①改库表主结构(拆表/改主键/不兼容迁移);②破坏旧 API 契约(删字段/改语义);③需新旧并存。独立大版本新建 <功能名>-v2 目录,目录内产物从 v1 重新起算 ,based_on 指回旧功能。

只有被本次变更触及的门禁(①②③)才必停必汇报 ;未触及的环节不重复打扰。详细编排见 commands/x-change.md 与 CLAUDE.md 第四节。

六、各文件「架子模板」(填空用)

用法:把 < > 里的内容替换成你的实际值,带「填空」的中文注释删掉即可。所有模板都遵循第二节的命名规范与部门前缀。

6.1 `.claude-plugin/plugin.json`(插件清单)

实际值(hbteck-software-company/.claude-plugin/plugin.json):

json 复制代码

{
  "name": "hbteck-software-company",
  "version": "0.1.0",
  "description": "一人 AI 软件公司：把产品→设计→开发→测试→部署全流程组织成有角色分工、可自动调度的虚拟公司（CTO 主线程编排 + 9 个终端执行子代理 + SOP 技能 + 质检钩子）。",
  "author": { "name": "bo.huang", "email": "" },
  "homepage": "",
  "license": "MIT",
  "keywords": ["software-company", "agents", "ddd", "full-stack", "workflow"]
}

仅 name 必填;其余推荐填写。

组件放在默认目录(agents/、commands/、skills/、hooks/、.mcp.json)时会被自动发现,无需在此显式声明路径。

name 会成为命令前缀,例如 /hbteck-software-company:dev-deploy。

6.2 `agents/*.md`(子代理 / 专家)

markdown 复制代码

---
name: dev-backend
description: <何时该派给这个专家。写清「触发场景 + 关键词」,越具体越准。例:当需要根据接口设计与 DDD 规范实现后端 Java/Spring 代码、编写 service/repository/聚合逻辑时使用。可加「主动使用 / PROACTIVELY」提高自动调度命中率>
tools: Read, Write, Edit, Grep, Glob, Bash
model: inherit
---

你是 <角色定位,如「研发部资深后端开发专家,精通 DDD 分层架构与 Spring 生态」>。

## 职责边界
- 负责:<这个专家具体做什么>
- 不负责:<明确划清不做什么,避免误派,如「不做前端、不做部署」>

## 输入(上游交接)
- <你接收什么产物。例:接口设计文档(OpenAPI)、数据库 DDL、功能设计说明书>

## 工作步骤
1. <第一步,如:查阅 dev-ddd-architecture / dev-backend-standards 规范>
2. <第二步,如:按七层架构生成骨架代码>
3. <第三步,如:实现业务逻辑与异常处理>
4. <自检,如:确认无硬编码、无吞异常>

## 产出格式(下游依赖,务必严格遵守)
- <交付什么、放在哪个目录、用什么结构。例:代码文件 + 一段「变更摘要」给 qa-reviewer>

## 约束
- <硬性红线,如:不得提交密钥;改动只限 backend/ 目录;遵守现有命名规范>

frontmatter 字段说明:

字段	必填	说明
`name`	是	kebab-case 唯一标识,自动派活的身份
`description`	是	何时委派给它,最重要,决定自动调度是否准确;写清触发场景+关键词
`tools`	否	允许使用的工具白名单(逗号分隔或 YAML 列表);省略则继承全部。审查/审计类专家应去掉 `Write`/`Edit` 形成只读边界
`disallowedTools`	否	工具黑名单(先于 tools 生效)
`model`	否	`sonnet` / `opus` / `haiku` / 完整模型ID / `inherit`,默认 `inherit`。高噪声/简单任务可降到 `haiku` 省 token
`skills`	否	启动时预加载的 skill 列表
`permissionMode`	否	权限模式(如 `default` / `acceptEdits` / `plan`)

写作要点 :description 写「何时触发」,正文写「怎么做 + 输出格式」。给下游消费的专家(如 dev-backend → qa-reviewer)务必固定「产出格式」,流水线才能稳定串起来。

6.3 `commands/*.md`(流程指令 / 老板发话)

markdown 复制代码

---
description: <这条命令做什么,会显示在 /help 列表>
argument-hint: "[<参数提示,如:项目名 / 需求描述,可留空>]"
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: inherit
---

# <环节名称,如:后端开发>

目标:<这条命令要达成什么>

## 输入
- 需求/参数:$ARGUMENTS
- 上游产物:<引用上一环节的产物文件,路径按后续约定,如 @docs/<上游产物>>

## 当前上下文(自动注入,可选)
<!-- 用 !`cmd` 把命令输出嵌入提示词,例: -->
当前 git 状态:
!`git status --short 2>/dev/null || echo "not a git repo"`

## 流程步骤
1. 调用 <哪个 agent,如 dev-backend 子代理>
2. 让它查阅 <哪个 skill,如 dev-ddd-architecture / dev-backend-standards>
3. 产出 <什么交付物,放在哪>
4. <是否需要停下等人工审批。例:这是「上线前确认」卡点,暂停并向我汇报>

## 产出
- <交付物清单 + 一句话结果摘要>

字段	作用
`description`	显示在 `/help` 中的描述
`argument-hint`	参数提示,告诉用户该传什么
`allowed-tools`	预授权工具,免逐次确认(可用 `Bash(git commit:*)` 精细限定)
`model`	指定模型

三种动态能力 :$ARGUMENTS/$1/$2 接收参数;@文件 引用文件内容;``!`命令``` 执行命令并把输出嵌入提示词。命令与主对话共享上下文,适合做流程编排入口。

6.4 `skills/<名>/SKILL.md`(规范 / SOP)

markdown 复制代码

---
name: dev-ddd-architecture
description: <这个规范是什么 + 何时该用它,放具体触发词。例:DDD 七层分层架构规范。当编写/审查后端代码、设计聚合与分层、确定模块归属时使用>
when_to_use: <补充触发场景或示例请求,可选>
---

# <规范标题>

## 适用场景
<什么时候该读这份规范>

## 核心要点
- <要点 1>
- <要点 2>
- <要点 3>

## 详细规则
<正文建议 < 500 行。大段细节拆到 chapters/ 按需加载,这里只放索引与最常用规则>

- 分层职责详见:chapters/layers.md
- 聚合/实体/值对象详见:chapters/aggregates.md
- 命名约定详见:chapters/naming.md

配套章节 skills/<名>/chapters/<主题>.md(单一主题,被引用时才加载):

markdown 复制代码

# <章节主题,如:七层分层职责>

<只写这一个主题的细节,保持单一职责>

frontmatter 字段说明:

字段	必填	说明
`name`	推荐	kebab-case,默认取目录名
`description`	推荐	做什么 + 何时用,Claude 据此自动加载(与 when_to_use 合计 ≤ 1536 字符)
`when_to_use`	否	补充触发场景 / 示例请求
`disable-model-invocation`	否	`true` 则只能手动 `/name` 触发,关闭自动加载

渐进式披露 :启动只加载 name+description(约 100 token);命中后才加载 SKILL.md 正文;chapters/ 等细节仅在被引用时加载。所以 description 必须写准触发词,否则该用时不被加载。

6.5 `hooks/hooks.json`(质检卡点)

json 复制代码

{
  "description": "一人公司质量门禁钩子",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-block-dangerous-bash.sh" }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-check-secrets.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-auto-format.sh" }
        ]
      }
    ]
  }
}

配套 hook 脚本模板 hooks/<时机>-<动作>.sh(以拦截类 PreToolUse 为例):

bash 复制代码

#!/bin/bash
# <脚本说明,如:提交/执行前拦截危险命令>
set -e
INPUT=$(cat)                                          # hook 输入是一段 JSON,从 stdin 读

# 取出要检查的字段(调试信息打到 stderr,不污染协议输出)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if <命中你的拦截条件>; then
  # 用 hookSpecificOutput 与 Claude 通信:deny=拦截,allow=放行
  cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "<为什么拦截>"
  }
}
EOF
  exit 2                                              # 退出码 2 = 阻断
fi

echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
exit 0

常用事件与匹配器:

事件	触发时机	能否拦截	matcher 过滤
`PreToolUse`	工具调用前	是	工具名(`Bash` / `Edit
`PostToolUse`	工具调用成功后	否	工具名
`UserPromptSubmit`	提交提示词前	是	---
`SessionStart`	会话开始	否	`startup` / `resume` / `clear` / `compact`
`Stop`	Claude 回答结束	是	---
`SubagentStop`	子代理结束	是	agent 名

插件内 hook 路径统一用 ${CLAUDE_PLUGIN_ROOT} 引用,保证可移植(换机器/换人也能跑)。

脚本记得 chmod +x,且依赖 jq 解析输入 JSON。

退出码:0 放行、2 阻断;复杂判定可改用 type: prompt(单次 LLM 评估)或 type: agent(多轮子代理验证)。

6.6 `.mcp.json`(外部系统接入)

json 复制代码

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

三种传输方式:stdio(本地进程,如上)、HTTP、SSE。

密钥绝不写死 :用 ${ENV_VAR} 引用环境变量,真实值放 .env(并加进 .gitignore)。

MCP 工具在 hook 里可用 mcp__<server>__<tool> 形式的 matcher 过滤。

6.7 `README.md`(公司说明书)

markdown 复制代码

# <插件名> · 一人 AI 软件公司

<一句话定位>

## 角色清单
<按部门列出 agents,各自职责一句话>

## 命令速查
| 命令 | 作用 | 触发的专家 |
|------|------|-----------|
| `/x-ship-it` | 全链路一键(新功能从零到上线) | cto 总指挥 |
| `/x-change` | 变更/迭代(影响分析→最小面重做) | cto 总指挥 |
| `/x-new-project` | 初始化新项目工作区(脚手架) | x-new-project 技能 |
| `/pd-spec` | 需求规格 + 功能设计(PRD) | pd-manager |
| `/dev-design` | 架构 + API 契约(OpenAPI) | dev-architect |
| `/dev-db` | 库表设计 + DDL/迁移脚本 | dev-database |
| `/dev-backend` | 后端代码 | dev-backend |
| `/dev-frontend` | 前端代码 | dev-frontend |
| `/qa-test` | 测试 + 覆盖率报告 | qa-tester |
| `/qa-review` | 代码 + 安全审查(只读) | qa-reviewer |
| `/ops-deploy` | 部署上线 + 监控告警 | ops-deployer |
| `/x-doc` | 文档 / 使用文档 / 发布说明 | x-writer |

## 主流程图
<贴第五节的流程图>

## 人工审批卡点
1. 需求确认  2. 设计确认  3. 上线前确认

## 安装与使用
<如何安装插件、如何只和 cto 对话下达目标>

七、落地建议(骨架已就绪,以下为迭代与维护原则)

骨架已建好:第三节目录的 commands / agents / skills / hooks 均已落地;新增能力时沿用同一命名规范与部门前缀,在既有架子上增量扩展即可。
先跑通一条最小主线 :/x-new-project → /pd-spec → /dev-design → /dev-backend → /dev-frontend → /qa-test,跑顺后再向两端补数据库、审查与部署;日常直接和 CTO 对话或用 /x-ship-it。
description 是命脉 :agent 和 skill 的 description / when_to_use 决定自动调度是否准确,务必写具体触发场景与关键词。
知识沉淀分两层 (严防写错地方,运行期不可写入插件目录):
- 项目级经验 (本项目反复出现的问题/约定)→ 派 x-writer 汇编进目标项目 docs/_project/conventions.md / known-issues.md(随项目 git)。
- 跨项目 SOP (可复用通用规范)→ 由你(CTO)/ 用户裁决,开发期手动改插件源码 skill 的 references/ 后发版;x-writer 不做此事。

附:参考来源

Claude Code 插件参考:https://code.claude.com/docs/en/plugins-reference
子代理(Subagents):https://code.claude.com/docs/en/sub-agents
技能(Skills):https://code.claude.com/docs/en/skills
钩子(Hooks):https://code.claude.com/docs/en/hooks

一人 AI 软件公司 · Claude Code 插件架构设计