mcpField
A
adr-discovery

adr-discovery

github.com/josiahsiegel开发5978 次安装19 周前更新
代码仓库

关于 adr-discovery

面向架构师的引导式技能，用于在编写架构决策记录（ADR）前收集信息。它只将人工确认的事实写入发现简报，把未确认内容放入开放问题清单，并在交接撰写前检查所需背景是否齐备。

主要功能

  1. 01记录事实前须经人工确认
  2. 02简报与开放问题文件分开
  3. 03为事实状态添加日期标签
  4. 04结构化扫描代码库与 ADR
  5. 05交接撰写前的检查清单

适用场景

  1. 01在撰写 ADR 前收集背景信息
  2. 02区分代码发现与已确认事实
  3. 03跟踪阻碍决策的未知项
  4. 04梳理相关 ADR 与组件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill adr-discovery

安装后在 Claude Code 中输入/adr-discovery确认已加载。

附带文件references/live-diagram-mode.mdreferences/open-questions-register.md

详细介绍

adr-discovery

为 ADR 收集前期背景。输出为 docs/architecture/discovery-brief.md，其中只包含经人工确认的事实，并附有一份记录未知项的 docs/architecture/open-questions.md。随后，架构师将工作移交给 adr-drafting，以实际起草决策。

核心规则：零幻觉

在架构师确认之前，任何事实都不得写入发现简报。代码发现、文档发现和推断都必须以问题的形式呈现，绝不能作为断言。

错误正确
"Your system uses Postgres and Redis.""我在 package.json 中看到了 pg 和 ioredis。Postgres 是你的主要存储吗？（是 / 否 / 不确定）"
"Component A talks to component B.""我在 src/a/client.ts 中看到了从 A 到 B 的 fetch。A 是否依赖 B？（是 / 否）"

每项已确认事实都必须在简报中注明日期并加上标签：[CONFIRMED YYYY-MM-DD]。未经确认的代码发现须标记为 [FROM CODE, UNCONFIRMED YYYY-MM-DD]，并记录在 open-questions.md 中，而不是简报里。

事实状态

状态所在位置是否可用于推动决策？
CONFIRMEDdiscovery-brief.md是
FROM CODE, UNCONFIRMEDopen-questions.md否
UNKNOWNopen-questions.md否
PARKEDopen-questions.md（附原因）否 — 必须在 ADR 的后果中注明

词汇表（首次使用时定义）

  • 组件 — 可运行 / 可部署的单元（C4 中的 Container），不是代码类。
  • 系统 — 本 ADR 关注的唯一有界产品。只能有一个。
  • 外部系统 — 团队不拥有但会与之交互的系统。
  • 参与者 — 人员角色（C4 术语中的 Person）。
  • 架构特征 — 受到压力的非功能质量（延迟、成本、可维护性、可用性、安全态势等）。
  • 冲突 — 两个 ADR 彼此冲突，且其中一个并未取代另一个。冲突是事实，不是失败；必须予以承认。
  • RFC — 提案阶段的文档。ADR 用于记录已作出的决策。

风格

  • 一次只讨论一个主题。绝不要在同一轮中提两个问题。
  • 记录答案之前，先用自己的话复述架构师的回答。
  • 直截了当。略过“好问题！”“非常棒！”等肯定语。
  • 指明具体文件、技术和组件，绝不要使用含糊的名词（如“服务”“数据库”）。
  • 如果一轮内容会包含多个 ?，或超过一个短段落，就精简内容。

九个阶段

1. 扫描，不要总结

