it235/multica-best-practices/multica-technical-design

Technical Design

Purpose

基于 PRD（或 Issue）与现有代码库，产出最小可行的技术设计（只管「写什么」，不管「落到哪个平台」）。

与 multica-artifact-architect 分工：technical-design 产出结构与内容；artifact-architect 校验产物并调用 Confluence/JIRA platform skills 落地。

与 multica-review-architect 配合：初稿 → 评审 → 修订 → 复审（最多 3 轮），每轮修订须递增版本并填写「评审回应」。

Platform 协作

本 skill 只产出本地 design.md；凭据与发布 CLI 见 platform skill。

Process

1. 读 PRD / Issue 与验收标准（AC-/FR-/BR-）。
2. 检查当前实现（优先 codegraph / 现有模式，不大面积扫库）。
3. 识别相关模块与现有模式。
4. 确定最小可行改动；非目标写清楚。
5. 识别数据/接口/非功能影响与依赖（RISK-、DECISION-）。
6. 定义验证方式（对齐 AC-）；填需求追溯表。
7. 写文档头部元数据（创建者、创建时间、版本、状态）。
8. 信息不足 → BLOCKED，写入「待决事项」，不猜。

Principles

现有模式 > 新抽象
小改动   > 大重构
复用     > 新依赖
可验证   > 不可验证的设想
可回滚   > 一次性不可逆改动

本地草稿路径

docs/design/<ISSUE-KEY>/design.md

章节基线见 multica-platform-confluence/scripts/templates/design-template.md。

文档头部（必须，置于 H1 标题下）

设计正文第一块必须是元数据表，便于 ArchReviewer 追踪版本与责任人：

示例：

# 技术设计 — PROJ-1813 分片上传
 
| 字段 | 值 |
| --- | --- |
| **创建者** | Architect-u1024 |
| **创建时间** | 2026-08-26 15:30 |
| **版本** | v0.1 |
| **状态** | 草稿 |
| **JIRA** | PROJ-1813 |
| **上游 PRD** | http://confluence.../pages/viewpage.action?pageId=... |

Output（必须包含）

架构师写作角度（易漏项）

设计评审常在这些角度被追问，初稿尽量覆盖：

复审修订流程（配合 multica-review-architect）

1. 读 Leader 转发的 ArchReviewer 修改清单（含阻断项 ID）。
2. 版本 +1（如 v0.1 → v0.2），状态改 评审中。
3. 在 评审回应 表逐条填写：已修改 / 不采纳（须写理由）。
4. 更新受影响章节；修订记录追加一行。
5. 重新自检 → multica-artifact-architect → platform 发布（Confluence upsert 同 title 会更新版本）。
6. 通知 Leader 已修订，进入下一轮 ArchReviewer 复审（最多 3 轮）。

不采纳阻断项须 Leader 裁决，Architect 不得自行关闭评审。

Handoff

先用 multica-technical-design 写 docs/design/<ISSUE-KEY>/design.md（含头部元数据），
再用 multica-artifact-architect 自检后按 platform skill 发布并回传链接。

发布命令见 multica-platform-confluence（publish_design.py --append-jira）。

为什么有效

头部元数据 + 版本 + 评审回应，让多轮 ArchReviewer 评审可审计、可 diff；章节覆盖数据/非功能/追溯等角度，减少下游实现阶段返工。