architecture-compass

架构指南针

目标

让架构决策明确、具有约束力、可在本地追溯并可执行。建立仓库原生的治理机制、审计实现，或执行由 ADR 指引的重构，且不覆盖已接受的历史记录，也不扩大权限范围。

适用场景

• 建立／协调 ADR 治理，或审计架构、决策覆盖情况、偏差、风险和证据。
• 规划或执行范围明确、受 ADR 治理的工作，包括先需要形成持久决策的广泛工作。

不适用场景

• 不涉及架构影响或 ADR 感知型边界检查的微小／纯样式修改或常规治理编辑。
• 泛泛的框架教育，或缺少目标证据且不涉及治理、审计、规划或重构结果的请求。

激活与回执呈现

通过 AC-ADR-053 Short · Long · Guide 路由激活与回执呈现。从 Short 开始，并在根据需要从内部索引加载 AC-INTERNAL-002（用于呈现器选择机制）之前先加载 Long。本分发器不定义呈现配置或呈现器策略。

工作流选择

每次直接调用都只公开以下工作流：

• setup：以 recommended 或 complete 覆盖范围建立或协调仓库原生的 ADR 治理。
• audit：严格只读地评估架构、ADR 覆盖情况、偏差和验证。
• refactor：执行已由本地接受的 ADR 治理、范围明确的工作。
• plan-refactor：协作制定并保存已批准、范围明确的重构规范，但不实施。
• plan-run-refactor：规划、保存、重新检查并执行已批准的广泛重构或涉及决策的重构。

激活时，先用简短一行列出 setup | audit | refactor | plan-refactor | plan-run-refactor，然后说明选定的路径、理由和授权范围。仅提供回复的评估也要保留此说明；简短回答仍须展示全部五个选项。

没有 auto 工作流。根据任务证据选择路径：

意图证据	选定的工作流
建立或协调 ADR 治理	setup/recommended
审查架构、ADR 覆盖情况、偏差或风险	audit
制定重构计划，但不执行	plan-refactor
执行广泛实施，或在执行前解决尚未确定的持久决策	plan-run-refactor
由已接受的本地 ADR 完全治理、范围明确的工作	refactor

对于意图明确、直接提出或由 Agent 发现且权限充分的任务，应简洁说明完整的工作流选项、选定的工作流及理由，然后继续。说明写入范围，以及任何重要的能力、受保护状态或单独审批边界；详细证据放入相应回执。若仅有笼统的激活请求、存在相互冲突的线索，或对结果、治理、范围、持久化或修改权限存在歧义，则须展示工作流选项并提问。

Agent 发起的激活可以在没有修改权限的情况下选择并宣布 audit。仅当用户现有任务已经要求相应结果和范围时，才可以选择会产生修改的工作流。选择工作流本身绝不授权破坏性、付费、不可逆、外部、部署、发布、生产或扩大范围的操作。

参考资料

从ADR 目录开始。根据 Scope、Category、Tags 和 Applies when 选择条目：

• 首先阅读 Short。
• 当某项已选决策适用于当前任务、存在冲突，或实现依赖其不变量时，阅读 Long。
• 仅在需要了解当前流程、示例、命令或兼容性说明时阅读 Guide。
• 任务范围较小时，不要加载整个库。
• Long 是规范依据。Short 不能放宽 Long；Guide 不具规范性。

通过以下文档了解技能行为：

• 工作流： AC-ADR-064 Short · Guide。
• 验证： AC-ADR-049 Guide。
• 宿主状态： AC-ADR-036 Guide。
• 执行与声明： AC-ADR-003 Guide · AC-ADR-004 Guide。
• 展示： AC-ADR-050 Short · Guide。
• 已采纳的 Jev 宿主建议： AC-ADR-065 Short · Long · Guide；在本地采纳、宿主前置条件证据或合规审计时加载。
• 产品规划： AC-ADR-067 Short · Long · Guide；在协调功能规划、细化模块契约或采纳相关 Setup 时加载。对于已选技能的复用及单独授权的配置，使用 AC-ADR-068 Long。
• 冲突： AC-ADR-046 Guide。

