Multica Best Practices

English | 中文

一个复用度极高的超级个体编排流程（从 PRD 到 CICD）。 面向 Multica 的 Agent · Squad · Skill · Issue 实战模板。 Copy. Paste. Run. —— 复制即用；或者一条命令自动建好整套。

本仓库把「一个需求从 Issue 走到可上线」需要的角色、流程、门禁、平台对接做成可直接复制的配置。你不必从零写 Prompt：复制一个 Starter → 在平台壳里填 .env → 跑真实任务，再按团队情况裁剪。

背景：很多团队在 Multica 上反复重造「需求 → 设计 → 实现 → 测试 → 部署」的轮子，还把 Confluence / Jira / Jenkins / Figma 等平台地址与凭据写死在 Prompt 里——换一家公司或平台就得重写。 本仓库的核心解法：平台只出现在 multica-platform-* 占位壳，角色提示词只说「用哪个 skill」；Skill 按名字挂载，团队填壳即复用。所有模板都经过真实任务验证，并公开为「Copy. Paste. Run.」。

这是什么

一句话：一套面向真实任务持续迭代的 Multica 小队配置——每个 Agent 只负责一件事，Leader 负责编排与门禁，每步产出都要证据。

你创建：Agent（角色） + Squad（编排） + Skill（做法） + Issue（任务）
                  ↓
       Leader 带队：需求收敛(G0) → 设计 → 实现 → 单测 → 部署 → 自动化测试
                  ↓
   每步门禁（multica-verification skill 复跑）→ Human 最终验收

角色与职责（Agent Matrix）

注：software-development-reviewed Starter 在上述角色之外，为除 Leader、DevOps 外的每个常规产出角色配备了专属 Reviewer（ArchReviewer / DesignReviewer / ProductReviewer / FrontendReviewer / BackendReviewer / TestReviewer），见 Starters 与 gates-and-evidence。

Starters

更多 Starter（Technical Research 等）将基于真实任务验证后补充。不要假装最佳实践已经完成。

仓库结构

AGENTS.md     ⭐ Agent 入口：项目约定与改动规范
templates/  ⭐ 从这里开始：可直接复制的全部配置
├── zh_CN/              中文模板（默认；复制整个子目录即用）
│   ├── agents/           共享 Agent Instructions（15 个角色定义：9 常规 + 6 专属 Reviewer）
│   ├── skills/           共享 Skill（29 个，按角色分组：architect / backend / designer / devops / frontend / leader / platform / product-manager / reviewer / shared / tester；四层模型详见 skills/README.md）
│   └── squad/            小队 Starter
│       ├── software-development/ 常规开发（squad / issue / README 含工作流）
│       ├── software-development-reviewed/ 推荐主流程：每角色专属 Reviewer + 两层门禁
│       └── bug-fix/             最小修复组合（只换编排）
└── en_US/              英文模板（与 zh_CN/ 结构一致）
docs/          ⭐ 先读这一页：指令放哪 / 门禁证据 / 常见错误 / 裁剪扩展
├── zh_CN/              中文方法论
└── en_US/              英文方法论
scripts/       ⚙️ 可选自动化：一键把模板推送到 Multica（建小队 / 建智能体 / 导入并绑定 skills）
└── multica-sync/       Python 3.9+ 仅标准库，全部幂等；详见 scripts/multica-sync/README.md

完整流程一览

一个需求从 Issue 进来到测试通过的全链路（基于 templates/zh_CN/squad/software-development-reviewed，即双层门禁主流程；software-development 为无专业评审的轻量替代）：

