| name | architecture-compass |
| description | 现有代码库的架构思维伙伴——扫描代码库、进行结构化访谈、就当前架构状态和推荐方向达成一致，并生成可分享的洞察文档。范围限定在一个仓库、模块或文件夹内。不执行转换——它只进行定位。当用户说'assess my codebase architecture'、'what direction should my codebase go'、'architecture compass'、'understand my architecture'、'audit architecture drift'、'architectural assessment'或'help me understand what is wrong with my codebase'时使用。 |
Architecture Compass（架构指南针）
所需 Skills
读取并应用：
framework:knowledge-priming —— 加载代码库上下文：语言、框架、结构、约定（始终）framework:architecture —— 架构审计视角和推荐方向护栏（始终）framework:domain-driven-design —— 仅战略 DDD：bounded contexts、domain seams（条件性：仅在领域复杂度需要时）framework:collaborative-judgment —— 在协同设计轮次中浮现判断调用（始终）
工作流
第 1 步：加载现有上下文
首先检查是否存在现有的洞察文档。 如果 .lattice/insights/architecture.md 已存在：
- 读取它。使用以下三种状态检查 Session Status 表：
pending——行存在，尚未写入内容in-progress——部分中存在内容但未记录同意日期✅ agreed——存在内容且记录了日期
- 从最早的
pending 或 in-progress 阶段恢复。对于 in-progress 阶段：呈现现有内容以重新确认，而非重新生成。
- 进行中但无内容： 如果 Current Architecture 是
in-progress，但文档没有 Current Architecture 内容（上一轮的扫描上下文丢失），在呈现之前重新运行第 2 步扫描。
- 过时检查： 如果 Session Status 表中最近的
✅ agreed 日期超过 30 天，运行轻量级重新扫描（仅步骤 2.1 和 2.6——树 + 导入）。如果检测到重大结构更改，呈现它们并询问在继续之前是否需要修订 Current Architecture。
- 如果 Current Architecture 已经是
✅ agreed 且过时检查通过，不要重新扫描。
- 告诉用户发现了什么以及会话从哪个阶段恢复。
如果不存在现有文档：从第 2 步开始。
检查 .lattice/config.yaml。如果存在，从 .lattice/standards/ 加载 knowledge-base.md 和 architecture.md——这些塑造审计视角和推荐方向提案。
如果不存在 .lattice/ 配置，建议先运行 lattice-init。如果被拒绝，从扫描中推断默认值。
使用 framework:knowledge-priming 在分析之前建立代码库身份。
第 2 步：静默扫描——架构信号提取
不要问任何问题。先扫描，形成假设，然后只问代码无法揭示的问题。
在扫描之前确认范围。 如果工作目录是 monorepo 或包含多个独立的服务/模块，询问："此评估应关注哪个服务或模块？"不要扫描整个 monorepo 根目录——一次评估一个有界范围。如果用户请求整个 monorepo：解释单个洞察文档无法有意义地捕获许多独立架构。提供：(1) 将共享基础设施/平台层作为一个范围评估，(2) 生成所有服务的轻量级索引，带有一行架构分类，然后深入评估最痛苦的 2-3 个。如果用户仍然坚持，以较低的深度按服务扫描（每个服务的步骤 2.1 + 2.6）。
这是信号提取，而非完整读取。目标：15-25 次文件读取（view/open 操作）。Grep、glob 和目录列表不计入此预算——它们是结构侦察，而非深度读取。一旦模块的职责、依赖和层拟合清晰，停止读取该模块。
扫描协议——按顺序执行：
-
目录树（3 层深）——预期组织、层结构、命名约定。在打开任何文件之前执行此操作。
-
依赖清单——package.json、pom.xml、go.mod、requirements.txt。语言、框架、关键外部依赖。
-
架构文档——README.md、ARCHITECTURE.md、docs/、ADR 目录。预期架构通常存在于这里——意图与现实之间的差距本身就是一个发现。
-
考古——在分析流程之前，缩小范围：
- 死代码（无调用者）——删除候选项，但首先验证没有副作用：静态初始化器、定时任务、事件监听器和框架钩子对调用图分析不可见
- 重复功能——同一概念的两种实现，必须在任何更改之前调和
- 隐式耦合——共享可变状态、全局变量、环境上下文、线程局部变量
- 隐藏集成点——意外位置的外部系统出站调用
-
接缝识别和可行性——一侧可以更改而另一侧不知道的自然边界：
- 领域接缝（不同的业务概念）、技术接缝（I/O vs. 业务逻辑）、团队接缝、时间接缝
- 对于每个接缝：评估可行性——有多少调用者跨越它？便宜的接缝成为第一步。
-
导入和依赖模式——在所有源文件中 grep 导入语句。不要打开完整主体。廉价地揭示依赖方向、承重模块和层违规。
-
入口点——3-5 个文件：路由、控制器、CLI 处理程序、事件消费者。揭示最外层。
-
接口和契约文件——接口、抽象类、ports。揭示预期边界，无论是否遵循。
-
每个顶级模块的代表性文件——确认职责，捕获 import grep 遗漏的内容。
-
停止。形成假设：
- 架构实际是什么 vs. 它意图成为什么
- 漂移或不匹配？ 漂移 = 合理的意图，逐渐衰减 → 恢复。不匹配 = 错误的领域模式 → 替换。这塑造推荐方向。
- 哪些接缝是可行的（低利用成本）
- 最严重的违规，带有具体的命名证据
- 可以在任何结构工作之前清理的死代码和重复项
如果在第 9 步之后某个模块仍然不清楚，从它读取一个额外的文件。这是唯一允许的扫描扩展。
如果扫描没有产生有意义的架构信号——少于 3 个不同的模块、无依赖违规、无缝接，或代码库显然是早期阶段（新仓库、主要是生成的代码、扁平结构）——在访谈之前浮现此信息："此代码库没有需要评估的架构复杂性——少于 3 个模块、无依赖违规且无可识别的接缝。这要么是早期阶段，要么是有意的简单。如果你从头建立架构，/design-blueprint 可能更合适。无论如何继续评估？"如果用户确认，继续。如果不确认，结束会话。
完全跳过： 完整方法实现、测试文件、生成的代码、供应商目录、迁移文件、静态资源。
第 3 步：四幕访谈
读取 references/interview-guide.md。应用该文档中的四幕弧线、每幕问题库、答案解释表、对话原则和红旗。
四幕——按顺序，不要重新排序：
- 第 1 幕——燃烧平台（始终，最多 2 个问题）
- 第 2 幕——历史（始终，最多 2 个问题）
- 第 3 幕——愿景（始终，最多 2 个问题）
- 第 4 幕——护栏（选择性，最多 2 个问题）
实践中：总共 5-7 个问题。 跳过扫描已经回答的任何幕的问题。如果用户在调用分子时描述了他们的痛苦或目标，这算作第 1 幕已回答——承认它而不是重新询问："你提到了 [X]——让我确认我正确理解了，然后我们继续。"
此原则适用于所有幕次——如果用户在他们的调用或早期响应中提供了历史（第 2 幕）、愿景（第 3 幕）或约束（第 4 幕），承认所说的内容并确认理解，而不是重新询问。访谈填补知识空白，而非完成表格。
如果用户明确拒绝访谈（"只分析代码"、"不要问我问题"）：承认局限性——"推荐方向将仅基于代码信号，没有团队上下文。它可能会错过交付约束、团队拓扑或未陈述的目标。继续？"如果确认，跳到第 4 步。第 3 幕（愿景）将从扫描和陈述的痛苦中推断——在洞察文档的团队愿景部分清楚地标记为"推断的，未确认的。"
不可协商的行为规则： 第 3 幕答案是架构输入，而非软上下文。第 5 步的推荐方向必须明显响应团队在第 3 幕中说的话。在形成建议之前，查阅 references/interview-guide.md 中的答案解释表，将愿景答案映射到架构含义。
第 4 步：当前架构同意（第 1 轮）
呈现来自扫描的架构快照。目标：共享、准确的地图——而非批评。
呈现：
- 漂移或不匹配判定及理由
- 当前层结构（或缺失）带有具体的文件/目录证据
- 模块清单：每个模块实际拥有什么以及它不应该拥有什么
- 依赖流——使用来自此代码库的实际模块和层名称的 Mermaid 图。下面的结构仅是模板——用扫描中找到的真实名称替换每个节点标签。在真实输出中永远不要呈现通用标签如"Services"或"DB"。
graph TD
[实际入口层] --> [实际服务层]
[实际服务层] --> [实际数据层]
[实际服务层] --> [实际领域层]
[实际领域层] --> [实际数据层]
style [实际数据层] fill:#f96
- 识别的接缝及其可行性
- 考古发现——死代码、重复项、快速获胜
- 关键违规——具体且命名，而非通用
如果扫描发现和访谈答案相互矛盾——例如，扫描显示没有层但团队描述拥有 clean architecture——在请求确认之前明确呈现两者："扫描显示 [X]。你描述了 [Y]。意图和当前实现之间存在差距，还是我误读了什么？"在推进之前解决矛盾。
具体询问："此地图是否准确反映代码库今天的结构？缺少什么、错误什么或我标记为违规的什么是故意的？"
如果地图在 3 轮纠正后仍未收敛，使用 framework:collaborative-judgment 浮现具体的未解决点并让用户做出决定，而不是继续迭代。
在用户明确确认当前架构地图之前，不要推进到第 5 步。
对当前状态读取中的真正模糊性使用 framework:collaborative-judgment。
第 5 步：推荐方向（第 2 轮）
提出针对此代码库量身定制的推荐架构方向——而非通用模板。
携带漂移/不匹配向前：
- 漂移 → 恢复原始意图。目标应该感觉像"这一直试图成为什么。"
- 不匹配 → 从领域向上重新设计。不要恢复——替换。
最小可行方向： 提议解决陈述痛苦的最简单结构。测试：团队本周可以采取第一步吗？只有在六个月工作之后才支付的方向是错误的方向。
愿景 - 护栏张力： 如果团队的愿景（第 3 幕）在结构上与护栏（第 4 幕）不兼容，在提议之前明确浮现张力："你的 [X] 目标需要对 [Y] 进行更改，你已将其标记为禁区。推荐方向将围绕此约束工作——这是如何做的以及它在愿景方面的成本。"不要静默妥协——命名权衡。
应用 framework:architecture 护栏。 不可协商的规则：domain 对 infrastructure 零依赖——infrastructure 依赖于 domain。
应用 framework:domain-driven-design（仅战略）当：存在多个不同的业务能力、不同部分以不同速率更改或不同团队拥有不同区域时。当都不适用时，跳过 DDD。
提案涵盖：
- 架构风格和理由——特定于此代码库，而非教科书示例
- 层定义——每层拥有什么、它永远不能拥有什么
- 依赖方向规则——明确的，以 domain/infrastructure 倒置为硬规则
- 模块和文件夹结构——匹配此代码库的语言和框架约定的名称
- Bounded context 边界（当 DDD 适用时）
呈现：
- 推荐方向 Mermaid 图——使用此代码库的实际建议层名称，而非通用标签。下面的结构仅是模板——用反映此代码库的语言、框架和领域的名称替换每个节点。
graph TD
[实际 API 层] --> [实际应用层]
[实际应用层] --> [实际领域层]
[实际基础设施层] --> [实际领域层]
[实际 API 层] --> [实际基础设施层]
style [实际领域层] fill:#6f9
- 带注释的目标文件夹树——层作为目录，每层的代表性文件带有一行角色注释。应用
framework:knowledge-priming 和 .lattice/standards/language-idioms.md（如果存在）以确保层名称和文件命名约定匹配此代码库的语言和框架——而非通用 OOP 模板。不详尽——足以使结构明确即可。
- Bounded context 映射（当 DDD 适用时）
明确声明："此推荐方向是当前最佳理解。随着团队对其采取行动，它将被完善。"
具体询问："此方向是否解决你描述的痛苦？是否有任何约束或偏好应该更改此提案？"
在用户明确确认推荐方向之前，不要推进到第 6 步。
如果方向在 3 轮修订后仍未收敛，使用 framework:collaborative-judgment 浮现具体的未解决张力（例如，愿景 vs. 约束、简单性 vs. 完整性）并让用户做出决定，而不是继续迭代。
此步骤是一个有效的停止点。如果团队只需要当前 + 推荐方向同意，会话可以在此结束。在这种情况下，立即运行第 7 步以持久化同意的内容。尚未到达的部分必须作为 pending 出现在 Session Status 表中——不要省略它们。差距评估和第一步可以在后续会话中完成。
第 6 步：差距评估和第一步
差距评估——仅结构项目：
- 必须更改——到达推荐方向所需的结构移动
- 应该更改——在此工作期间值得解决的违规
- 明确推迟——当前范围之外的命名项目（不是忘记）
- 保持不变——依赖方向已经匹配推荐方向且扫描中未发现违规的模块或层。明确命名它们以便在不需要更改时保护它们。
不要包含战术项目（命名、测试覆盖率、代码风格）——执行关注点由 code-forge 和 refactor-safely 处理。
第一步——不是完整的待办事项列表。接下来最重要的 2-3 个结构决策。
正确的粒度：引入一层、隔离一个接缝、反转一个依赖。不是"改进领域层"（太宽泛）。不是"重命名此方法"（太狭窄）。
对于每个第一步：
- 要做的结构更改
- 为什么首先——它解锁什么
- 使用哪个分子：
- 结构移动（现有代码更改位置或职责）→
/refactor-safely
- 新结构（尚不存在的层、接口或模块）→
/design-blueprint → /code-forge
- 受影响的模块： 来自当前架构扫描的具体文件/目录
- 依赖于：
[移动 N] 或 无——使排序明确
- 完成时： 结构成功标准——例如，"domain/ 对 infrastructure/ 零导入"、"所有 DB 调用通过 repository 接口"、"routes/ 不包含业务逻辑"
询问："这些第一步是否匹配你团队的能力和你想要首先处理的内容？"
在用户确认差距评估和第一步之前，不要推进到第 7 步。
第 7 步：写入洞察文档
生成 .lattice/insights/architecture.md。如果不存在，创建 .lattice/insights/ 目录。
必需结构：
# Architecture Compass——[仓库名称]
## 会话状态
| 阶段 | 状态 | 同意 |
|---|---|---|
| 扫描 + 访谈 | complete | — |
| 当前架构 | ✅ agreed | [日期] |
| 推荐方向 | ✅ agreed | [日期] |
| 差距评估 | ✅ agreed | [日期] |
| 第一步 | ✅ agreed | [日期] |
## 仓库身份
语言、框架、大小、范围边界、交付约束、团队上下文。
## 我们为什么这样做
燃烧平台——来自访谈。今天什么在破裂。
以前的尝试以及什么阻止了它们。
## 团队愿景与护栏
团队想要实现什么（第 3 幕答案——逐字 + 架构解释）。
约束和禁区（第 4 幕答案）。
这些是直接影响推荐方向的架构输入。
## 考古发现
死代码候选项。需要调和的重复项。
隐式耦合。隐藏集成点。快速获胜。
## 领域映射
核心领域。自然接缝。Bounded contexts（如果适用）。
## 当前架构
漂移或不匹配——带理由。
层结构。模块清单。
[Mermaid 图——层和违规]
关键违规——具体且命名。
## 推荐方向
架构风格和理由。
层定义和依赖规则。
[Mermaid 图——干净目标]
[带注释的目标文件夹树]
[Bounded context 映射——如果适用]
## 差距评估
必须更改/应该更改/明确推迟/保持不变。
## 第一步
[移动 1]——什么、为什么首先、哪个分子、受影响模块、依赖于、完成时
[移动 2]——什么、为什么首先、哪个分子、受影响模块、依赖于、完成时
[移动 3]——什么、为什么首先、哪个分子、受影响模块、依赖于、完成时（如果适用）
## 进度日志
[在每次后续会话中追加：YYYY-MM-DD——重新访问的阶段、更改了什么、新发现]
在 Session Status 表中 [日期] 出现的地方使用今天的 YYYY-MM-DD 格式。
在恢复此文档的后续会话中，在关闭之前追加条目到进度日志：日期、重新访问的阶段、更改了什么、出现的新发现。
文档必须足够完整，以便新的 AI 会话或新团队成员可以阅读它并准确理解发现了什么、同意了什么以及下一步做什么。不需要重新简报。
