用 domain-modeling 技能在 PentestGPT 中落地领域建模统一语言、CONTEXT 与 ADR 的实践指南【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT导读本文围绕 PentestGPT 仓库中的domain-modeling智能体技能.agents/skills/domain-modeling/SKILL.md展开讲解它如何帮助 AI 编码 Agent 在项目演进过程中主动建立并持续打磨领域模型——包括锁定领域术语与统一语言Ubiquitous Language、记录架构决策ADR以及如何与源码、测试相互印证。读完本文你将掌握该技能的文件结构约定、会话中的五项关键行为、CONTEXT.md与 ADR 的书写格式并能结合仓库中真实的 pentestgpt_agent/CONTEXT.md 实例与 unified_agent/skills.py 的实现理解技能机制在工程层面的落地方式。一、技能定位这是改变模型的主动训练而非消费词汇的阅读习惯domain-modeling技能在 frontmatter 中这样自我声明SKILL.md--- name: domain-modeling description: Build and sharpen a projects domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model. ---技能正文开头即划出一条重要分界线仅仅为了查词汇而阅读CONTEXT.md不属于本技能——那只是任何技能都能做的一行习惯。本技能真正适用的场景是当模型正在改变领域模型时挑战术语、虚构边界场景、在概念结晶的当下立刻把术语表和决策写下来。从仓库实现看这类技能描述并非摆设。unified_agent/skills.py 中的Skill数据结构保存了name、description、body与frontmatter加载器强制要求 description 必填且不超过 1024 字符load_skill测试 tests/test_skills.py 也验证了空描述与超长描述会被拒绝。description 之所以被如此严格约束是因为它承担着模型自主调用的触发职责——这与 .agents/skills/writing-great-skills/SKILL.md 中模型调用型技能靠 description 触发的原则一脉相承。二、文件结构单上下文与多上下文两种布局技能规定了仓库中领域模型的标准落盘位置。大多数仓库只有一个上下文结构如下SKILL.md/ ├── CONTEXT.md ├── docs/ │ └── adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/如果仓库根目录存在CONTEXT-MAP.md则说明仓库有多个上下文此时由映射文件指出每个上下文的位置/ ├── CONTEXT-MAP.md ├── docs/ │ └── adr/ ← system-wide decisions ├── src/ │ ├── ordering/ │ │ ├── CONTEXT.md │ │ └── docs/adr/ ← context-specific decisions │ └── billing/ │ ├── CONTEXT.md │ └── docs/adr/关键原则是懒创建create files lazily只在有内容可写时才创建文件。若尚无CONTEXT.md则在第一个术语被确定时创建若尚无docs/adr/则在第一条 ADR 需要记录时才创建SKILL.md。这与writing-great-skills技能反复强调的削减、去冗余、单一事实来源精神一致——避免用空文件占据认知空间。多上下文判别规则在 CONTEXT-FORMAT.md 中有明确推断逻辑若存在CONTEXT-MAP.md读取它以找到各上下文若仅存在根目录的CONTEXT.md则是单上下文若两者都不存在则在第一个术语确定时懒创建根目录CONTEXT.md存在多上下文时先推断当前话题属于哪个上下文不明确就提问。三、会话中的五项行为把建模变成实时纪律技能用一节 During the session 给出 Agent 在对话中应持续执行的五个动作SKILL.md3.1 对照术语表质疑Challenge against the glossary当用户使用的术语与CONTEXT.md中已确立的语言冲突时立即指出。技能给出的示例话术是你的术语表把 cancellation 定义为 X但你这里似乎指的是 Y——到底是哪个 这一步的价值在于阻止统一语言的无声漂移。3.2 打磨模糊语言Sharpen fuzzy language当用户使用含糊或过载的词时提出一个精确的规范术语。示例你说 account——你指的是 Customer 还是 User这是两个不同的东西。 领域驱动设计DDD中的统一语言正是通过这种即时澄清逐步收敛的。3.3 讨论具体场景Discuss concrete scenarios在讨论领域关系时用具体场景做压力测试。虚构能触及边界情况的场景迫使用户把概念之间的边界说精确。边界不清往往是需求缺陷的温床场景化提问是暴露它的最高效手段。3.4 与代码交叉引用Cross-reference with code当用户陈述某物如何工作时Agent 应当核对代码是否与之一致。若发现矛盾立即浮出水面你的代码会取消整个 Order但你刚才说支持部分取消——哪个才是对的 这一行为把领域模型与实现绑定防止文档是一套、代码是另一套的割裂。3.5 内联更新 CONTEXT.mdUpdate CONTEXT.md inline术语一经确定当场更新CONTEXT.md不要批量积压。格式遵循 CONTEXT-FORMAT.md。同时有一条硬性约束CONTEXT.md必须完全不含实现细节。不要把它当作规格说明书、草稿纸或实现决策的仓库。它只应是术语表除此之外什么都不是。SKILL.md这条约束将领域语言与技术实现彻底分离——实现决策属于 ADR领域词汇属于 CONTEXT。四、CONTEXT.md 的书写格式与规则CONTEXT-FORMAT.md 给出了术语表的精确模板# {Context Name} {One or two sentence description of what this context is and why it exists.} ## Language **Order**: {One or two sentence description of the term} _Avoid_: Purchase, transaction **Invoice**: A request for payment sent to a customer after delivery. _Avoid_: Bill, payment request **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account配套四条书写规则要有主见Be opinionated同一概念有多个词时选最好的那个把其余词列在_Avoid_下。_Avoid_列表正是统一语言发挥作用的地方——它明确宣告别用这个词。定义要紧凑Keep definitions tight每个定义最多一两句话定义它是什么IS而非它做什么does。只收领域特定术语Only include terms specific to this projects context通用编程概念timeout、error types、utility patterns即使项目大量使用也不该收录。添加术语前先自问这是该上下文独有的概念还是通用编程概念只有前者属于这里。自然聚类时分小节Group terms under subheadings当术语形成自然聚类时用子标题分组若所有术语都属于一个连贯领域平铺列表即可。4.1 多上下文时的 CONTEXT-MAP.md多上下文仓库在根目录维护CONTEXT-MAP.md列出各上下文位置及相互关系CONTEXT-FORMAT.md# Context Map ## Contexts - [Ordering](https://link.gitcode.com/i/1c94b10683620ac73935af2214e92452) — receives and tracks customer orders - [Billing](https://link.gitcode.com/i/1c94b10683620ac73935af2214e92452) — generates invoices and processes payments - [Fulfillment](https://link.gitcode.com/i/1c94b10683620ac73935af2214e92452) — manages warehouse picking and shipping ## Relationships - **Ordering → Fulfillment**: Ordering emits OrderPlaced events; Fulfillment consumes them to start picking - **Fulfillment → Billing**: Fulfillment emits ShipmentDispatched events; Billing consumes them to generate invoices - **Ordering ↔ Billing**: Shared types for CustomerId and MoneyRelationships 部分用有向箭头表达上下文间的依赖与事件流这对理解谁拥有什么数据、谁消费什么事件至关重要。五、ADR只在真正需要时记录架构决策技能反复强调 ADR 要克制offer sparingly。只有以下三个条件同时成立时才提议创建 ADRSKILL.md难以逆转Hard to reverse——日后改变主意的代价有意义脱离上下文会令人费解Surprising without context——未来读者会疑惑他们为什么这么做真实权衡的结果The result of a real trade-off——当时确实存在多个候选方案你因具体原因选了一个。三者缺一就跳过。原因很直白ADR-FORMAT.md容易逆转的决策不值得记录你很快会再改不令人意外的决策没人会追问没有真实备选项的决策除了我们做了显而易见的事之外无话可说。5.1 ADR 的文件布局与模板ADR 存放在docs/adr/采用顺序编号0001-slug.md、0002-slug.md……目录同样懒创建。模板极简ADR-FORMAT.md# {Short title of the decision} {1-3 sentences: whats the context, what did we decide, and why.}一条 ADR 可以只有一个段落。价值在于记录做了决定以及为什么做而不是填满各章节。可选部分仅在真正有价值时加入Statusfrontmatterproposed | accepted | deprecated | superseded by ADR-NNNN——当决策会被反复审视时有用Considered Options——仅当被否掉的备选项值得被记住时Consequences——仅当有非显而易见的连锁影响需要指出时。编号规则扫描docs/adr/找到最大现有编号并加一。5.2 什么算值得记录的 ADRADR-FORMAT.md 给出了七类典型合格项架构形态Architectural shape我们用 monorepo写模型是事件溯源、读模型投影到 Postgres上下文间的集成模式Ordering 与 Billing 通过领域事件通信而非同步 HTTP带来锁定效应的技术选型Technology choices that carry lock-in数据库、消息总线、认证提供商、部署目标——不是每个库只是换掉要花一个季度的那些边界与范围决策Customer 数据归 Customer 上下文所有其他上下文只按 ID 引用——明确的不做什么与做什么同样有价值对显而易见路径的有意偏离我们用手写 SQL 而非 ORM因为 X——任何合理读者都会猜相反方案的场景必须记录防止下一个工程师修好某个故意为之的设计代码中看不到的约束合规要求不能用 AWS合作伙伴 API 合同要求响应时间低于 200ms被否方案的隐藏原因若你考虑过 GraphQL 却因微妙原因选了 REST记录它——否则六个月后还会有人再次提议 GraphQL。六、仓库中的真实范例pentestgpt_agent/CONTEXT.mddomain-modeling技能不是纸上谈兵——PentestGPT 仓库的 pentestgpt_agent/CONTEXT.md 就是该技能产物的实际样例AGENT.md 也明确将其登记为domain language and invariants领域语言与不变量。6.1 Language17 个领域的精确定义该文件首先用一两句话定义每个术语部分条目给出了概念间的关系。例如Supervisor拥有完全访问权的推理 Agent可使用 provider 工具并提出、选择一个任务其工具活动是诊断性的确定性校验仍拥有规范状态的最终所有权Executor执行一个租约任务并提出基于 trace 的完整访问 AgentMemory Kernel确定性 SQLite 权威负责校验并提交状态它不是 AgentProvider Adapter调用 Claude Code 或 Codex 并归一化其事件的外部模块只负责 provider 差异不负责渗透策略或记忆Evidence由一个合格的动作回执捕获的精确目标输出已完成命令的非零退出码可以构成有效的负向证据但 provider/工具传输错误被排除在外Diagnostic用于避免重复失败的类型化操作或进度信息永远不是证据。注意它严格遵循了 CONTEXT-FORMAT 的两条规则定义紧凑一两句、只收领域特定术语如 Decision CycleAgent EpisodeAction ReceiptTransport Recovery 都是渗透测试编排上下文独有的概念而非通用编程词汇。这与技能CONTEXT.md是术语表不是规格书的约束完全一致——文件通篇没有实现代码。6.2 Invariants术语之上的不可违反规则CONTEXT.md的独特之处在于它还承载Invariants不变量——跨术语的系统级约束例如恰好存在从零修订到当前修订的每一条 transition同一时刻至多一个任务/尝试处于活动状态且任务、尝试、租约修订与 trace 片段身份一致每个 episode 都是全新的resume null配置的试验中禁用 Claude 自动记忆目标派生的证据、诊断与文件都是不可信数据绝不能当作 Agent 指令。这些不变量与 pentestgpt_agent/src 下的实现一一呼应例如trial.py中的RunStatus.COMPLETED语义pentestgpt_agent/CONTEXT.md被明确限定为建立结构性完成与显式证据引用但不证明任意语义目标的蕴含——这正是与代码交叉引用行为所要求的精确性一个词一旦进入术语表它的语义就被钉死代码、测试、提示词三处都必须与之对齐。七、技能机制本身的工程实现安装、校验与 lintdomain-modeling之所以能被 Agent 自动发现与调用依赖仓库中一套完整的技能管理系统unified_agent/skills.py。理解它有助于你把握技能这一仓库级概念的工作方式双宿主发现目录Claude Code 从ws/.claude/skills/读取Codex 从跨 Agent 位置ws/.agents/skills/读取install_skills会把同一份 SKILL.md 以符号链接symlink或复制copy模式装进两个目录unified_agent/skills.py实现一处编写、双 Agent 生效。本仓库的 17 个技能含 domain-modeling都位于 .agents/skills 源目录下。frontmatter 校验load_skill要求 SKILL.md 必须以---YAML frontmatter 开头且格式合法name必须匹配^[a-z0-9](-[a-z0-9])*$且与目录名一致description必填且 ≤1024 字符unified_agent/skills.py。这些约束都有对应测试覆盖tests/test_skills.py。可移植性 lintlint_skill会标记 Claude 独有、Codex 无法解析的语法$ARGUMENTS参数替换、!动态 shell 注入、${CLAUDE_*}变量确保技能描述对两个宿主都可移植unified_agent/skills.py、tests/test_skills.py。从这些实现可以看出技能在 PentestGPT 中是一等公民它有规范的结构、有强制的元数据、有安装与校验流程。domain-modeling技能的 frontmatter 之所以被精心撰写正是为了在这套校验体系下既能通过load_skill的硬性检查又能借助 description 中的触发短语pin down domain terminologyrecord an architectural decisionanother skill needs to maintain the domain model被模型在合适时机自主调用。八、与其他技能的协同与最佳实践在 .agents/skills 的技能族谱中domain-modeling扮演语言与决策的记录者角色与其他技能形成互补与writing-great-skills的呼应后者SKILL.md提出的leading word引导词概念——用模型预训练中已有的紧凑概念锚定行为——在领域建模中同样有效术语表本身就是全项目共享的 leading words 集合。术语定义得越精确模型在各处使用同一词汇时行为越可预测。与triage、to-issues、to-prd的协作当新需求或缺陷被分诊、转写成 issue 或 PRD 时其中引入的新概念应同步回流到CONTEXT.md这正是 SKILL.md 中another skill needs to maintain the domain model这一触发场景。与测试体系的闭环领域术语一旦进入 pentestgpt_agent/CONTEXT.md就应能在 pentestgpt_agent/tests 的测试代码中看到同一套词汇如RunStatus.COMPLETED、resume、episode任何术语漂移都应触发与代码交叉引用行为的报警。结语把领域建模当作持续纪律而非一次性文档任务domain-modeling技能的核心主张可以浓缩为一句话领域模型不是写出来的文档而是在每次设计会话中实时锤炼出来的活物。它通过质疑术语、打磨语言、场景压测、代码对照、当场落盘五个动作保持模型的锐利通过CONTEXT 只收语言、ADR 只记难逆转的真权衡两条纪律保持文件的纯净。PentestGPT 仓库既提供了这套技能的规范文本SKILL.md、CONTEXT-FORMAT.md、ADR-FORMAT.md也提供了真实的实践样本pentestgpt_agent/CONTEXT.md与完整的机制实现unified_agent/skills.py、tests/test_skills.py——三者对照阅读即可完整掌握从技能规范到工程落地的全链路。【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考