对于提供方机制，先确定适用的公开 AC-ADR，并首先加载其 Long。然后有条件地阅读内部 ADR 索引，并且仅在解决持久化问题时阅读 AC-INTERNAL-001，或在渲染回执时阅读 AC-INTERNAL-002。内部 ADR 属于实现政策，不纳入目标仓库的采纳范围，也不能放宽已接受的公开 Long 决策。

使用目录了解命名空间权威性、沿袭关系、规范 Long 版本以及特定任务的决策。AC-ADR-001 仅作为已被取代的历史背景。 对于测试工作，使用目录选择 AC-ADR-059 来确定仓库验证归属，选择 AC-ADR-060 来评估运行时／状态影响，选择 AC-ADR-061 来提供分布式证明，选择 AC-ADR-062 来评估转换缓存。仅选择适用的候选项；保持七项决策、证据为空的基础不变。映射现有的等效本地决策，而不是重复创建。以只读方式审计已采纳的结果，并将 met、unmet、unmeasured、waived 和 not-applicable 与执行状态区分开。使用测试回执，并遵循目标已有的证据惯例。推广测试变更之前，根据当前目录推导公开 ADR、三元组和可采纳项的数量；核对完整的采纳矩阵、决策锁定／沿袭关系和评估清单，然后验证重新生成／干净安装后的技能字节一致性，并确认已安装负载中不包含夹具／评估文件。若推广会改变公开治理或分发契约（包括通过文档表达的变更），则应用 AC-ADR-049 的 high 风险下限。

需要检查的输入

确定路径后，只检查该路径所需的内容：

• 结果、仓库身份／HEAD、受保护的 Git／外部状态，以及确切的授权范围。
• 仓库说明、ADR／索引／映射／历史记录惯例、架构／技术栈契约，以及验证回执。
• 仅检查所选路径所需的代表性代码、测试、CI、公开契约，以及迁移／安全／交付证据。
• 支持的说明文件位置：最近的 AGENTS.md、CLAUDE.md、现有的 CLAUDE.local.md、.claude/rules、.cursor/rules，以及仅作为迁移证据的旧版 .cursorrules。

不要自动将 CONTEXT.md 归类为 Claude 说明文件。

在持久化规范、ADR、报告或说明文件变更之前，先通过 AC-ADR-052 简版 · 长版 · 指南确定路径。从简版开始；在有条件地从内部索引加载 AC-INTERNAL-001 以处理持久化路径解析机制之前，先加载长版。此分派器不会选择或授权任何写入位置。

权限与协作

使用两个相互独立的维度：

1. 主机／仓库说明、权限、受保护路径、用户授权和安全约束，决定哪些操作可以执行。
2. 适用的已接受 ADR 或取代它们的 ADR，决定预期架构。

当前代码证明的是当前状态，而非预期策略。若请求的操作会违反已接受的 ADR，必须发出清晰警告，指出相关决策、冲突、受影响的范围和解决方案；在后续 ADR／适配方案获接受或冲突撤销之前，停止受影响的实现工作。

依据 AC-ADR-046 对架构来源排序：适用且已接受或已被取代的目标 ADR；具体的规范目标文档；与 ADR 关联的已批准目标示例；一致的当前实现；适用且可采纳的提供方决策；然后是通用框架默认设置。绝不要将相互矛盾的来源混合成未记录的折中方案。记录来源、受影响的范围及影响、建议的解决方案和决策负责人，并且只停止依赖该决策的工作。此排序不能扩大用户、主机、仓库或权限所授予的操作权限。

如果证据实质性改变了路径，应先说明重新分类，并在继续之前确定其权限依据。规划能力与文件系统权限相互独立。绝不要声称提示词文本改变了其中任一项控制。

