system-architect（系统架构师）Skill 是什么？如何用 AI 完成架构设计与 C4 图？

系统架构师Skill：让 AI 代理用 C4 模型、ADR 和权衡分析把架构设计讲清楚

它是什么：system-architect（系统架构师）是一个以 Copilot 代理形式工作的架构设计助手，专注架构设计、C4 模型图、ADR（架构决策记录）与权衡分析四件事。
怎么协作：它不会一次性输出内容，而是按“一问一答”的 5 阶段流程先访谈、再确认、再分阶段生成文档，避免架构方案脱离业务上下文。
产出什么：架构设计书、C4 上下文、容器、组件图（Mermaid）、技术选型与权衡分析、ADR、安全架构设计、迁移路线图，并按英文版 + 日文版双语落盘到 ./design/architecture/ 目录。
强在哪：把“随手问一句 AI”变成“有方法论、有产出物、有项目记忆”的工程化流程，并且会读取 steering/ 下的项目记忆文件，保证与其他代理的工作保持一致。
适合谁：正在做新系统设计、单体拆微服务、云迁移，或需要把架构决策过程沉淀成可追溯文档的技术负责人、后端架构师与研发团队。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目	内容
技能中文名	系统架构师Skill
技能英文名	system-architect
技能ID	13455
形态	Copilot 代理（Agent）
允许使用的工具	Read、Write、Edit、Bash、Glob、Grep
触发术语	架构、系统设计、C4模型、ADR、架构决策、设计模式、组件设计、架构图、微服务、单体、可扩展性

它解决什么问题

架构设计最大的痛点往往不是“不知道有哪些模式”，而是三件事：

信息收集不全就下结论——需求、规模、质量特性、技术约束没问清楚，直接给出“上微服务”的结论；
决策过程无法追溯——半年后没人记得为什么选了 PostgreSQL 而不是 NoSQL；
文档不成体系——画了一张图，但没有上下文图、没有容器图、没有 ADR、没有权衡分析，评审时无从讨论。

系统架构师Skill 正是把这三件事打包成流程：先用结构化访谈补齐上下文，再用 C4 模型 + ADR + ATAM 权衡分析方法产出成套文档。

“一键安装”AI 技能的思路与步骤

所谓“一键安装”，本质是把技能接入到你的 AI 编码助手（Copilot 类环境）中，让它成为一个可被调用的代理。通用步骤如下（具体命令与入口以官方说明为准）：

准备安装前提
- 已具备支持自定义技能 / 代理的 AI 助手环境（Copilot 类工具）；
- 本地项目可被该助手读取（因为该技能需要 Read / Glob / Grep 来读取项目文件与 steering/ 记忆文件）；
- 项目根目录具备写权限，因为技能会把成果物写入 ./design/architecture/。
安装技能
- 在技能市场 / 技能管理入口中搜索技能英文名 system-architect 或技能ID 13455；
- 选择安装并启用，授予 Read / Write / Edit / Bash / Glob / Grep 这些它声明需要的工具权限；
- 若你的环境采用配置文件方式管理技能，则按官方文档把技能定义添加到对应配置目录（以官方说明为准）。
验证是否生效
- 在对话中输入包含触发术语的请求，例如：“请帮我做一次架构设计，我们要把单体拆成微服务”；
- 若技能生效，它会以“系统架构师AI”的身份开场，并抛出【问题 1/6】项目类型是什么（新系统设计 / 现有系统重构 / 微服务迁移 / 云迁移 / 其他）；
- 如果它只是普通地长篇回答而没有进入访谈流程，说明技能未被正确加载，需回到技能管理入口检查启用状态。

提示：安装包大小、命令形式、是否收费等信息，本技能详情中未提供，请以官方说明为准。

2. 该技能的主要功能和特点

核心能力

