【system-architect】：一个让 AI 做架构建议时“说得清依据“的 Skill

开源地址：github.com/cptzzt/system-architect

这个 Skill 解决什么问题

用通用 AI（ChatGPT、Copilot 等）问架构问题，有三个具体的问题：

1. 建议没有依据。AI 给出方案后，无法说明这个方案来自教材、来自工程实践、还是来自它自己的推断。用户无法判断可信度。
2. 只讲收益不讲代价。架构设计本质是权衡，但 AI 倾向给出"看起来正确"的单一答案，回避代价分析。
3. 备考与实战需求冲突。备考「系统架构设计师」需要按教材原文判卷、做考点对齐；真实项目需要工程经验和团队上下文。同一套行为无法同时满足。

system-architect 针对这三点设计了一套约束机制：强制溯源、强制权衡、按场景区分行为。本质上是一个 Claude Code skill，但知识层（core/knowledge/）是纯 Markdown，可以迁移到 Cursor / Windsurf / Cline / Copilot 等任意工具。

核心机制

1. 强制溯源——每条建议必须标注来源

AI 给建议时按来源分类标注：

这条规则把"AI 编一个听起来对的答案"这条路堵死了。架构领域 AI 自身的知识可能过时或不准，强制标注来源等于把判断权交还给用户。

2. 内置知识层——10 章 35 个知识文件

core/knowledge/下覆盖系统架构设计师考试综合知识：

重要：知识层不含教材原文（版权属于出版社）。它是"读完权威教材后用自己的话重组的知识体系"，类似读完书写博客，可以独立工作。

每个知识文件是四层结构：

1. 核心知识体系 ← 知识本身 2. 顾问指引 ← 这块知识在真实项目里怎么用 3. 常见误区 ← AI 自检红线（防典型错误） 4. 自检清单 ← 给建议前过一遍

第三层"误区红线"是关键。光告诉 AI 正确答案不够，还要告诉它"最容易在哪犯错"。举一个真实的例子，数据库章节里写的：

❌ 两级映象方向搞反：外/概映象 =逻辑独立性，概/内映象 =物理独立性（不是反过来）
❌ 以为 SQL 操作内模式：应用操作的是外模式
❌ 故障恢复原理说成"备份"：教材原意是"建立冗余数据"

这三条是 AI 和初学者都容易踩的坑。在知识文件里固化成红线后，AI 给建议前会先自检，避开了这些典型错误。

3. 教材边界——有教材更强，无教材也能用

教材有版权，不能塞进开源项目。这个 skill 的处理方式：

• 默认（无教材）：靠知识层 + 工程经验工作。涉及工程经验会显式标注"非权威依据"。
• 接入教材（可选）：把教材电子版（推荐 Markdown；PDF 可用 MinerU 转成带页码的 md）放进textbook/目录，或改配置里的路径。这时 AI 能引用教材出处（标文件名 + 章节/页码），判卷以教材原文为唯一标准，做考点对齐。
• 降级机制：教材路径失效时，自动降级到"无教材"状态，并告知用户。不会假装有教材、不会编页码。

这套设计不绑死使用方式——纯白嫖知识层的、接教材做强溯源的，都能用。

4. 用户上下文——改几行配置，AI 适配个人

SKILL.md顶部有一段可编辑的"用户上下文"：

技术栈：[如 Java/Spring Boot, MySQL/MariaDB, Docker, React] 项目方向：[如 Web 后端 / 数据平台 / 移动端] 关注的质量属性：[如 性能 / 可用性 / 成本] 是否备考系统架构设计师：[是/否] 教材路径：[无 / textbook/ / 自定义路径]

AI 每次会话读这段配置来适配用户。备考用户和实战用户、不同技术栈、不同关注的质量属性——给的建议会不一样。这影响的是举例方式和行为路由（按"是否备考"判断主场景）。

三种模式，无需手动切换

模式不是状态机，是 AI 根据问题自然匹配的行为指引。

架构顾问模式（默认）

触发：真实项目问题（“我的项目表怎么设计”）。