flowchart TB
    IN([需求 / 想法 / Issue 输入])

    subgraph P0["阶段 0：需求收敛与 G0"]
        direction TB
        L0["@Leader读取 Issue，判断事实源"]
        PM["@ProductManager（可选）multica-pm-requirement-spec+ multica-pm-artifact-publish落地平台由 sync skill 决定"]
        REQ[/"需求事实源PRD 或已有 IssueG- FR- BR- AC- OP- RISK-"/]
        SCOPE["@Leader确定范围、在场角色、路由图声明 deploy branch"]
        OP{"OP- 关闭且范围明确？"}
        CLARIFY["人类 / @ProductManager补充口径与待确认项"]
        G0["G0 人工确认范围、业务规则、参与角色"]

        L0 --> PM --> REQ
        REQ --> SCOPE --> OP
        OP -->|"否"| CLARIFY --> SCOPE
        OP -->|"是"| G0
    end

    subgraph P1["阶段 1：设计、测试左移与 G1"]
        direction TB
        ARCH["@Architect（可选）multica-technical-design+ multica-artifact-architectOutput: 技术设计稳定引用"]
        DESIGNER["@Designer（可选）multica-design-ui-implOutput: UI、全状态、Token、标注"]
        T1["@Tester T1（可选）multica-test-t1-design+ multica-test-orchestrationOutput: 功能用例 + AC- 追溯"]
        R1["@ProductReviewer / @ArchReviewer / @DesignReviewer（可选）G1 专业产出物评审（需求 / 技术设计 / UI 各自独立评审）"]
        V1["@Leadermultica-verification检查设计与 AC- 对齐"]
        G1{"G1 通过？"}
        FIX1["退回对应设计角色最多返工 2 次"]

        ARCH --> R1
        DESIGNER --> R1
        T1 --> R1
        R1 --> V1 --> G1
        G1 -->|"FAIL"| FIX1 --> R1
    end

    subgraph P2["阶段 2：契约先行、并行实现与 G2"]
        direction TB
        API["@BackendDev（可选）先发布 API 契约multica-artifact-backend"]
        BDEV["@BackendDev（可选）multica-backend-implOutput: 服务端代码 + 单测"]
        FDEV["@FrontendDev（可选）依赖 UI + API 契约multica-frontend-impl"]
        APICASE["@Tester（可选）与开发并行写接口用例multica-test-orchestration"]
        SELF["开发自查multica-verification"]
        R2["@FrontendReviewer / @BackendReviewer（可选）G2 专业产出物评审（前端 / 后端各自独立评审）"]
        V2["@Leadermultica-verification独立复跑实现证据"]
        G2{"G2 通过？"}
        FIX2["退回对应开发角色附失败证据与修改清单"]
        PUSH["各端 merge 到 deploy branch 并 push"]

        API --> BDEV
        API --> FDEV
        API --> APICASE
        BDEV --> SELF
        FDEV --> SELF
        APICASE --> R2
        SELF --> R2 --> V2 --> G2
        G2 -->|"FAIL"| FIX2 --> SELF
        G2 -->|"PASS"| PUSH
    end

    subgraph P25["阶段 2.5：覆盖率评估、CI/CD 与部署"]
        direction TB
        T2["@Tester T2（可选）multica-test-t2-coverageOutput: 用例补充 + AC- 覆盖率评估"]
        DEVOPS["@DevOps（可选）multica-artifact-cicd-sync（内部调用 multica-platform-* 壳）"]
        DISCOVER["discover-only复制上次成功参数，仅改 deploy branch"]
        READY{"discover ready？"}
        CICD["触发 CI/CD 构建、打包、部署（平台由 platform 壳决定）"]
        DEPLOY[/"CI/CD 证据Build URL + 日志摘要 + 环境 URL"/]
        G25["G2.5 @Leader 门禁核对部署证据"]
        FIX25["BLOCKED / FAIL补参数、修流水线或退回开发"]

        DEVOPS --> DISCOVER --> READY
        READY -->|"否"| FIX25 --> DEVOPS
        READY -->|"是"| CICD --> DEPLOY --> G25
    end

    subgraph P3["阶段 3：真实环境自动化测试与 G3"]
        direction TB
        T3["@Tester T3（可选）输入: T1 + 接口用例 + T2 + 环境 URLmultica-test-t3-ui-automation+ multica-test-orchestration"]
        RT["@TestReviewer（可选）G3 测试评审"]
        REPORT[/"测试报告自动化日志 + AC- 逐条结果PASS / FAIL / BLOCKED"/]
        V3["@Leadermultica-verification复核测试证据"]
        G3{"G3 通过？"}
        FAIL3["FAIL: 建缺陷并退回开发修复后重新经过 G2 / G2.5 / G3"]
        BLOCK3["BLOCKED: 补环境、数据或权限"]

        T3 --> RT --> REPORT --> V3 --> G3
        G3 -->|"FAIL"| FAIL3
        G3 -->|"BLOCKED"| BLOCK3
    end

    subgraph P4["阶段 4：人工验收"]
        direction TB
        G4["G4 人工验收业务价值、发布风险、最终放行"]
        DONE([测试通过 / 可合并 / Done])
        REJECT["不通过: 指定责任角色返工重新经过对应门禁"]
        ESC["统一升级人类返工超 2 次 / 安全或发布风险 / 证据矛盾"]

        G4 -->|"通过"| DONE
        G4 -->|"不通过"| REJECT
        REJECT -. "达到升级条件" .-> ESC
    end

    IN --> L0
    G0 -. "范围含技术设计" .-> ARCH
    G0 -. "范围含 UI" .-> DESIGNER
    G0 -. "Tester 在场，启动 T1" .-> T1
    G1 -->|"PASS"| API
    G1 -. "仅前端或无后端时跳过 API 契约" .-> FDEV
    PUSH --> T2
    PUSH --> DEVOPS
    T2 --> T3
    G25 -->|"PASS"| T3
    G25 -->|"FAIL"| FIX25
    G3 -->|"PASS"| G4

    classDef terminal fill:#1f2937,color:#fff,stroke:#111827,stroke-width:2px;
    classDef role fill:#e8f5e9,color:#173b1b,stroke:#2e7d32,stroke-width:1.5px;
    classDef artifact fill:#f3e5f5,color:#3b1742,stroke:#8e24aa,stroke-width:1.5px;
    classDef gate fill:#ffebee,color:#56151b,stroke:#c62828,stroke-width:2px;
    classDef human fill:#eeeeee,color:#222,stroke:#616161,stroke-width:1.5px;
    classDef action fill:#fff8e1,color:#3d3100,stroke:#b58500,stroke-width:1.2px;

    class IN,DONE terminal;
    class L0,PM,SCOPE,ARCH,DESIGNER,T1,R1,V1,API,BDEV,FDEV,APICASE,SELF,R2,V2,T2,DEVOPS,T3,V3 role;
    class REQ,DEPLOY,REPORT artifact;
    class OP,G0,G1,G2,READY,G25,G3,G4 gate;
    class CLARIFY,ESC human;
    class FIX1,FIX2,PUSH,DISCOVER,CICD,FIX25,FAIL3,BLOCK3,REJECT action;