架构设计：整体结构、组件划分、职责设计，从“系统边界”开始而不是从技术栈开始。
架构模式库：分层架构、六边形 / 清洁架构、微服务、事件驱动、无服务器、模块化单体——每种模式都会给出适用条件与代价，而不是只报名字。
分布式系统分析：CAP / PACELC 定理取舍、水平扩展 vs 垂直扩展、缓存策略（旁路缓存 / 读通过 / 写后）、分布式事务（Saga / 2PC / TCC）。
数据架构：数据建模、一致性选择、CQRS、事件溯源。
安全架构：零信任、OAuth 2.0 / OIDC / RBAC / ABAC、深度防御、STRIDE / DREAD 威胁建模。
云与基础设施：AWS / Azure / GCP、IaC（Terraform / Bicep）、Kubernetes、服务网格。
可观察性设计：指标、日志、分布式追踪、SLO / SLA 与告警设计。
技术选型与权衡分析：ATAM、收益矩阵、ADR 三种手段并用。
文档产出：C4 模型图（Mermaid 代码，可直接渲染）、ADR、架构设计文档。

差异化特点

强制一问一答：明确禁止一次抛出多个问题，必须等用户回答后再进入下一题，并显示“👤 用户: [等待回答]”。这让访谈不会变成一张让人放弃填写的问卷。
项目记忆（steering）机制：开工前强制读取 steering/structure.md（架构模式、目录组织、命名约定）、steering/tech.md（技术栈、框架、技术约束）、steering/product.md（业务上下文、目标用户）。这让它给出的方案与项目既有约定对齐，而不是“另起一套”。
分阶段、小步落盘：文档超过 300 行必须拆分保存，一次只创建一个文件，每个文件完成后请用户确认。这规避了长文档生成中断导致成果全丢的问题。
双语文档政策：所有文档先生成英文版 filename.md，再生成日文版 filename.ja.md；引用其他代理成果物时，一律引用英文版 .md。
与工作流引擎集成：设计阶段开始执行 musubi-workflow next design，完成时执行 musubi-workflow next tasks，并附带设计完成清单（C4 模型、ADR、需求追溯性、非功能需求反映、利益相关者评审）。
端到端有模板：架构设计书模板包含执行摘要、架构概要、C4 各层图、技术栈、质量特性实现、数据架构、安全架构、可观察性、迁移策略、权衡分析、技术债务、实现路线图、术语表与变更历史。

和普通工具比强在哪

普通绘图工具能画图，但不知道你为什么这么画；通用对话大模型能聊架构，但不会检查项目记忆、不会主动把决策写成 ADR、不会把文档按规范命名落盘。系统架构师Skill 把“方法论 + 上下文 + 产出物”绑在一起。

3. 如何使用该技能？

步骤 1：准备好项目记忆（可选但强烈推荐）

在项目根目录准备 steering/ 目录，至少包含：

steering/structure.md：架构模式、目录组织、命名约定
steering/tech.md：技术栈、框架、开发工具、技术约束
steering/product.md：业务上下文、产品目的、目标用户、核心功能

如果文件不存在，技能仍然可以继续工作，但会建议你先补齐项目记忆。

步骤 2：用触发术语唤起技能

在对话中自然描述任务即可，只要包含触发术语（架构、系统设计、C4模型、ADR、微服务、单体、可扩展性等）就会被识别。例如：

我们要做一个面向 C 端的预约系统，用户量预计 50 万，请帮我做架构设计，并输出 C4 模型图和 ADR。

步骤 3：完成第一阶段访谈（6 个问题）

技能会逐个提问，你需要逐个回答：

项目类型（新系统设计 / 重构现代化 / 微服务迁移 / 云迁移 / 其他）
系统规模（<1万人 / 1万~100万人 / >100万人 / 未定）
最重要的质量特性（性能 / 可扩展性 / 可用性 / 安全性 / 可维护性 / 成本效率，可多选）
技术约束（特定云厂商 / 本地部署 / 沿用现有技术栈 / 需集成遗留系统 / 无特别约束）
期望成果物（架构设计书 / 技术选型与权衡分析 / ADR / 安全架构设计 / 迁移路线图 / 全部）
是否已有需求书或设计书（有则提供路径）

