PentestGPT 中的架构决策记录ADR格式规范、编号规则与触发时机全解【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT本文以 PentestGPT 仓库的 ADR 格式规范 为主体完整讲解该仓库对架构决策记录Architecture Decision Record的存放约定、模板结构、编号规则以及什么时候才值得写一条 ADR的三条判定标准。结合仓库配套的 domain-modeling 技能 与 CONTEXT.md 领域词表读者读完后能够按规范在本仓库或同类项目中落一条合格的 ADR理解 ADR 与领域词表ubiquitous language的分工并看懂 docs/architecture.md 这类决策文档是如何把格式规范转化为实际工程收益的。1. ADR 的存放位置与编号约定ADR-FORMAT.md 开篇给出两条硬性约定存放目录所有 ADR 统一放在docs/adr/下文件名格式使用顺序编号加 slug 命名例如0001-slug.md、0002-slug.md编号四位数补零懒创建目录docs/adr/目录不预先创建——Create thedocs/adr/directory lazily — only when the first ADR is needed即只有当第一条 ADR 真正出现时才建目录。当前 PentestGPT 仓库中docs/下只有 architecture.md、docker-dev-plan.md 与redesign/目录尚无docs/adr/子目录——这正是懒创建约定的直接体现在第一条 ADR 触发条件满足之前不空占目录。编号规则同样明确扫描docs/adr/中已存在的最大编号加一。这意味着编号是全局递增的历史序列不会跳号、不会复用被废弃或被取代的 ADR 保留原文通过状态标记见第 4 节表达演化关系。2. ADR 模板一个段落就够格式规范给出的完整模板只有五行# {Short title of the decision} {1-3 sentences: whats the context, what did we decide, and why.}即标题 13 句话把背景是什么、决定了什么、为什么讲清楚。规范对此有一句核心论断An ADR can be a single paragraph. The value is in recordingthata decision was made andwhy— not in filling out sections.这句话把 ADR 与设计文档彻底区分开ADR 的价值在于留下做过这个决定以及为什么这么选的证据而不在于填满章节骨架。这与 PentestGPT 仓库的实际风格一致——docs/architecture.md 记录诸如The Supervisor chooses one task or proposes completion、There is no always-on judge, RAG service, speculative backlog, or parallel scheduler这类决策时用的正是短小、陈述式、不展开论证的笔法。3. 三个可选章节只在真正增值时才写规范列出三个可选章节并强调大多数 ADR 都不需要它们Only include these when they add genuine value. Most ADRs wont need them.可选章节何时才写作用Statusfrontmatter决策会被再次审视时取值为proposed \| accepted \| deprecated \| superseded by ADR-NNNN其中superseded by ADR-NNNN直接指向取代它的编号形成决策演化链Considered Options被否掉的替代方案值得被记住时防止半年后有人重新提出同样的已被否决的方案Consequences存在不明显的下游影响需要点名时提醒后来者这个决定会波及哪些地方注意superseded by ADR-NNNN与顺序编号制度的配合编号本身承担版本角色决策被推翻时不改写旧文件而是新增一条更高编号的 ADR并在旧文件的 Status 中标注指向。4. 何时该写 ADR三条判定标准AND 关系格式规范中最重要的部分是何时主动提出写 ADRWhen to offer an ADR。以下三条必须同时成立Hard to reverse难以逆转——事后反悔的代价是真实存在的Surprising without context缺少上下文时会令人困惑——未来的读者看到代码会问他们为什么要这样做The result of a real trade-off源于真实的取舍——确实存在多个真实候选方案而你是出于具体理由选了其中一个。规范还给出了对应的跳过逻辑同样值得逐条记住如果决策容易逆转就跳过——反正你迟早会反转它如果决策不令人意外就跳过——没人会追问为什么如果没有真实备选方案就跳过——除了我们做了显而易见的事之外无话可记。这三条标准在 domain-modeling 技能 中被原样复述为 Offer ADRs sparingly——技能要求 Agent 在会话过程中克制地提出 ADR任何一条缺失就不写。这防止了 ADR 目录被低价值条目淹没。5. 什么算合格的决策七类典型场景规范用 What qualifies 一节列举了七类应当记录的决策这一节基本可以当作 ADR 的选题清单Architectural shape架构形态——例如我们使用 monorepo、写模型是事件溯源的读模型投影进 PostgresIntegration patterns between contexts上下文间的集成模式——例如Ordering 与 Billing 通过领域事件通信而非同步 HTTPTechnology choices that carry lock-in带锁定性的技术选型——数据库、消息总线、认证提供方、部署目标。不是每个库都算只有那些换掉要花费一个季度的才值得记Boundary and scope decisions边界与范围决策——例如客户数据由 Customer 上下文拥有其他上下文只能通过 ID 引用。规范特别强调显式的不做什么和做什么同样有价值Deliberate deviations from the obvious path对显而易见路径的刻意偏离——例如因为 X我们用手写 SQL 而非 ORM。任何合理读者会默认相反的选择都应记录其作用是阻止下一位工程师去修复那些本来就是故意的东西Constraints not visible in the code代码中不可见的约束——例如合规要求不能用 AWS、合作伙伴 API 合同要求响应时间低于 200msRejected alternatives when the rejection is non-obvious当否决不显而易见时记录被否决的备选方案——例如你考虑过 GraphQL 却出于微妙原因选了 REST必须记下来否则六个月后一定会有人再提 GraphQL。6. 在 PentestGPT 中如何落地这套规范6.1 ADR 与 CONTEXT.md 的分工domain-modeling 技能 把整个仓库的领域建模文档组织为两套文件ADR 只是其中一半单上下文仓库多数情况根目录一个CONTEXT.md领域词表/术语表docs/adr/决策记录多上下文仓库根目录CONTEXT-MAP.md指向各上下文的CONTEXT.mddocs/adr/存放系统级决策各上下文目录内另有自己的docs/adr/存放上下文级决策。技能的定位说明也很关键domain-modeling 是一项主动纪律——挑战术语、发明边界场景、在术语定型的那一刻立刻写入词表而仅仅阅读CONTEXT.md借词不属于这个技能。ADR 与词表的边界同样清晰技能的规则要求CONTEXT.md完全不含实现细节It is a glossary and nothing else——它只回答这个词是什么而为什么这么设计一律归 ADR / 架构文档管。PentestGPT 恰好提供了一个多文件领域文档的真实样本pentestgpt_agent/CONTEXT.md 就是按 CONTEXT-FORMAT.md 的格式写成的——## Language段给出加粗术语Supervisor、Executor、Memory Kernel、Evidence、Transition……## Invariants段列出不变量。这些不变量如Every episode is fresh、Deterministic code owns scope, leases, evidence……正是决策的结果而其背后的选型理由属于 ADR 的管辖范围。6.2 用三条标准检验 PentestGPT 的既有决策docs/architecture.md 虽然是架构文档而非docs/adr/条目但它记录的若干决策恰好满足第 4 节的全部三条标准可作为ADR 化的示范样本两个 LLM 角色的循环且刻意不加第三角色——There is no always-on judge, RAG service, speculative backlog, or parallel scheduler。这同时命中第 5 类的刻意偏离社区里 LLM Agent 框架常见 Judge/反思角色与第 4 类的显式不做什么且难以逆转循环结构牵动 Supervisor/Executor/Trace 全部接口。CLAUDE.md 甚至把这条升级为编辑规则Keep the core at two LLM roles. Do not add an always-on judge, RAG layer, or scheduler without trace evidence that the current deterministic seam cannot solve the problem.FULL_ACCESS沙箱策略以部署环境为隔离边界——CONTEXT.md 的 Invariants 写明 Both roles receive full provider tool and filesystem/process access. The deployment environment is the isolation boundary。这是一个典型的合理读者会默认相反的决策安全测试框架默认会被期待内置沙箱而 PentestGPT 明确选择了不在进程内维护第二层工具或文件系统沙箱见 docs/architecture.md 的 The deployment environment is the isolation boundary; PentestGPT does not maintain a second tool or filesystem sandbox。unified-agent依赖固定到外部包的某个 commit——docs/architecture.md 解释这是真实接缝provider 选择、结构化输出、事件归一化移除它会让 provider SDK 的变动重复进pentestgpt_agent.trace与pentestgpt_agent.trialtests/test_dependency.py 验证嵌套项目导入的是已安装的外部依赖而非仓库根目录的漂移副本。这是第 3 类带锁定性的技术选型。SQLite 是唯一权威记忆provider 会话转录只是诊断 trace——SQLite is canonical memory. Provider transcripts are diagnostic traces, not memory并且 CONTEXT.md 的 Invariants 进一步约束diagnostics 不能成为证据或完成依据。这是第 6 类代码中不可见的约束读者必须知道为什么 trace 文件再全也不算记忆否则很容易写出把 provider 历史当状态用的代码。6.3 实操清单在本仓库写第一条 ADR按格式规范的流程操作判断候选决策是否同时满足三条标准难以逆转 无上下文会困惑 真实取舍缺一条就放弃扫描docs/adr/找最大编号加一创建docs/adr/NNNN-slug.md目录不存在则此时创建正文按模板写一个标题 13 句话背景、决定、理由仅在被否决方案值得记忆、下游影响不直观、或决策会被复审时才追加 Considered Options / Consequences / Status 章节若该决策同时引入新术语另行更新CONTEXT.md只定义是什么不写实现理由两个文件各司其职。7. 小结ADR 的最小主义纪律PentestGPT 的 ADR 格式规范 的核心主张可以压缩成一句话ADR 是决定发生过、以及为什么的最短可检索记录——模板最短到一句话编号保证历史可追溯三条 AND 标准保证目录里每一条都值得存在。配合 domain-modeling 技能 的克制地提出 ADR与 CONTEXT-FORMAT.md 的纯词表定位这套文档纪律把架构决策记录从一次性写作任务变成了随设计过程自然沉淀的仓库资产决策与术语各归其位后来者既能从 docs/architecture.md 这样的决策文档中直接受益也能按同一格式为下一个难以逆转、真实取舍的决定留下一条编号明确的记录。【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PentestGPT 中的架构决策记录（ADR）：格式规范、编号规则与触发时机全解
PentestGPT 中的架构决策记录ADR格式规范、编号规则与触发时机全解【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT本文以 PentestGPT 仓库的 ADR 格式规范 为主体完整讲解该仓库对架构决策记录Architecture Decision Record的存放约定、模板结构、编号规则以及什么时候才值得写一条 ADR的三条判定标准。结合仓库配套的 domain-modeling 技能 与 CONTEXT.md 领域词表读者读完后能够按规范在本仓库或同类项目中落一条合格的 ADR理解 ADR 与领域词表ubiquitous language的分工并看懂 docs/architecture.md 这类决策文档是如何把格式规范转化为实际工程收益的。1. ADR 的存放位置与编号约定ADR-FORMAT.md 开篇给出两条硬性约定存放目录所有 ADR 统一放在docs/adr/下文件名格式使用顺序编号加 slug 命名例如0001-slug.md、0002-slug.md编号四位数补零懒创建目录docs/adr/目录不预先创建——Create thedocs/adr/directory lazily — only when the first ADR is needed即只有当第一条 ADR 真正出现时才建目录。当前 PentestGPT 仓库中docs/下只有 architecture.md、docker-dev-plan.md 与redesign/目录尚无docs/adr/子目录——这正是懒创建约定的直接体现在第一条 ADR 触发条件满足之前不空占目录。编号规则同样明确扫描docs/adr/中已存在的最大编号加一。这意味着编号是全局递增的历史序列不会跳号、不会复用被废弃或被取代的 ADR 保留原文通过状态标记见第 4 节表达演化关系。2. ADR 模板一个段落就够格式规范给出的完整模板只有五行# {Short title of the decision} {1-3 sentences: whats the context, what did we decide, and why.}即标题 13 句话把背景是什么、决定了什么、为什么讲清楚。规范对此有一句核心论断An ADR can be a single paragraph. The value is in recordingthata decision was made andwhy— not in filling out sections.这句话把 ADR 与设计文档彻底区分开ADR 的价值在于留下做过这个决定以及为什么这么选的证据而不在于填满章节骨架。这与 PentestGPT 仓库的实际风格一致——docs/architecture.md 记录诸如The Supervisor chooses one task or proposes completion、There is no always-on judge, RAG service, speculative backlog, or parallel scheduler这类决策时用的正是短小、陈述式、不展开论证的笔法。3. 三个可选章节只在真正增值时才写规范列出三个可选章节并强调大多数 ADR 都不需要它们Only include these when they add genuine value. Most ADRs wont need them.可选章节何时才写作用Statusfrontmatter决策会被再次审视时取值为proposed \| accepted \| deprecated \| superseded by ADR-NNNN其中superseded by ADR-NNNN直接指向取代它的编号形成决策演化链Considered Options被否掉的替代方案值得被记住时防止半年后有人重新提出同样的已被否决的方案Consequences存在不明显的下游影响需要点名时提醒后来者这个决定会波及哪些地方注意superseded by ADR-NNNN与顺序编号制度的配合编号本身承担版本角色决策被推翻时不改写旧文件而是新增一条更高编号的 ADR并在旧文件的 Status 中标注指向。4. 何时该写 ADR三条判定标准AND 关系格式规范中最重要的部分是何时主动提出写 ADRWhen to offer an ADR。以下三条必须同时成立Hard to reverse难以逆转——事后反悔的代价是真实存在的Surprising without context缺少上下文时会令人困惑——未来的读者看到代码会问他们为什么要这样做The result of a real trade-off源于真实的取舍——确实存在多个真实候选方案而你是出于具体理由选了其中一个。规范还给出了对应的跳过逻辑同样值得逐条记住如果决策容易逆转就跳过——反正你迟早会反转它如果决策不令人意外就跳过——没人会追问为什么如果没有真实备选方案就跳过——除了我们做了显而易见的事之外无话可记。这三条标准在 domain-modeling 技能 中被原样复述为 Offer ADRs sparingly——技能要求 Agent 在会话过程中克制地提出 ADR任何一条缺失就不写。这防止了 ADR 目录被低价值条目淹没。5. 什么算合格的决策七类典型场景规范用 What qualifies 一节列举了七类应当记录的决策这一节基本可以当作 ADR 的选题清单Architectural shape架构形态——例如我们使用 monorepo、写模型是事件溯源的读模型投影进 PostgresIntegration patterns between contexts上下文间的集成模式——例如Ordering 与 Billing 通过领域事件通信而非同步 HTTPTechnology choices that carry lock-in带锁定性的技术选型——数据库、消息总线、认证提供方、部署目标。不是每个库都算只有那些换掉要花费一个季度的才值得记Boundary and scope decisions边界与范围决策——例如客户数据由 Customer 上下文拥有其他上下文只能通过 ID 引用。规范特别强调显式的不做什么和做什么同样有价值Deliberate deviations from the obvious path对显而易见路径的刻意偏离——例如因为 X我们用手写 SQL 而非 ORM。任何合理读者会默认相反的选择都应记录其作用是阻止下一位工程师去修复那些本来就是故意的东西Constraints not visible in the code代码中不可见的约束——例如合规要求不能用 AWS、合作伙伴 API 合同要求响应时间低于 200msRejected alternatives when the rejection is non-obvious当否决不显而易见时记录被否决的备选方案——例如你考虑过 GraphQL 却出于微妙原因选了 REST必须记下来否则六个月后一定会有人再提 GraphQL。6. 在 PentestGPT 中如何落地这套规范6.1 ADR 与 CONTEXT.md 的分工domain-modeling 技能 把整个仓库的领域建模文档组织为两套文件ADR 只是其中一半单上下文仓库多数情况根目录一个CONTEXT.md领域词表/术语表docs/adr/决策记录多上下文仓库根目录CONTEXT-MAP.md指向各上下文的CONTEXT.mddocs/adr/存放系统级决策各上下文目录内另有自己的docs/adr/存放上下文级决策。技能的定位说明也很关键domain-modeling 是一项主动纪律——挑战术语、发明边界场景、在术语定型的那一刻立刻写入词表而仅仅阅读CONTEXT.md借词不属于这个技能。ADR 与词表的边界同样清晰技能的规则要求CONTEXT.md完全不含实现细节It is a glossary and nothing else——它只回答这个词是什么而为什么这么设计一律归 ADR / 架构文档管。PentestGPT 恰好提供了一个多文件领域文档的真实样本pentestgpt_agent/CONTEXT.md 就是按 CONTEXT-FORMAT.md 的格式写成的——## Language段给出加粗术语Supervisor、Executor、Memory Kernel、Evidence、Transition……## Invariants段列出不变量。这些不变量如Every episode is fresh、Deterministic code owns scope, leases, evidence……正是决策的结果而其背后的选型理由属于 ADR 的管辖范围。6.2 用三条标准检验 PentestGPT 的既有决策docs/architecture.md 虽然是架构文档而非docs/adr/条目但它记录的若干决策恰好满足第 4 节的全部三条标准可作为ADR 化的示范样本两个 LLM 角色的循环且刻意不加第三角色——There is no always-on judge, RAG service, speculative backlog, or parallel scheduler。这同时命中第 5 类的刻意偏离社区里 LLM Agent 框架常见 Judge/反思角色与第 4 类的显式不做什么且难以逆转循环结构牵动 Supervisor/Executor/Trace 全部接口。CLAUDE.md 甚至把这条升级为编辑规则Keep the core at two LLM roles. Do not add an always-on judge, RAG layer, or scheduler without trace evidence that the current deterministic seam cannot solve the problem.FULL_ACCESS沙箱策略以部署环境为隔离边界——CONTEXT.md 的 Invariants 写明 Both roles receive full provider tool and filesystem/process access. The deployment environment is the isolation boundary。这是一个典型的合理读者会默认相反的决策安全测试框架默认会被期待内置沙箱而 PentestGPT 明确选择了不在进程内维护第二层工具或文件系统沙箱见 docs/architecture.md 的 The deployment environment is the isolation boundary; PentestGPT does not maintain a second tool or filesystem sandbox。unified-agent依赖固定到外部包的某个 commit——docs/architecture.md 解释这是真实接缝provider 选择、结构化输出、事件归一化移除它会让 provider SDK 的变动重复进pentestgpt_agent.trace与pentestgpt_agent.trialtests/test_dependency.py 验证嵌套项目导入的是已安装的外部依赖而非仓库根目录的漂移副本。这是第 3 类带锁定性的技术选型。SQLite 是唯一权威记忆provider 会话转录只是诊断 trace——SQLite is canonical memory. Provider transcripts are diagnostic traces, not memory并且 CONTEXT.md 的 Invariants 进一步约束diagnostics 不能成为证据或完成依据。这是第 6 类代码中不可见的约束读者必须知道为什么 trace 文件再全也不算记忆否则很容易写出把 provider 历史当状态用的代码。6.3 实操清单在本仓库写第一条 ADR按格式规范的流程操作判断候选决策是否同时满足三条标准难以逆转 无上下文会困惑 真实取舍缺一条就放弃扫描docs/adr/找最大编号加一创建docs/adr/NNNN-slug.md目录不存在则此时创建正文按模板写一个标题 13 句话背景、决定、理由仅在被否决方案值得记忆、下游影响不直观、或决策会被复审时才追加 Considered Options / Consequences / Status 章节若该决策同时引入新术语另行更新CONTEXT.md只定义是什么不写实现理由两个文件各司其职。7. 小结ADR 的最小主义纪律PentestGPT 的 ADR 格式规范 的核心主张可以压缩成一句话ADR 是决定发生过、以及为什么的最短可检索记录——模板最短到一句话编号保证历史可追溯三条 AND 标准保证目录里每一条都值得存在。配合 domain-modeling 技能 的克制地提出 ADR与 CONTEXT-FORMAT.md 的纯词表定位这套文档纪律把架构决策记录从一次性写作任务变成了随设计过程自然沉淀的仓库资产决策与术语各归其位后来者既能从 docs/architecture.md 这样的决策文档中直接受益也能按同一格式为下一个难以逆转、真实取舍的决定留下一条编号明确的记录。【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考