关键约束：① 所有门禁由 Leader 用 multica-verification 独立复跑，不采信成员自述；② T3 必须等 G2.5 PASS 后才派发；③ 外部工具（Confluence / JIRA / Jenkins / Figma / 用例平台）经编排层 skill（multica-artifact-* 系列等）与 multica-platform-* 壳层可替换接入，公开仓库只保留占位壳；④ 任一产物被修改后，其下游门禁立即失效、必须重新门禁。

5 分钟快速开始

前置条件

一个 Multica 环境（能创建 Agent / Squad / Skill / Issue）。 还没有？先看 Multica 文档 或 How Multica works（3 分钟）。

下面两条路，选一条即可：

Step 4–6（建 Issue → 分配 → 运行）两种模式共用。

---

方式 A — 自动（脚本，推荐）

scripts/multica-sync 把本仓库模板一次性推到你的 workspace： 导入 skills → 创建/更新 agents → 创建小队 → 加成员 → 绑定 skills。 幂等（可反复跑）、以名称对齐（不用填任何 UUID）、仅依赖 Python 3.9+ 标准库。

cd scripts/multica-sync

$env:MULTICA_API_TOKEN = "mul_xxx"                           # 你的 API Token
$env:MULTICA_API_URL   = "https://your-multica.example.com"  # 你的 Multica 地址

python bootstrap_squad.py --workspace 100 --dry-run   # 先预览（可选）
python bootstrap_squad.py --workspace 100             # 一条命令建好整套

就这两条命令：默认用内置的 squad-bootstrap.example.json（15 个角色 + 各自挂载的 skills）。 想改角色或挂载时，复制一份再改：

cp squad-bootstrap.example.json squad-bootstrap.json
python bootstrap_squad.py --workspace 100 --config squad-bootstrap.json

只想同步部分角色 / 精确覆盖绑定 / 指定 runtime：见 scripts/multica-sync/README.md。 自动模式已完成 Step 1–3，直接跳到 Step 4 创建 Issue。

---

方式 B — 手工（复制粘贴）

👉 templates/zh_CN/squad/software-development-reviewed（轻量无专业评审版见 software-development）

你将得到：

• 1 个 Squad Leader（编排 + 门禁）
• 15 个 Agent：主流程 software-development-reviewed 含 6 个专属 *-reviewer（ArchReviewer / DesignReviewer / ProductReviewer / FrontendReviewer / BackendReviewer / TestReviewer）；轻量版 software-development 为 9 个（单 Reviewer）
• 29 个 Skill（按需复制；其中 multica-verification 是必备门禁 Skill，推荐起步集见下表）
• 1 个 Issue 模板（含「涉及端」范围声明；来源支持「链接型 / 全量自包含」二选一）
• 1 个软件开发工作流（任意角色可缺失的条件路由，含 G2.5 CI/CD）

Step 1 — 创建 Agents

在 Multica 创建 9 个 Agent（命名遵循 docs/zh_CN/naming-conventions.md），把 templates/zh_CN/agents/ 下对应文件的代码块复制到各自 Instructions：

leader.md 不需要单独建 Agent：Squad Instructions 只注入 Leader，squad.md 就是它的行为配置。ProductManager 为可选角色，仅当需求无就绪范围标识时由 Leader 派发。

Step 2 — 创建 Skills