步骤 4：完成第二阶段细节访谈

围绕架构模式（单体 / 模块化单体 / 微服务 / 无服务器 / 未定求推荐）、数据库策略（单一 RDBMS / 每服务一库 / CQRS / 事件溯源）、安全需求（认证方式、授权方式、加密、零信任、合规要求）、可扩展性需求（水平扩展 / 垂直扩展 / 多区域 / 峰值流量）、可观察性需求（全量可观察性 / 基础指标 / SLO 定义 / 分布式追踪）继续逐个确认。若是重构或迁移场景，还会追问现有架构、技术栈、当前问题与停机容忍度。

步骤 5：确认汇总信息

技能会把收集到的项目概要、质量特性优先级、架构需求、现有系统情况、期望成果物整理成一份清单让你复核，你可以直接说“第 3 项补充：峰值 8000 QPS”。

步骤 6：批准并分阶段生成成果物

确认后技能会列出生成计划（通常是 6 类文档 × 2 种语言 = 12 个文件），并逐个生成、逐个汇报进度：

🤖 [1/12] 生成架构设计书英文版...
📝 ./design/architecture/architecture-design-xxx-20251112.md
✅ 保存完成

大文档（>300 行）会自动拆成多部分保存，例如先存“概要 & 组件设计”280 行，再存“数据流 & 部署策略”250 行，最后汇总为 530 行。

步骤 7：确认成果物并推进下一阶段

生成完毕后，技能会给出下一步建议：确认成果物与反馈、追加设计、或移交给 Database Schema Designer、API Designer、Cloud Architect、DevOps Engineer 等下游代理。

步骤 8：更新项目记忆

最后技能会把本次设计的架构模式、目录结构、组件组织、设计原则、关键技术决策回写到 steering/structure.md 与对应语言版本，使其他代理后续能读到最新架构信息。

输出示例（C4 容器图片段）

C4Container
    title Container Diagram for 预约系统
    Person(user, "用户", "最终用户")
    Container_Boundary(sys, "预约系统") {
        Container(web, "Web应用", "React", "提供UI")
        Container(api, "API网关", "Node.js/Express", "REST API")
        ContainerDb(db, "数据库", "PostgreSQL", "存储数据")
        ContainerDb(cache, "缓存", "Redis", "会话缓存")
    }
    Rel(user, web, "使用", "HTTPS")
    Rel(web, api, "调用", "HTTPS/JSON")
    Rel(api, db, "读/写")

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势	不足
system-architect（系统架构师Skill）	工程化架构设计代理	结构化访谈、C4 模型图、ADR、ATAM 权衡分析、安全架构、迁移路线图、项目记忆回写	需在支持技能的 AI 助手中启用并授权工具；需准备 steering 文件（可选）	新系统设计、单体拆微服务、云迁移、需要可追溯决策文档的团队	流程完整、产出物成体系、与项目上下文对齐、文档分阶段落盘不丢成果	产出文档默认英文 + 日文双语；访谈需逐题回答，前期投入时间较多
通用对话大模型（直接提问）	通用问答助手	任意架构问题解答、代码片段、文字解释	极低，打开即问	快速获取概念解释、头脑风暴、单点技术问题	上手最快、无流程约束、灵活	不会主动补齐上下文、不落盘成规范文档、决策过程难以追溯、容易给出脱离项目实际的方案
绘图 / 文档工具（Mermaid、PlantUML 等）	图形与文档绘制工具	画架构图、导出图片、协作编辑	低，需自己写图代码或拖拽	已有明确架构后出图、汇报材料	图形表现力强、可精细控制排版	不具备架构推理能力，无法回答“为什么这样设计”，不产出 ADR 与权衡分析
传统架构方法论与建模工具（ATAM、4+1 视图等人工流程）	方法论 + 人工评审	质量属性分析、场景评审、架构文档规范	高，需要资深架构师主持评审会	大型企业级系统、强合规行业	严谨、评审充分、利益相关方共识度高	周期长、人力成本高、文档撰写工作量大、小团队难以承担

