system-design

系统设计

为初创公司生成采用模块化设计的全面技术架构文档。

子 Agent 架构

此技能使用并行研究 Agent，并提前提取内容。模式：D（研究 + 综合）+ E（分阶段流水线）。

Agent

Agent	角色	并行方式
prd-reader	阅读 PRD 和支持文档，并返回结构化提取结果	顺序执行（仅一次）
tech-researcher	负责一轮研究（并行启动 5 个实例）	并行执行（5 个实例）
tad-writer	根据所有输入生成完整的 tad.md	顺序执行（所有研究完成后）

研究轮次（并行执行 5 轮）

• 第 1 轮：技术栈验证（React、Node.js、PostgreSQL、Elasticsearch）
• 第 2 轮：基础设施验证（Vercel、AWS、CDN、成本估算）
• 第 3 轮：安全审查（身份验证、加密、合规性、API 安全）
• 第 4 轮：风险评估（瓶颈、供应商锁定、团队能力缺口）
• 第 5 轮：整体审查（与 PRD 的一致性、团队能力、快速见效方案）

并行策略

• PRD 内容：由 prd-reader 提取一次，不占用主上下文
• 研究独立性：每轮研究不同的概念角度（技术、基础设施、安全）
• 推理隔离：并行轮次让各领域的推理彼此隔离，避免群体思维
• 注意：研究轮次属于概念推理，并非数据获取；并行轮次不会产生本质不同的信息，但隔离有助于提升质量

结果：所有 5 轮并行完成后，tad-writer 将输出综合为统一的 TAD。

环境检查

执行前：

1. 确认项目目录中存在 prd.md
2. 检查是否有可用的支持文档（idea.md、validate.md）
3. 确认可使用 WebSearch 和 WebFetch 工具进行研究
4. 确认对项目根目录具有写入权限，以便创建 tad.md
5. 确认可访问 git，以便最终提交

编辑前同步仓库（强制）

在现有仓库中创建、更新或删除文件之前，先将当前分支与远程同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作树不干净，先暂存更改，再同步，最后恢复：

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果缺少 origin、无法拉取，或变基 / 暂存时发生冲突，请停止并先询问用户。

输入

$ARGUMENTS 中的项目文件夹路径，包含：

• prd.md - 产品需求（必需）
• idea.md、validate.md - 补充背景（可选）

工作流

阶段 1：设置与验证

1. 确认 prd.md 存在
2. 阅读支持文档（如果存在）
3. 阅读 references/tech-stack.md，了解技术建议
4. 如果已有 tad.md，先备份

阶段 2：提取背景信息

从 PRD 中提取：

• 产品名称和愿景
• 核心功能和需求
• 用户流程
• 非功能性需求
• 第三方集成
• 分析需求

阶段 3：明确架构

如果信息不明确，询问用户：

决策	选项
部署	Vercel/Netlify（推荐）、AWS、GCP、可自托管
数据库	PostgreSQL、MongoDB、Supabase/Firebase、多个数据库
身份验证	社交登录（OAuth）、邮箱 / 密码、Magic Link、企业 SSO
预算	免费套餐、<$50/mo、<$200/mo、灵活

阶段 4：研究与验证

开展 5 轮研究：

1. 技术栈：依据行业标准验证选型
2. 基础设施：比较托管服务的成本和可扩展性
3. 安全：根据所选技术栈审查 OWASP 指南
4. 风险评估：识别瓶颈和供应商锁定
5. 整体审查：确保符合 PRD，并评估初创公司的可行性

阶段 5：生成 TAD

创建 tad.md，包含以下章节：

1. 系统概述 - 用途、范围、与 PRD 的一致性
2. 架构图 - 系统和流程的 Mermaid 图
3. 技术栈 - 前端、后端、数据库、基础设施、DevOps
4. 系统组件 - 包含接口和依赖关系的模块化设计
5. 数据架构 - 架构、模型、流程、存储
6. 基础设施 - 托管、环境、扩展、CI/CD、监控
7. 安全 - 身份验证、授权、数据保护、API 安全
8. 性能 - 目标、优化策略、缓存
9. 开发 - 环境设置、项目结构、测试、部署
10. 风险 - 带缓解措施的风险矩阵
11. 附录 - 研究见解、备选方案、成本、术语表

完整模板结构请参阅 references/tad-template.md。

阶段 6：维护 README（ideas 仓库）

编写 tad.md 后，如果项目文件夹位于 ideas 仓库中，请更新仓库 README 的 ideas 表格：

• 首选：切换到仓库根目录并运行 python3 scripts/update_readme_ideas_index.py（如果该脚本存在）
• 备用方案：手动更新 README.md（确保该创意的 TAD 状态变为 ✅）

阶段 7：提交并推送（必须）

• 更新后立即提交。
• 立即推送到远程。
• 如果推送被拒绝：运行 git fetch origin && git rebase origin/main && git push。

调用此技能后，不要再请求额外的推送权限。

阶段 8：输出

1. 将 tad.md 写入项目文件夹
2. 总结架构决策
3. 突出模块化设计的优势
4. 按阶段列出成本估算
5. 建议后续步骤（设置开发环境、创建任务）

使用 GitHub 链接进行报告（必须）

报告完成情况时，必须包含：

• 指向 tad.md 的 GitHub 链接
• 如果更新了 README.md，则包含指向它的 GitHub 链接
• 提交哈希

链接格式（从 git remote get-url origin 获取 <owner>/<repo>）：

• https://github.com/<owner>/<repo>/blob/main/<relative-path>

步骤完成报告

完成每个主要步骤后，按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据步骤实际验证的内容调整检查项名称。通过时使用 √，失败时使用 ×，并使用 — 添加简要说明。“Criteria”行总结满足的验收标准数量。“Result”行给出总体结论。

各阶段专属检查项

阶段 1 — 设置

◆ Setup (step 1 of 8 — environment validation)
··································································
  PRD found:                    √ pass
  Context extracted:            √ pass (product + features + NFRs read)
  Architecture questions answered: √ pass (deployment, DB, auth, budget confirmed)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

阶段 4 — 研究

◆ Research (step 4 of 8 — validation rounds)
··································································
  5 parallel rounds completed:  √ pass
  Best practices gathered:      √ pass (tech, infra, security, risk, holistic)
  Patterns validated:           √ pass (OWASP, vendor lock-in, startup feasibility)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

阶段 5 — 生成

◆ Generation (step 5 of 8 — TAD authoring)
··································································
  11 sections written:          √ pass
  tad.md created:               √ pass
  Diagrams included:            √ pass (mermaid architecture + flow diagrams)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

阶段 8 — 输出

◆ Output (step 8 of 8 — delivery)
··································································
  Summary presented:            √ pass (architecture decisions highlighted)
  README updated:               √ pass (TAD status ✅)
  Committed and pushed:         √ pass (commit hash: ...)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

修改模式

针对现有 TAD 的修改：

1. 创建带时间戳的备份
2. 询问要修改哪些内容（技术栈、基础设施、安全、数据、扩展）
3. 在保留结构的前提下应用更改
4. 更新修订历史

指南

• 实用：提供适用于初创公司的可实施方案
• 控制成本：考虑预算影响
• 模块化：强调职责分离
• 具体：选择明确的技术方案
• 可视化：包含 mermaid 图