把 templates/zh_CN/skills/ 下的 Skill 按需复制到 Multica 的 skills/（完整清单与分层见 skills/README.md，目前共 29 个，分内容 / 编排 / 平台 / 评审四层）。推荐起步最少集：

所有 Skill 共享放在 templates/zh_CN/skills/，统一 multica- 前缀命名空间，分四类（详见 skills/README.md 与 docs/zh_CN/role-skills-architecture.md）：内容层（requirement-analysis / technical-design / backend-impl / frontend-impl / test-t1·t2·t3 / verification）；编排层（multica-artifact-architect / multica-artifact-backend / multica-artifact-frontend / multica-artifact-cicd-sync + multica-pm-artifact-publish + multica-design-ui-impl + multica-test-orchestration，负责把产物落地到团队平台，平台在 skill 内实现、可替换）；平台层占位壳（multica-platform-* 五个，唯一允许出现公司基建地址/凭据占位的地方，公开仓库只给占位壳）；评审层（multica-review-* 六个）。角色提示词只说"用哪个 skill"，不写平台名；换公司只填平台壳。Skill 靠名称挂载，谁需要就在自己的 Instructions 里写「用 xxx skill」，与仓库路径无关。

Step 3 — 创建 Squad

创建 Squad，把 templates/zh_CN/squad/software-development-reviewed/squad.md 复制到 Squad Instructions（轻量替代可用 software-development/squad.md）。

Step 4 — 创建 Issue

把 templates/zh_CN/squad/software-development-reviewed/issue.md 复制到新 Issue：若需求已在 Jira/Tapd，选「外部系统链接」只填链接 + 涉及端即可；否则选「全量自包含」完整填写。

Step 5 — 分配

把 Issue 分配给这个 Squad。

Step 6 — 运行

Issue → [设计] → [API 契约 ∥ 功能用例] → [前端 ∥ 后端实现 ∥ API 测试用例] → [G2.5 CI/CD 部署] → [T3 测试报告] → Human

每个产物的门禁由 Leader 用 multica-verification skill 执行，PASS 才进入下一阶段；范围里没有的角色直接跳过；设计与关键改动由 Reviewer 做业务评审；G2 后由 DevOps 触发 CI/CD（G2.5），Tester 在其部署环境跑自动化（T3）。 就这些。先跑一个真实需求，再按你的团队调整。

一条指令该放哪？

Issue   = 我们在做什么？
Project = 我们应该知道什么？
Agent   = 我的职责是什么？
Squad   = 谁应该做什么？
Skill   = 我该怎么做？
CI / PR = 什么必须真的通过？

原则

1. Agent 职责保持狭窄。
2. 不要把路由逻辑复制进每个 Agent。
3. 由 Squad Leader 统一协调。
4. 完成者不得审批自己的工作（门禁动作标准化为 multica-verification skill，由不产出的 Leader 或 CI 执行）。
5. 用证据代替「做完了」的口头声明。
6. 不用自然语言指令做硬性约束。
7. 复杂多 Agent 之前，先用简单流程。
8. 临时故障重试。
9. 方向错误就重启新会话，别硬推。
10. 在重要的不可逆边界保留人类审批。

Instructions 是引导，不是安全边界。 必须被遵守的规则请放到 LLM 之外：测试、Lint、构建、CI、分支保护、PR 审批。不要依赖「Agent 被要求不要这样做」。

两种门禁模式

本仓库的 Squad 工作流统一采用「阶段门禁 + 证据」的框架，但门禁层数有两种模式，按把关强度选择：

两层门禁怎么走（加强模式）：产出角色完成产物 → Leader 用 multica-verification 复跑验收/流程（管「对不对」）→ PASS 后派专属 Reviewer 用 multica-review-* 做专业分析（管「专不专业」）→ 评审 PASS 才放行；FAIL 则专属 Reviewer 汇报 Leader、指派作者修改、再复审，最多 3 轮，仍不通过升级人类。两层任一 FAIL 均退回，轮次独立计数但共用「3 次上限」。

专属 Reviewer 与产出角色一一对应（架构/UI/需求/前端/后端/测试各一名），不代替作者修改、结论汇报 Leader；Leader 与 DevOps 不配专属 Reviewer。详见 gates-and-evidence。

详细说明见：

与相关项目的关系

贡献

请不要提交「听起来不错」的 Prompt。一次有价值的贡献应包含：

1. 它解决的问题
2. 适用场景
3. 完整模板
4. 至少一个真实示例
5. 已知失败案例

实战经验比提示词复杂度更有价值。详见 CONTRIBUTING.md。

资源

• Multica GitHub
• Multica 文档
• How Multica works
• Agents
• Squads
• Tasks

安全

分享配置前必读 SECURITY.md：禁止上传 token、绝对路径、真实 workspace / 邮箱。

License

MIT

友链

• LinuxDo