选型建议：如果你只是临时想搞懂“CAP 定理到底怎么取舍”，直接问通用模型最快；如果架构已经想清楚只差出图，绘图工具更合适；如果你需要一份能被评审、能追溯决策、能交给下游代理继续使用的架构文档集，系统架构师Skill 的投入产出比最高。

5. 该技能的典型应用场景与实际体验情况

场景一：初创团队从 0 到 1 设计新系统

角色与痛点：技术负责人一人兼架构师，知道要做预约系统，但不确定该上单体还是微服务，也担心过度设计。
使用方式：以“新系统设计 + 中规模（1万~100万人）+ 可扩展性与成本效率优先”回答访谈，架构模式选择“未定（需要推荐）”。
实际体验：技能会输出架构模式对比表（复杂性、可扩展性、开发效率、运营成本四个维度），并倾向推荐模块化单体作为起点，同时在 ADR 中记录“为何暂不采用微服务”。对初创团队来说，这类“反向建议”比堆砌新技术更有价值。上手难度低，但需要你如实回答规模问题，否则结论会失真。

场景二：遗留单体系统拆分微服务

角色与痛点：后端架构师面对一个运行多年的大单体，拆到哪里、先拆哪个、数据怎么切分，团队内部意见不一。
使用方式：项目类型选“微服务迁移考虑”，补充现有架构、技术栈、当前问题（如发布耦合、数据库锁竞争）与停机容忍度，成果物勾选“迁移计划/路线图 + ADR”。
实际体验：技能会追问迁移停机容忍度并给出分阶段路线图，风险评估以表格形式列出（风险 / 影响 / 概率 / 缓解措施），分布式事务部分会对比 Saga、2PC、TCC 的适用条件。注意事项：现有系统的真实痛点需要你提供足够细节，否则路线图会偏模板化。

场景三：安全与合规要求高的系统设计

角色与痛点：金融或医疗类项目，安全评审时被追问认证授权方案、加密策略与威胁模型，临时补文档非常痛苦。
使用方式：安全需求详细说明认证方式（OAuth 2.0 / OIDC / SAML）、授权方式（RBAC / ABAC）、存储与传输加密、是否采用零信任、是否有 GDPR 等合规要求，成果物勾选“安全架构设计”。
实际体验：产出包含认证 / 授权、数据保护（TLS 1.3、密钥管理）、网络安全（防火墙 / WAF / DDoS 防护）、STRIDE 威胁模型分析等章节，直接可作为评审输入。注意事项：技能提供的是设计框架与方法，具体合规条文的最终判定仍需法务或安全团队确认。

场景四：多代理协作团队的文档一致性

角色与痛点：团队使用多个 AI 代理分别做需求、架构、API 设计、数据库设计，结果各自的文档互相引用不上，术语和目录结构也对不齐。
使用方式：预先维护好 steering/structure.md、tech.md、product.md，每次架构任务前让技能读取；设计结束后让其回写 structure.md。
实际体验：这是该技能最被低估的能力。因为技能强制“引用英文版 .md、指定路径不用 .ja.md”，跨代理引用不会错链；设计完成后的转向更新会把架构模式、目录结构、设计原则同步给下游代理。注意事项：steering 文件需要团队自己维护质量，内容过时会让方案跟着跑偏。

整体上手感受：上手难度中等偏低，真正的门槛在于“愿不愿意认真回答那 11~12 个问题”。效果上，产出物完整度和可追溯性明显优于直接对话；需要注意的两点是——访谈环节不能跳步，且最终文档默认是英文 + 日文双语，若团队需要其他语言版本，需在后续环节另行处理（以官方说明为准）。

6. 该技能能为用户带来的价值

效率提升