在代码仓库中使用 glob 查找线索，绝不要对发现的内容作断言。

  • ADR 目录：docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md；还要检查旧版 architecture/decisions/，并提醒可能需要为 ADR Explorer 配置自定义根目录
  • 清单文件：package.json、pyproject.toml、Cargo.toml、go.mod、pom.xml、*.csproj
  • 代码仓库根目录及下一层目录中的 README
  • LikeC4 文件：**/*.c4、likec4.config.*
  • 已有的 discovery-brief.md / open-questions.md

只报告原始发现：“我找到了这些文件：X、Y、Z。我还没有对它们进行解读。”然后询问：“你想让我和你逐一查看这些文件，还是想从头开始？”

可以选择提供实时图表模式——参见 references/live-diagram-mode.md——但只能在架构师明确同意后提供。

2. 确认领域

只问一个问题："这个系统的用途是什么，面向哪些人？"

等待回答。复述。确认。然后在简报中写入一行 Domain:。

3. 逐一确认组件

定义组件（C4 Container——可部署单元）。然后逐个查看候选项。对每个候选项：

  1. 说明你发现的候选项名称（来自清单文件、README、LikeC4 文件或架构师的描述）。
  2. 询问：“这是本次决策范围内的组件吗？（是 / 否 / 不在范围内）”
  3. 如果是：请架构师用自己的话给出一句话描述。
  4. 如果否：将其移除。
  5. 严格限制：5 个组件。如果架构师提出第 6 个，询问这项决策是否打包处理。
4. 用人工编写的描述确认关系

对于每一对已确认的组件，询问：“A 是否依赖 B？如果是，用一行说明 A 使用 B 来做什么。”

没有人工编写描述的关系不会纳入简报。“A 与 B 通信”不算描述。

5. 确认现有 ADR

遍历 ADR 目录。对于每个 ADR，询问以下问题之一：

  • 取代？ — 这个新决策是否取代了之前的决策？
  • 修订？ — 它是否进行了调整，但没有取代之前的决策？
  • 相关？ — 它是否共享上下文，但独立存在？
  • 存在冲突？ — 它是否与之前的决策冲突，且双方都没有取代对方？
  • 无关？ — 将其剔除。

只有架构师的回答会纳入简报。不得推断。

6. 多仓库 + 生态系统探查

许多决策跨越仓库边界。针对每个相关仓库，询问：

  • 角色（使用方 / 提供方 / 共享库 / 平台）
  • 负责人（具名团队或个人）
  • 访问权限（读取 / 写入 / 无权限）
  • 该仓库中现有的 ADR
  • 现有的 C4 / 架构图

此外，还要询问组织是否有：

  • Wiki / Backstage / TechRadar / 平台级 ADR 集
  • 对决策有约束力的合规要求（数据驻留、SOC2、HIPAA、GDPR、FedRAMP）
  • 需要架构师遵循其决策的平台团队
7. 检查清单关卡

交接前，所有五项 MUST 都必须为 CONFIRMED：

MUST确认条件……
领域架构师已说明系统的功能及其服务对象
面临压力的架构特征架构师已指出正在优化的质量属性（延迟 / 成本 / 可用性 / 等）以及迫使做出决策的具体数值或条件
范围内的组件 ≤5 个架构师已逐一确认每个组件的名称，并提供一行描述
已分类相关 ADR每个现有 ADR 均已分类或明确剔除
已指定决策者具体人员 — 不能是“团队”或“领导层”

如果任何 MUST 为 UNKNOWN 或 PARKED，该技能将拒绝继续，并转到 open-questions.md。

8. C4 交接（可选）

如果架构师希望先绘制图表再起草，则交接给 c4-model（规范 C4：仅限 Context + Container 视图）。如果不需要，则跳过。

9. 交接以开始起草

当全部五项 MUST 都确认后，在 discovery-brief.md 底部写一行摘要：

Discovery complete: 2026-05-20. Hand off to adr-drafting.

起草技能会读取简报，不会再次询问其中已包含的内容。

持续更新的文件（特意放在 ADR 解析目录之外）

docs/architecture/discovery-brief.md 和 docs/architecture/open-questions.md 特意不放在 docs/adr/ 下，以免 ADR 解析工具和索引误将它们识别为 ADR。

discovery-brief.md 的结构
# Discovery Brief

## Domain
[CONFIRMED 2026-05-20] One sentence -- what does the system do, for whom.

## System in focus
[CONFIRMED 2026-05-20] Single named system.

## Architectural characteristic under pressure
[CONFIRMED 2026-05-20] e.g., "p95 read latency < 200ms on cross-entity reports."

## Components in scope (≤5)
[CONFIRMED 2026-05-20] - Name -- one-line description (architect's words)
...

## Relationships
[CONFIRMED 2026-05-20] - A → B: A uses B to <verb phrase>
...

## External actors
[CONFIRMED 2026-05-20] - Role -- one-line description
...

## Existing ADRs in play
[CONFIRMED 2026-05-20] - 0007 -- supersedes / amends / relates-to / tension

## Repos in play
[CONFIRMED 2026-05-20] - repo: role / owner / access / ADRs / C4

## Ecosystem constraints
[CONFIRMED 2026-05-20] - Compliance, platform, wiki/Backstage hits

## Decision-makers
[CONFIRMED 2026-05-20] - Named human(s)

---
Discovery complete: 2026-05-20. Hand off to adr-drafting.
open-questions.md 的结构 — 完整架构请参阅 references/open-questions-register.md。

此处同样适用“ADR 不是……”规则

即使在探查期间，也不要编写教程、含糊其辞或凭空捏造。请参阅 ../_shared/adr-is-not.md 中的共享检查清单。

参考资料

  • references/live-diagram-mode.md — 探查期间可选择启用的 LikeC4 实时图表工作流
  • references/open-questions-register.md — open-questions.md 的架构和规范
  • ../_shared/adr-is-not.md — 共享的“ADR 不是……”检查清单

评论

支持 Markdown