工作流

在选择后、生成制品或执行变更之前，加载 AC-ADR-064 Guide 和匹配的报告资源。保持这些入口门槛清晰可见：

对于请求的代码简化、减少重复或复用库，在选择工作流后加载可选的 AC-ADR-006 simplification loop。在该路径的权限范围内将其用于只读审计、规划或经授权的执行；它不会增加工作流或目标策略。

setup

• 对于相关的协同产品／功能规划，有条件地提出 AC-ADR-067 并遵循其 Guide。确定本地身份、精确且受支持的启动绑定、明确的技能预选、可用性及独立的配置授权。保留七项决策基础；缺失或实验性技能只会阻止依赖它的交接。

• 对于 recommended，使用目标证据；对于 complete，评估目标仓库中每项已接受且可采纳的决策。只有新的或证据为空的仓库，才将 AC-ADR-005、006、018、019、021、022 和 049 作为初始候选基础。Setup 从不授权应用重构、部署、发布或生产探测。

• 选择 AC-ADR-065 时，通过其 Guide 记录仓库原生的采纳映射、授权主机和前置条件缺口。采纳不会启用钩子或授权 TypeSafe 处理。

audit

• 保持可强制执行的禁止写入行为，并进行严格只读的架构、ADR 覆盖、漂移和验证评估。不创建任何制品或执行任何变更。对于已采纳的 Jev 策略，分别报告已安装、已配置、已启用／受信任、已获处理授权、当前清单和合格证据。不得请求任何服务提供方，也不得尝试资格认定／修复；指出未满足的义务，同时保留原生工作。

refactor

• 确认已接受的本地 ADR 具有治理效力，且请求授权了整个有界变更。遇到治理缺失、冲突、尚未解决的持久性选择、范围扩展或重大漂移时停止。直接重构绝不擅自创设持久性决策，也不静默修复治理。

plan-refactor

• 通过原生或对话式规划明确并批准有界规范；在任何所需退出后，仅持久化经授权的治理制品，并在源代码实现前停止。

plan-run-refactor

• 遵循 plan-refactor，然后重新检查状态，仅按未变更的已批准计划分阶段执行可逆操作。遇到重大漂移、新决策、验证失败或范围扩展时停止。

计划生命周期

请参阅 AC-ADR-064 和 AC-ADR-036 指南，了解详细的状态转换和可移植的状态处理方式：

1. 根据观察到的能力选择执行主机通道，不受目标运行时影响。必要时，将 Planning capability 报告为 Active | Available but inactive | Unavailable | Explicitly declined | Indeterminate | Not applicable。尊重已启用或明确请求的原生 Plan，并在工作内容复杂且存在歧义时推荐使用。控制项未启用、缺失、被拒绝或状态未知，本身不会阻止获准的只读探索和对话；不要臆造控制项，也不要声称模式已更改。
2. 复用先前的答复和权威信息。在征求一次批准前，准备完整、可供审阅的草稿，以及准确的交付/写入范围。只有当原生最终批准的实际语义涵盖内容和写入时，才能同时批准两者；单独切换模式不够。跨越必需的主机状态转换时保留批准，只针对有实质影响的变更重新征求批准。
3. Plan 模式启用期间，不得写入目标仓库/工作区中的任何内容。模式或权限状态未知时，绝不意味着获准写入。解决必要的状态转换期间，仍可进行不写入的对话和已确认不会产生变更的读取操作。明确提出的原生 Plan 请求在观察到其已启用之前，始终处于待处理状态；尊重被拒绝的建议，不会静默退出已启用的 Plan。
4. 在需要时，于批准后和退出 Plan 模式后重新检查状态，再进行持久化或执行。plan-refactor 仅保存已获准的治理内容，或完成明确的纯对话交付，不得声称内容已持久化；源代码实现属于需另行授权的执行。提议持久化 ADR 并不代表接受其决定。
5. 仅在受支持时使用结构化问题或异步问题。等待必需答复期间，只继续进行相互独立且已获准的工作。沉默、超时和预选选项均不构成批准。

