GSD 架构研究模板全解析：为 spec-driven 开发管线产出可落地的系统架构蓝图

GSD 架构研究模板全解析：为 spec-driven 开发管线产出可落地的系统架构蓝图

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

本文围绕 get-shit-done（GSD）开源仓库中的架构研究模板 ARCHITECTURE.md 展开。它是 GSD 项目研究（Research）阶段的产物之一，负责回答"这个领域的系统通常长什么样"，并把结论落盘为.planning/research/ARCHITECTURE.md，直接供给后续 roadmap 生成。读完本文，你将掌握该模板九大区块的填写方法、其内置写作准则，以及它如何在 GSD 的 SDK 源码中被四路并行研究与总结（synthesis）机制调用的完整链路，从而能在自己的 AI 辅助开发工作流中复刻这套"研究→架构→规划"的工程方法。

模板定位：架构研究在 GSD 管线中的角色

GSD 是一个"轻量但强大"的 meta-prompting / context engineering / spec-driven development 系统。在/gsd:new-project与/gsd:new-milestone编排流程中，存在一个明确的Research（研究）阶段（Phase 6）：在生成 roadmap 之前，先对项目所属领域进行生态调研，产出四份研究文档：

这一角色关系在 gsd-project-researcher.md 中有明确表格说明：ARCHITECTURE.md的产出直接决定 roadmap 中"系统结构、组件边界"的规划依据。换句话说，架构研究不是写给自己看的笔记，而是 roadmap 生成的输入工件。

在 SDK 侧，init-runner.ts 定义了四种研究类型与 prompt 路由的映射：

STACK: 'research-stack', FEATURES: 'research-features', ARCHITECTURE: 'research-architecture', PITFALLS: 'research-pitfalls',

buildResearchPrompt（init-runner.ts）会读取templates/research-project/${researchType}.md模板文件，把模板内容包裹进<research_template>...</research_template>标签交给研究员 Agent，并要求"Write.planning/research/${researchType}.mdfollowing the template structure"。因此，本模板的真实消费者是一个具备 Read/Write/WebSearch/Context7 等能力的 AI 研究员（详见 gsd-project-researcher.md）。

模板整体骨架：九大区块概览

模板文件整体采用<template>（可复制正文）与<guidelines>（写作准则）双区结构，其中正文模板包含九个主题区块：

这样的结构安排意味着：先画全局（Overview）→ 拆职责（Components）→ 落到目录（Structure）→ 提炼模式（Patterns）→ 验证数据流（Data Flow）→ 评估扩展（Scaling）→ 规避雷区（Anti-Patterns）→ 理清协作（Integration）→ 记录来源（Sources），是一条从粗到细、从结构到行为、从正面到反面的完整推理链。

逐区块实战详解

System Overview：用 ASCII 分层图表达系统全貌

模板要求使用 box-drawing 字符（├── └── │ ─）绘制分层架构图，示意结构如下：

┌─────────────────────────────────────────────────────────────┐ │ [Layer Name] │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ [Comp] │ │ [Comp] │ │ [Comp] │ │ [Comp] │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ ├───────┴────────────┴────────────┴────────────┴──────────────┤ │ [Layer Name] │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────────┐ │ │ │ [Component] │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ [Layer Name] │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ [Store] │ │ [Store] │ │ [Store] │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘

填写要点（对应模板<guidelines>）：

• 展示主要组件及其关系，而不是罗列所有类——这是概念层，不是实现层；
• 不要过度细节化：图中一个单元格代表一个逻辑组件，具体类和方法留给后面的 Patterns 小节；
• 分层顺序建议按"上层消费下层"排列：展示层 / 应用层 / 领域层 / 基础设施层是常见惯例，但应贴合所选技术栈（前端项目可能分层为 UI / State / API Client 等）。

Component Responsibilities：明确"谁拥有什么"

模板给出三列表格，每条组件一行：

填写建议：

• Responsibility 用动词短语描述"拥有的东西"（例如 "owns user session lifecycle"），而不是描述它调用了谁——职责边界是架构图能否落地的关键；
• Typical Implementation写该领域主流做法（如 "Redis-backed session store"、"gRPC service in Go"），为 STACK.md 的技术选型提供呼应；
• 组件数量应与 System Overview 图中的组件一一对应，避免出现"图上有、表里没有"或反之的漂移。

Recommended Project Structure：目录组织与理由

模板要求给出具体的目录结构树，并逐目录说明理由：

src/ ├── [folder]/ # [purpose] │ ├── [subfolder]/ # [purpose] │ └── [file].ts # [purpose] ├── [folder]/ # [purpose] │ ├── [subfolder]/ # [purpose] │ └── [file].ts # [purpose] ├── [folder]/ # [purpose] └── [folder]/ # [purpose]

指南强调三条纪律：

• 对目录组织要具体，不要只写src/一层；
• 解释分组理由（如 "按领域聚合而非按技术分层"、"feature-first 以便独立发布"），理由比目录名更重要；
• 贴合所选技术栈的惯例（模板示例用.ts文件即暗示 TypeScript 栈，可对齐该领域的社区目录规范）。