流程：澄清场景（规模/约束/技术栈/质量目标）→ 关联知识层 → 给建议带依据 → 讲权衡 → 暴露不确定性。

自检红线防典型错误：不凭自身知识编造、不混淆"表结构设计（逻辑层）“和"建库运行（实施层）”、不把单表内"传递依赖"和跨表外键搞混。

学习导师模式（备考用户）

触发：用户上下文"备考=是"，或问考试/真题/论文。

学习流程：提取目录 → 出学前引导题 → 讲解（原理 + 类比 + 考点 + 挂钩用户技术栈）→ 用户提问 → 出学后验证题 → 收尾（一页纸总结 + 进度更新）。

判卷红线：判卷前必须回教材核实；不拿 AI 领域知识纠正教材已有的正确说法；记录用户原话，不编造用户回答。

配套复习体系：学习后建复习看板，追踪每章的重要度、学完日期、掌握度、薄弱点。明确"掌握度颜色是自测结果，不是学完自动变绿"。

技术选型模式

触发：“A vs B 怎么选”、“评审这个方案”。

产出结构化对比表（候选方案 × 决策维度），结合用户上下文，给倾向但说清"什么情况下推荐失效"。架构评审 checklist 覆盖：质量属性需求是否明确、架构风格是否匹配场景、关键权衡是否识别（CAP、一致性 vs 可用性）、是否有单点故障、是否过度设计（YAGNI）。

目录结构

system-architect/ ├── SKILL.md ← 主体（架构师内核 + 用户上下文 + 教材边界 + 行为路由） ├── README.md ├── LICENSE ← MIT ├── core/ │ ├── 教材边界.md ← 有/无教材各能做什么（AI 必读） │ └── knowledge/ ← 内置知识层（10 章，按需加载） │ ├── README.md ← 三层索引 + 主题导航 │ ├── 02-计算机系统/ … 06-数据库/ （已校验） │ └── 07-架构设计/ … 11-未来信息/ （未校验） ├── modes/ ← 可选模式（架构顾问/学习导师/技术选型） └── textbook/ ← 用户教材（自备，.gitignore，不入库）

SKILL.md只做精简路由（不超过 500 行），知识按主题按需加载（progressive disclosure）。AI 根据问题两次跳转定位相关知识，不全量读 35 个文件。

与现有方案的差异

"学习→顾问延续"指：备考用户学完教材后，AI 自然从导师过渡到顾问——学到的架构知识正是 AI 给实战建议时的知识层，学和用是同一套体系。

使用方式

Claude Code

1. 克隆仓库到 Claude Code 的 skills 目录
2. （可选）教材放textbook/目录
3. 编辑SKILL.md顶部"用户上下文"
4. 直接问架构问题（自动套架构顾问模式），或说"我要备考"（套学习导师模式）

其他工具

知识层（core/knowledge/）工具无关。把SKILL.md指令复制到对应工具的规则文件，调整子文件引用语法即可：

设计取舍

为什么"可溯源"比"答案正确"更重要。AI 不可能 100% 正确，这是前提。强制它标注来源，用户就能自己判断可信度。把判断权交还用户，比让 AI 包装成权威更有价值。

为什么用误区红线而非只讲正确答案。光告诉 AI “正确是什么"不够，还要告诉它"最容易在哪犯错”。预防错误比灌输正确更有效。

为什么诚实声明能力边界。有教材和没教材是两种能力，skill 明确声明各自边界并提供降级机制。宁可 AI 说"这条不确定"，也不要它编一个看起来对的答案。

为什么不全量加载知识。progressive disclosure——用到什么读什么。既省 context，又精准。

状态与协议

• 协议：MIT 开源
• 状态：持续迭代中
• 已覆盖：综合知识 2-11 章（其中 2-6 章经学习纠错校验，7-11 章标注未校验，待学到对应章节时核实）
• 待补：案例 12-19 章、论文 20 章
• 版权：skill 绝不含教材原文，用户教材需自备

项目地址：github.com/cptzzt/system-architect

问题、建议、知识层校验贡献都欢迎提 issue 或 PR。