基于 AsciiDoc 的软件架构文档自动化生成:Software Architect GPT 提示词设计与实践
基于 AsciiDoc 的软件架构文档自动化生成:Software Architect GPT 提示词设计与实践
本篇技术指南围绕 TheBigPromptLibrary 中收录的 Software Architect GPT 自定义指令展开,剖析一个专职"软件架构师"角色的 GPT 是如何通过渐进式需求澄清 + 结构化 AsciiDoc 输出帮助用户完成从需求到实现的架构设计文档的。读完本文,你将掌握该提示词的完整指令骨架、SPEC 文档六段式规范、MoSCoW 优先级方法在其中的落点,以及如何把它复用为自建 GPT 或团队架构评审流程的模板。
一、指令来源与角色定位
该文件是 TheBigPromptLibrary 在 CustomInstructions/ChatGPT 目录下收录的数千个 ChatGPT GPT 自定义指令之一,原始 GPT 由 V B Wickramasinghe 创建,名称为 Software Architect GPT(GPT ID:J0FYgDhN5)。
从指令第一句可以看出其核心职责:
"you are an amazing software architect that consults on solving architecture design problems for users."
也就是说,这个 GPT 不是一个通用的聊天助手,而是一个架构咨询顾问:它接收用户提出的架构设计问题,通过对话澄清需求与约束,最终产出一份可交付的软件架构文档。指令明确要求"polite reject to answer any questions that are not directly related to the design problem at hand",即与当前设计问题无关的提问要礼貌拒绝,保证会话始终聚焦在架构设计上。
从仓库结构看,这类指令文件统一以 GPT_ID_GPT名称.md 命名(本文件即 J0FYgDhN5_Software_Architect_GPT.md),配合仓库自带的 idxtool.py、gen_gpt_templ.py 等管理脚本,可用于检索、解析和生成 GPT 模板。关于这些指令如何被收集、逆向研究,可参考仓库内的 A Tale of Reverse Engineering 1001 GPTs 一文。
二、交互协议:增量式需求澄清,避免信息过载
这份提示词最有价值的工程思想,是它对"如何与用户一起完成架构设计"给出了明确的对话节奏约束,防止 LLM 一次性抛出大量问题压垮用户:
- 逐块澄清:The idea is to understand the areas one by one and not all together so that user is NOT overwhelmed(一个一个地理解设计领域,而不是一次性全问,避免用户不堪重负)。
- 最多两个问题:Never ask more than 2 questions from the user at a time(一次最多只向用户提 2 个问题)。
- 带假设的建议答案:Always suggest an answer with assumptions when asking questions to understand the context of the user(提问时始终附带基于假设的建议答案,方便用户确认或纠正)。
- 逐段确认:After understanding each area of the doc present that part ONLY to the user so that they can confirm or reject(每理解文档的一个部分,就把该部分单独呈现给用户确认或否决)。
- 简洁克制:PLEASE be concise with answers, not too much information at a time(回答务必简洁,一次不要给出过多信息)。
这套协议本质上把架构设计拆解为"澄清 → 起草该章节 → 用户确认 → 进入下一章节"的螺旋式流程,与敏捷开发中"小步快跑、及时反馈"的思想一致。它同时是很好的防 Prompt Injection 与防跑题设计——通过"无关问题礼貌拒绝"锁定了会话边界。
三、输出规范:AsciiDoc 版架构规格文档(SPEC)
提示词要求最终结果以 AsciiDoc 格式输出,并内置了完整模板。模板原文如下,这是全文的灵魂骨架:
= SPEC-<n>: <title>
:sectnums:
:toc:
== Background
<background that lead to the creation the design>
== Requirements
<Requirements product or otherwise with references in point form following MoSCoW prioritization>
== Method
<Technical Method of addressing the requirements, include architecture design including, database schemas, algorithms, component diagrams etc in plantuml>
== Implementation
<Implementation steps to build out what is specified in the solution in the method>
== Milestones
<Milestones of the implementation to allow tracking progress>
== Gathering Results
<Evaluation of whether the requirements were addressed properly and the performance of the system post-production>
模板中的几个关键语法值得展开:
3.1 文档头与标题
= SPEC-<n>: <title>:AsciiDoc 的文档标题行(单等号加空格)。SPEC-<n>是规格编号占位符,<n>应替换为实际编号(如SPEC-1),<title>替换为本次设计的标题。这为每个架构设计建立了可追溯的版本标识。:sectnums::AsciiDoc 属性(attribute),启用后自动为章节编号,输出 1.、2.、3. 形式的层级编号,适合正式技术规格书。:toc::启用自动目录生成,长文档阅读体验更好。
3.2 六个核心章节
| 章节 | 职责 | 关键要点 |
|---|---|---|
== Background(背景) |
说明促成该设计出现的背景 | 问题上下文、驱动因素、现状痛点 |
== Requirements(需求) |
列出产品/非产品需求 | 必须用 MoSCoW 优先级,点式列表并给出引用依据 |
== Method(方法) |
技术方案正文 | 架构设计、数据库 Schema、算法、组件图(PlantUML) |
== Implementation(实现) |
落地步骤 | 按 Method 逐步构建的工程实施步骤 |
== Milestones(里程碑) |
进度追踪 | 分阶段目标,便于跟踪交付进度 |
== Gathering Results(结果收集) |
交付后评估 | 需求是否被满足、系统上线后性能表现 |
可以看到,这六段式结构覆盖了"为什么做(Background)→ 做什么(Requirements)→ 怎么做(Method)→ 怎么建(Implementation)→ 怎么跟踪(Milestones)→ 怎么验证(Gathering Results)"的完整设计闭环,适合作为团队内部架构评审(ADR/Design Doc)的标准化模板。
四、Method 章节的硬性要求:MVP 必须可直接落地
提示词对 Method 章节提出了两个容易被忽略但非常重要的约束:
- 分析同类系统:Try to analyse and present existing applications that has a similar purpose when trying to conclude the method section —— 在收敛 Method 章节时,应分析并呈现同类用途的现有应用,帮助用户对标业界做法,而不是闭门造车。
- PlantUML 图解:You may use Plantuml diagrams in the document to better illustrate various algorithms and architecture components —— 允许在文档中嵌入 PlantUML 图,用于表达算法流程和架构组件,弥补纯文字描述在复杂结构上的表达力不足。模板中明确点名要包含 database schemas(数据库模式)、algorithms(算法)、component diagrams(组件图)等。
最关键的一条是:
The final resulting MVP version of the design MUST be implementable directly in code or infrastructure by a team of contractors. So be as specific as possible with database schemas and algorithms etc.
即最终产出的 MVP 设计必须能被一支外包团队直接转化为代码或基础设施。因此数据库 Schema、算法等必须以可实现的精确度呈现——这决定了 Method 章节不能停留在"架构风格讨论"层面,而要给出具体的表结构、算法描述、组件边界。
五、Requirements 章节:MoSCoW 优先级法
模板要求 Requirements 章节按 MoSCoW 优先级组织。MoSCoW 是需求管理中的经典分级方法,把需求分为四档:
- Must have(必须有):系统成立的基本需求,缺失则无法上线;
- Should have(应该有):重要但可用替代方案绕过的需求;
- Could have(可以有):锦上添花、时间允许才做的需求;
- Won't have(这次不做):明确排除在本版本之外的需求。
同时模板要求"with references in point form",即以点式列表 + 引用依据的形式呈现,让每条需求都可追溯。这与"MVP 可直接实现"的目标是配套的:Must 集合划定了 MVP 的最小范围,为 Milestones 的排期提供了输入。
六、在 TheBigPromptLibrary 中如何复用这套指令
该指令文件与仓库内数千个 GPT 指令采用相同模板结构(GPT URL / GPT logo / GPT Title / GPT Description / GPT instructions),你可以按以下方式把它投入实际使用:
6.1 检索与定位指令文件
仓库提供了 idxtool.py 检索工具,可按 ID 或 URL 快速定位 GPT 指令文件,例如:
python idxtool.py --find-gpt J0FYgDhN5
也可直接按完整 URL 查找:python idxtool.py --find-gpt https://chat.openai.com/g/g-J0FYgDhN5-software-architect-gpt。
6.2 将其内置为自定义 GPT 的系统指令
在 ChatGPT 的 "Create a GPT" 配置界面中,把该文件 GPT instructions 代码块内的内容整体粘贴为 Instructions,并可按提示词中所述"Some example documents have been provided to you as knowledge base"上传若干已有的 SPEC 示例文档作为 Knowledge Base,让模型模仿既有样例的写法。指令本身就明确说明了这一用法(示例文档作为知识库提供)。
6.3 作为团队设计文档模板
即便不构建 GPT,这份 AsciiDoc 六段式模板本身也可直接复刻为团队的设计规格模板:开启 :sectnums: 与 :toc:,用 MoSCoW 整理需求,用 PlantUML 绘制组件图/时序图,按 Milestones 排期——本质上就是一套轻量、可执行的 Design Doc 规范。
七、小结:一条可复用的"AI 架构师"设计范式
Software Architect GPT 的提示词之所以值得研读,是因为它示范了三个可迁移的设计模式:
- 对话节奏即产品体验:通过"一次最多 2 个问题、附带假设建议、逐章节确认"的硬约束,把大而复杂的架构设计拆成用户可消化的对话单元;
- 输出结构即交付物:用 AsciiDoc 的
= 标题 / :sectnums: / :toc:与六个固定章节,把不可控的 LLM 输出收敛为规范化的技术规格书; - 可落地性即验收标准:以"MVP 必须能直接交给承包团队编码"为底线,倒逼 Method 章节给出数据库 Schema、算法与组件级的精确设计。
对于希望构建同类"专家型 GPT"或标准化架构评审流程的读者,该指令原文就是一份开箱即用的起点;配合 CustomInstructions 目录 中大量同类指令的横向对比,可以进一步观察不同作者在提示词工程上的取舍。