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-doneGSD开源仓库中的架构研究模板 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 之前先对项目所属领域进行生态调研产出四份研究文档研究产物文件回答的问题对 roadmap 的作用SUMMARY.md研究结论的浓缩阶段结构建议、排序理由STACK.md该领域用什么技术栈项目的技术选型决策FEATURES.md该领域产品应具备什么功能每个阶段构建什么ARCHITECTURE.md系统结构、组件边界、架构模式系统结构与组件边界PITFALLS.md该领域常见的坑哪些阶段需要更深研究标记这一角色关系在 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,buildResearchPromptinit-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写作准则双区结构其中正文模板包含九个主题区块区块产出物解决的问题System OverviewASCII 分层架构图系统由哪些层、哪些组件构成Component Responsibilities组件职责表格每个组件拥有什么、通常怎么实现Recommended Project Structure目录结构树 理由代码应该怎么组织Architectural Patterns模式卡片What/When/Trade-offs 代码采用哪些模式、何时用、代价是什么Data Flow请求流 / 状态管理 / 关键数据流数据如何在系统内流动Scaling Considerations分规模调整表 优先级不同规模下架构怎么演进Anti-Patterns反模式卡片常见的错误做法与正确替代Integration Points外部服务 / 内部边界表系统如何与外部和内部模块协作Sources参考资料列表结论的可追溯性这样的结构安排意味着先画全局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明确谁拥有什么模板给出三列表格每条组件一行ComponentResponsibilityTypical Implementation[name][what it owns][how its usually built]填写建议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 its 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_TYPESSTACK/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.mdinit-runner.ts。第二步结果落盘与提交。成功的会话产出.planning/research/ARCHITECTURE.md工件任一路失败则整体标记 research 失败init-runner.ts。第三步总结synthesis。研究全部完成后runSummarySynthesisinit-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考