Architectural Patterns：模式卡片的四要素

模板为每个模式定义了统一的"卡片"格式：

What:模式是什么When to use:适用条件Trade-offs:优缺点Example:TypeScript 代码示例

### Pattern 1: [Pattern Name] **What:** [description] **When to use:** [conditions] **Trade-offs:** [pros and cons] **Example:** ```typescript // [Brief code example showing the pattern]

指南强调两点： - **代码示例要有帮助**——一个 5~15 行的最小可读示例优于大段文字描述； - **诚实呈现 trade-offs**，并特别注明"何时该模式对小型项目是过度设计（overkill）"，防止研究员无脑堆模式。 ### Data Flow：请求流、状态管理与关键数据流 模板提供三种视角的流程图骨架： 请求流（单向链路 + 回程）：

[User Action] ↓ [Component] → [Handler] → [Service] → [Data Store] ↓ ↓ ↓ ↓ [Response] ← [Transform] ← [Query] ← [Database]

状态管理（订阅驱动的数据变更）：

[State Store] ↓ (subscribe) [Components] ←→ [Actions] → [Reducers/Mutations] → [State Store]

关键数据流（编号清单）： 1. **[Flow name]:** [description of how data moves] 2. **[Flow name]:** [description of how data moves] 填写时建议区分"请求路径"（用户操作如何贯穿全链路）与"状态同步路径"（数据变更如何通知到 UI），二者不要混在一张图里；关键数据流选取 2~4 条对架构理解最重要的路径即可（如登录、下单、实时推送）。 ### Scaling Considerations：现实主义的扩展规划 模板给出"按规模分档"的调整表： | Scale | Architecture Adjustments | |-------|--------------------------| | 0-1k users | [approach — usually monolith is fine] | | 1k-100k users | [approach — what to optimize first] | | 100k+ users | [approach — when to consider splitting] | 并附 Scaling Priorities： 1. **First bottleneck:** [what breaks first, how to fix] 2. **Second bottleneck:** [what breaks next, how to fix] 指南明确反对"百万级洁癖"： - **保持现实**——大多数项目不需要扩展到百万用户； - **聚焦"什么先坏"**，而不是理论极限； - **避免过早优化建议**——0-1k 用户时单块应用（monolith）通常完全够用。 这一节的价值在于让 roadmap 排序时知道"哪一步必须现在做、哪一步可以以后再说"。 ### Anti-Patterns：先写错法，再写替代 反模式卡片同样采用三段式： **What people do:** 人们常犯的错 **Why it's wrong:** 会造成什么问题 **Do this instead:** 正确做法 指南特别强调反模式必须"对该领域具体"（不写泛泛的"代码没注释"之类），且**必须包含替代方案**——只列坑不给解药等于没写。它直接服务于 roadmap 阶段的实现规避（对应 PITFALLS.md 的 pitfall-to-phase 映射思路）。 ### Integration Points：外部服务与内部边界 外部服务表： | Service | Integration Pattern | Notes | |---------|---------------------|-------| | [service] | [how to connect] | [gotchas] | 内部边界表： | Boundary | Communication | Notes | |----------|---------------|-------| | [module A ↔ module B] | [API/events/direct] | [considerations] | 填写时注意：外部服务写"连接方式 + 已知坑"（如认证方式、限流、数据一致性）；内部边界写"通信机制"（API / 事件 / 直接调用），并注明耦合风险。这一节是后续集成阶段（integration phase）最直接的输入。 ### Sources：为每一条结论留证据

• [Architecture references]
• [Official documentation]
• [Case studies]