条件式稳定技能选择器指令

将此目标仓库指令归类为 applicable、not applicable 或 indeterminate。只有证据证明目标发布了包含多个实质性工作流的稳定公共技能时，才适用此指令。

• 在 setup 中，保留等效规则，或添加通用规则，要求完整披露有限的全部工作流、依据意图进行选择并说明理由、针对歧义提出问题、仅在已获准的结果/范围内执行变更，以及单独征求高风险/外部操作的批准。
• 在 audit 中，报告归类结果以及任何缺失、等效或冲突的规则，不得写入。
• 直接执行 refactor 不会修复缺失的规则；应将治理修复转交给 setup。
• indeterminate 绝不授权写入。
• 绝不将本仓库或提供方技能的 ADR ID 复制到目标仓库。仅当本地治理要求作出决定时，才使用仓库原生标识。

公共状态

必要时，使用 AC-ADR-036 指南和报告资产中有证据支持的精确 Read-only enforcement、Architecture decision status 和 Execution status 值。规划和文件系统执行情况相互独立。completed 仅涵盖已获准的部分/阶段；这不代表 CI、发布、部署、生产环境或第三方操作成功。

对于面向用户的简明结果列表，请通过 AC-ADR-050 Short 处理状态语义，并通过 AC-ADR-053 及上述条件式内部渲染器路径处理呈现方式。

资产

资产为衍生产物，不具规范性。setup 请使用 assets/setup-report-template.md，其他路径请使用 assets/refactor-report-template.md；仅在已获准的治理工作中使用其余资产。适用的规范性长期 ADR 优先。

脚本

Architecture Compass 不附带可执行的运行时脚本。仅在了解其行为和写入效果后，才使用仓库原生验证工具；不要在审计过程中臆造或安装辅助工具。

安全规则

• 不要臆造仓库事实、路径、命令、ADR、映射、验证结果或主机能力；不要根据含糊信息推断会发生变更。
• 不要用捆绑的决策覆盖已接受的目标 ADR，也不要将审计变成设置、规划或实施工作。
• 不要仅仅因为某项公开技能可用或受到推荐，就安装、调用、引入或配置它。
• 不要在可复用的产物中暴露机密、客户数据、私有来源信息或内部主机名。
• 破坏性、不可逆、对外部、部署、发布、生产以及扩大范围的工作，都需要单独授权、明确目标、停止条件和恢复证据。
• 不要重复证明义务、重用已失效的凭据、创建流于形式的永久性冒烟测试框架，或夸大证据阶段。
• 若出现范围偏移、缺少授权、与受保护路径重叠、映射不明确、ADR 冲突未解决或必需验证失败，请停止。

输出格式

使用匹配的报告资源和 AC-ADR-004 证据表。包括工作流集合及其选择、覆盖范围、写入范围/状态/受保护状态、已检查和无法获取的证据、决策/映射或发现、已批准的计划或变更、AC-ADR-049 台账、风险/延后触发条件，以及下一项获授权的操作。

通过 AC-ADR-053 及其有条件的内部适配器路由生成最终凭据；本节仅说明输出组装，不要重复其持久呈现策略。

对于 audit，按严重程度排序提供发现，不附补丁，也不写入仓库。对于计划路由，区分已批准的内容和写入范围、待处理的转换/持久化、已持久化的产物、状态复查结果以及已执行的工作。

完成标准

按照 AC-ADR-064 Guide 中所选流程的标准执行，并核对其 AC-ADR-049 凭据。完成范围仅限于获授权的工作流和证据阶段。

失败模式

遵循 AC-ADR-064 Guide 中的路由和计划停止规则，以及 AC-ADR-049 Guide 中的验证恢复规则。绝不要将受阻或不确定状态表述为已完成。