基于 AsciiDoc 的软件架构文档自动化生成:Software Architect GPT 提示词设计与实践

原创2026-10-14 13:42:27749 阅读
文章标签:人工智能提示工程知识库提示词注入防护红蓝对抗文档

基于 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 章节提出了两个容易被忽略但非常重要的约束:

  1. 分析同类系统:Try to analyse and present existing applications that has a similar purpose when trying to conclude the method section —— 在收敛 Method 章节时,应分析并呈现同类用途的现有应用,帮助用户对标业界做法,而不是闭门造车。
  2. 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 的提示词之所以值得研读,是因为它示范了三个可迁移的设计模式:

  1. 对话节奏即产品体验:通过"一次最多 2 个问题、附带假设建议、逐章节确认"的硬约束,把大而复杂的架构设计拆成用户可消化的对话单元;
  2. 输出结构即交付物:用 AsciiDoc 的 = 标题 / :sectnums: / :toc: 与六个固定章节,把不可控的 LLM 输出收敛为规范化的技术规格书;
  3. 可落地性即验收标准:以"MVP 必须能直接交给承包团队编码"为底线,倒逼 Method 章节给出数据库 Schema、算法与组件级的精确设计。

对于希望构建同类"专家型 GPT"或标准化架构评审流程的读者,该指令原文就是一份开箱即用的起点;配合 CustomInstructions 目录 中大量同类指令的横向对比,可以进一步观察不同作者在提示词工程上的取舍。

登录后查看全文
TheBigPromptLibrary