结合研究员 Agent 的验证协议（[gsd-project-researcher.md](https://link.gitcode.com/i/b25aa4f7bb4d6639e79d72630a48b021)），Sources 应标注证据层级：Context7 库文档 / 官方文档 / 案例研究，并按置信度（HIGH/MEDIUM/LOW）分类，LOW 置信度的结论必须显式标记"需验证"。 ## 模板内置写作准则（guidelines）解读 模板后半段的 `<guidelines>` 是模板的"使用说明书"，其核心思想可归纳为五条： 1. **Overview 要克制**：ASCII 图只做结构与关系可视化（`├── └── │ ─`），"概念而非实现"，不要画到类方法粒度； 2. **Structure 要具体**：目录组织必须给出分组理由，并贴合所选技术栈的惯例； 3. **Patterns 要诚实**：代码示例放在有帮助的地方，trade-offs 如实呈现，并指出对小型项目何时属于过度设计； 4. **Scaling 要现实**：聚焦"什么先坏"，绝大多数项目不需要百万级架构，避免过早优化； 5. **Anti-Patterns 要落地**：必须是领域特有的、必须给替代方案、必须能预防实现阶段常见错误。 ## 从模板到产物的调用链：SDK 源码佐证 理解模板"怎么用"最直接的方式是看 SDK 中真实调用它的代码路径，位于 [sdk/src/init-runner.ts](https://link.gitcode.com/i/3185e601f082df3bd281cb8b557348f9)。 **第一步：四路并行研究。** `runParallelResearch`（[init-runner.ts](https://link.gitcode.com/i/3185e601f082df3bd281cb8b557348f9#L330-L356)）对 `RESEARCH_TYPES`（STACK/FEATURES/ARCHITECTURE/PITFALLS）并发发起 4 个研究会话，每个会话调用 `buildResearchPrompt` 读取对应模板： ```typescript const agentDef = await this.readAgentFile('gsd-project-researcher.md'); const template = await this.readGSDFile(`templates/research-project/${researchType}.md`);

即本模板路径templates/research-project/ARCHITECTURE.md会被原样装载进 prompt，并附加指令："Write your findings to .planning/research/ARCHITECTURE.md"（init-runner.ts）。

第二步：结果落盘与提交。成功的会话产出.planning/research/ARCHITECTURE.md工件；任一路失败则整体标记 research 失败（init-runner.ts）。

第三步：总结（synthesis）。研究全部完成后，runSummarySynthesis（init-runner.ts）读取全部四份研究文件（含ARCHITECTURE.md），把它们作为<research_architecture>...</research_architecture>上下文，调用 SUMMARY.md 模板合成总览——其中明确要求"Summary from ARCHITECTURE.md — 1 paragraph + Major components 列表"。

第四步：roadmap 消费。生成的SUMMARY.md连同 PROJECT.md、REQUIREMENTS.md 一起作为 roadmap 生成的上下文（init-runner.ts），架构建议由此转化为阶段结构。

值得注意的是，ARCHITECTURE.md这个名字在 GSD 中还有一处独立用法：profile-output.ts 会把.planning/codebase/ARCHITECTURE.md（代码库结构分析产物）作为架构上下文输出，缺失时回退到内置的CLAUDE_MD_FALLBACKS.architecture。这印证了"架构信息 = 关键上下文"的设计理念：无论是研究阶段的领域架构，还是执行阶段的代码库架构，都会进入 AI 的上下文窗口。

研究员的执行纪律：验证协议与置信度

模板本身不含"怎么做研究"的说明，这部分由 gsd-project-researcher.md 补充，其核心纪律与模板配套使用：

• 训练数据即假设：Agent 的训练数据滞后 6~18 个月，任何能力断言必须先经 Context7 或官方文档验证（gsd-project-researcher.md）；
• 诚实报告："我没找到 X"、"LOW confidence"、"来源互相矛盾"都是有价值的输出，禁止把未经验证的结论写成事实；
• 证据优先级：Context7 → Exa（已验证）→ Firecrawl（官方文档）→ 官方仓库 → Brave/WebSearch（已验证）→ WebSearch（未验证）（gsd-project-researcher.md）；
• 三档置信度：HIGH=官方来源可陈述为事实；MEDIUM=多个可信来源一致需注明出处；LOW=单一来源或推断需标记待验证（gsd-project-researcher.md）。

对应到 ARCHITECTURE.md 模板头部，就是**Confidence:** [HIGH/MEDIUM/LOW]字段——每个架构结论都应有置信度背书，这是 GSD 语境工程与"防 sycophancy（谄媚输出）"设计的一部分。

使用建议与填写检查清单

结合模板结构与源码调用链，填写一份高质量的.planning/research/ARCHITECTURE.md建议按以下顺序自查：

• 头部元信息完整：Domain / Researched / Confidence 三字段均已填写；
• System Overview 图与 Component Responsibilities 表一一对应，无图上有表无；
• 每个模式卡片含 What / When to use / Trade-offs / Example 四要素，且注明小型项目是否适用；
• Request Flow 与 State Management 区分清晰，关键数据流 2~4 条且编号；
• Scaling 表三档规模均有调整方案，且第一瓶颈有明确判断（非理论极限）；
• 每个 Anti-Pattern 都给出"Do this instead"替代方案；
• Integration Points 覆盖所有外部服务与关键内部边界；
• Sources 中每条关键结论都能溯源，LOW 置信度已显式标记；
• 全文结论与 STACK.md（技术选型）、FEATURES.md（功能需求）、PITFALLS.md（风险）无相互矛盾。

结语

sdk/prompts/templates/research-project/ARCHITECTURE.md表面上看只是一份填空模板，实质上它是 GSD "先研究、后规划"方法论在架构维度的固化：用统一的九段式结构约束 AI 研究员的输出质量，用置信度与 Sources 保证结论可追溯，并通过 init-runner 的四路并行 + synthesis 机制把它无缝嵌入 roadmap 生成管线。无论你是 GSD 的使用者，还是想为自己团队的 AI 工作流设计"研究产物规范"，这套模板的区块划分、写作准则与调用链设计都值得直接借鉴——它把"架构设计"这件最容易被 AI 泛泛而谈的事，变成了可填写、可验证、可被下游自动消费的工程工件。

本文基于 ARCHITECTURE.md 模板全文、同目录下的 SUMMARY.md、FEATURES.md、STACK.md、PITFALLS.md 四份配套模板，以及 init-runner.ts、profile-output.ts 与 gsd-project-researcher.md 中的实际实现撰写，内容以当前仓库为准。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done