把“查资料 + 想方案 + 画图 + 写文档”四件事合并到一条流程里。以 6 类文档 × 2 种语言 = 12 个文件的产出量计算，人工撰写通常需要数天，而该技能通过分阶段落盘逐份产出，中途即可评审，返工成本被显著压低。
大文档自动拆分（>300 行拆成多部分保存），避免了长文档生成中断重来的时间浪费。

门槛降低

没有资深架构师的小团队，也能获得一套包含 CAP / PACELC、Saga、CQRS、STRIDE 等专业框架的分析框架，而不是凭直觉拍板。
C4 模型图以 Mermaid 代码产出，不需要额外学习绘图工具；ADR 有固定模板，写决策记录不再是负担。

可量化的收益方向

决策可追溯：每个关键技术决定都有独立 ADR 文件（如 adr-001-microservices-adoption.md），包含上下文、备选方案、选定理由、影响与验证方法，减少后期“为什么这么选”的反复讨论。
评审一次通过率：设计完成清单（C4 模型完整、ADR 完成、需求追溯性确认、非功能需求反映、利益相关者评审）本身就是评审检查表。
跨角色对齐成本：项目记忆回写机制让下游代理与新人能直接读到最新架构约定，减少重复解释。

长期价值

架构文档的真正价值在于半年后仍然可用。该技能产出的不是一次性回答，而是一个有目录规范（./design/architecture/）、有命名规范（architecture-design-{project-name}-{YYYYMMDD}.md）、有变更历史表格的文档资产库——这才是它与其他方案最本质的差别。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

A：安装方式取决于你所使用的 AI 助手环境，一般在技能市场或技能管理入口搜索英文名 system-architect 或技能ID 13455 后启用，并授予 Read / Write / Edit / Bash / Glob / Grep 工具权限即可。具体的安装命令、入口位置与是否收费，本技能详情中未提供，请以官方说明为准。

Q2：它会不会直接给我一大堆文档，但内容很空？

A：这正是它设计上要避免的。技能强制“一问一答”，第一阶段必须逐个回答 6 个基础问题，第二阶段继续确认架构模式、数据库策略、安全、可扩展性、可观察性等细节，确认汇总信息后才开始生成文档。你提供的信息越具体（峰值流量、停机容忍度、合规要求），产出就越贴合实际；如果一路“未定”到底，文档自然会偏框架性。

Q3：它和直接问 ChatGPT / Claude 架构问题有什么区别？

A：区别在三点：一是会读取并遵循 steering/ 下的项目记忆文件，方案与项目既有约定对齐；二是有强制流程与产出物规范（C4 图、ADR、权衡分析表、安全架构、迁移路线图），并按固定命名落盘；三是它会回写项目记忆，让其他代理后续能复用这次设计。如果你只是需要一个概念解释，直接问通用模型更快。

Q4：适合谁用？前端或非架构岗能用吗？

A：最适合技术负责人、后端架构师、需要承担架构职责的高级工程师，以及使用多代理协作流程的研发团队。非架构岗也可以用——访谈环节本身就是引导式的，你只要如实回答业务规模、质量特性和技术约束，它会给出模式推荐与权衡说明，是很好的学习路径。

Q5：产出文档为什么是英文版 + 日文版双语？我需要中文文档怎么办？

A：这是技能定义中的文档语言政策：所有文档先用英文创建 filename.md，再生成日文版 filename.ja.md，且跨代理引用时一律引用英文版 .md。如果你的团队需要中文版本，建议在获取成果物后按团队规范另行处理；具体是否支持其他语言输出，以官方说明为准。

Q6：它能直接改我的代码或搭建云环境吗？

A：不能。它的工具权限限定为 Read、Write、Edit、Bash、Glob、Grep，主要用来读取项目文件、检索代码上下文、写出架构文档与 Mermaid 图代码。云资源创建、CI/CD 搭建等落地工作，技能会在结束时建议移交给 Cloud Architect、DevOps Engineer 等下游代理。它提供的是设计与决策依据，不是部署执行。