incu-way-arch-assessment

架构评估流程

一种由关卡驱动的工作流，用于根据明确的质量属性和设计原则评估架构——可以是整个系统、某个模块，也可以是当前分支上的变更——并将评估结果转化为团队可据此采取行动的可追溯、经过优先级排序的评估报告。输出保存在 docs/assessments/arch/{slug}/ASSESSMENT.md。

两种调用模式：

• 独立运行（审查系统或设计）： 使用自己的分支 assess/arch-{slug} → 向 develop 提交 PR。
• 嵌入其他流程： 写入调用方当前的分支／工作树；评估随该流程的 PR 一起提交。不单独创建分支或 PR。例如： incu-way-development 在 Gate 2 评估计划中的设计，incu-way-docs 在编写文档时标记结构性风险，incu-way-init 评估现有代码库。

这是一个评估流程。与 incu-way-docs 一样，它不会维护 .ways/state.json（该模型用于 feature / bug / security 工作）。它 负责评估并提出建议——不会实施修复。执行建议属于单独的 incu-way-development 或 incu-way-bugs 工作项。

---

仓库资格检查（优先执行）

在 Phase 0 之前，根据 ~/.ways/config.yaml 中的 blacklist 检查当前仓库（格式遵循始终启用的 incu-base global-config 规则）。如果匹配，告知用户该仓库已被列入 incu-way 黑名单，并询问是否仍要继续（作为一次性例外）或停止——在用户答复前不要运行任何阶段。文件不存在或没有匹配项：照常继续。

---

Phase 0 — 范围与调研

目标： 在做出任何判断之前，了解评估对象及其评估视角。 只读。

信息收集

1. 根据现有上下文确认目标：
   • 整个仓库、特定模块／服务／有界上下文，或当前分支的差异 （拟议的变更或新增代码——git diff develop...HEAD）
   • 这是按现状构建的审查（现有代码），还是按设计方案的审查（尚未实施的计划／PRD／提案）
2. 首先阅读现有架构文档（docs/architecture/、README.md、PRD.md、 任何 ADR），以此为评估提供依据，避免重新推导已有内容。如果文档缺失或已过时，请注明——这本身就是一项发现。

调研目标

进行调研，暂不评判：

• 分解结构 — 实际的顶层结构（分层、六边形端口／适配器、功能目录、微服务），以及代码是否符合文档中的预期。
• 依赖关系 — 模块／包的依赖方向；循环依赖；耦合热点；各部分之间的依赖关系。
• 边界 — 领域逻辑与基础设施／框架代码各自所在的位置；跨边界泄漏情况。
• 横切关注点 — 认证、配置、日志／可观测性、错误处理、事务——各自所在位置及其一致性。
• 数据与集成 — 存储、外部系统，以及代码如何访问它们。
• 测试 — 覆盖了哪些层、测试采用何种形式、哪些内容无法测试。

Phase 0 退出标准

进入 Gate 1 之前，Claude 应能够说明：

• 评估目标，以及目标是按现状构建还是按设计方案评估
• 主要组件及其实际依赖关系
• 使用了哪些现有文档，哪些文档缺失或已过时
• 对该系统而言重要的候选质量属性
• 哪些区域尚不明确，并将标记为开放问题，而不是自行假定

不要根据名称推断设计属性。如果代码无法清楚表明某个结构事实，就应将其列为开放问题，而不是做出确信的判断。

---

阶段 1 — 评估范围和标准

提出评估内容以及评估所依据的标准，并根据目标调整范围（单个模块采用的评估尺度应比多服务平台更轻量）。按以下格式呈现：

## Proposed assessment

- **Target:** {repo | module X | current branch diff}
- **Mode:** as-built audit | as-designed review
- **Quality attributes (rated):**
  - [ ] Maintainability / modularity
  - [ ] Coupling & cohesion
  - [ ] Layering / boundary integrity (hexagonal, SoC)
  - [ ] Scalability & performance posture
  - [ ] Testability
  - [ ] Security posture (structural — defer deep checks to incu-way-security-validation)
  - [ ] Observability & operability
  - [ ] Consistency with documented architecture
- **Out of scope:** {what this pass will not cover}
- **Open questions:** {anything ambiguous about the target or intent}

• 删除目标不适用的属性；添加任何适用于该目标的特定属性。
• 询问：“这是针对 {target} 的评估范围和标准。请在我开始评估前确认。”
• 停止。在用户确认范围和标准之前，不要生成评估内容。

---

隔离设置（仅限独立模式）

如果嵌入在另一个工作流中运行，请跳过此步骤——写入现有分支/工作树。

如果独立运行，请在写入前询问用户要如何隔离工作：

你希望我在当前检出中创建一个新分支，还是创建一个独立的 git 工作树？

严格按照用户的回答操作。 询问后停止；在用户选择前，不要创建分支或工作树。

如果当前检出有未提交的更改，请停止并在切换分支或创建工作树前询问。

选项 A — 在当前检出中创建分支

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c assess/arch-{slug}

选项 B — 创建独立工作树

仅在 .worktrees/ 下创建工作树。不要询问用户要使用哪个路径。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/assess-arch-{slug} -b assess/arch-{slug} origin/develop

{slug} 是 {kebab-target}（例如 payments-core、checkout-redesign）。所有输出都在选定的工作位置内编写并提交。

---

阶段 2 — 编写评估

目标： 基于实际代码/设计生成 ASSESSMENT.md。

评估规则（不可妥协）

• 可追溯。 每项发现都要指出其证据——path/to/file.ext:line、模块、依赖关系或配置键。读者必须能够核实。
• 不臆测。 评估现状，而不是评估“应该”存在什么。如果某项属性不明确，应列入待解答问题／待核实事项——绝不要猜测评级。
• 给出评级，而不只是描述。 每项质量属性都要有评级及其依据，不能只用含糊的形容词。
• 严重程度反映风险，而非个人偏好。 问题的严重程度取决于其带来的架构风险（影响范围、导致缺陷的可能性、后续修改成本），而非个人风格偏好。
• 提出建议，而不实施。 建议应具体并注明优先级；此工作流不会修改代码。
• 记录矛盾。 如果代码与已记录的架构相矛盾，应明确说明矛盾，而不是默默选择一方。

ASSESSMENT.md 结构

# Architectural Assessment — {target}

## Scope
- Target: {repo | module | branch diff}
- Mode: as-built | as-designed
- Date: {YYYY-MM-DD}
- Criteria: {the attributes confirmed at Gate 1}

## Executive summary
3–5 sentences: overall health, the one or two things that matter most, the headline risks.

## Quality attribute ratings
| Attribute | Rating | Evidence | Notes |
|-----------|--------|----------|-------|
| Maintainability | Strong / Adequate / At risk / Poor | `path:line`, module | … |
| Coupling & cohesion | … | … | … |
| Layering / boundaries | … | … | … |
| Scalability | … | … | … |
| Testability | … | … | … |

## Strengths
What is genuinely well-structured and should be preserved (each with evidence).

## Findings
| # | Area | Severity | Finding | Evidence | Recommendation |
|---|------|----------|---------|----------|----------------|
| 1 | Coupling | High | Domain layer imports the HTTP framework directly | `src/domain/order.ts:12` | Introduce a port; move the dependency to the adapter |
| 2 | … | … | … | … | … |

Severity: Critical / High / Medium / Low — architectural risk, not style.

## Tech debt register
Debt items worth tracking, each with rough cost-to-fix and cost-of-delay.

## Open questions / to verify
- …

文字应精炼：句子简短直接；适合时优先使用表格，而非段落。

---

阶段 3 — 图表与优先级排序

• 图表（有助于说明时）： 绘制目标的 Mermaid 组件／依赖关系图，突出问题区域；如果建议重构，还应绘制目标状态图。结束前，使用 Mermaid 解析器验证每张图——无法渲染的图还不如没有。
• 按优先级排列建议： 将各项发现的建议整理成简短的立即执行／接下来执行／考虑执行列表，并为每项建议标注对应的发现编号。这是可执行的交接内容——“立即执行”事项通常会成为后续的 incu-way-development 或 incu-way-bugs 工作项。

---

阶段 4 — 审查

写好评估、图表和优先级排序后：

• 提供路径、执行摘要、按严重程度排列的主要发现，以及待解答问题／待核实事项。
• 说明：“架构评估已准备就绪，位于 docs/assessments/arch/{slug}/ASSESSMENT.md。待解答问题已列出，请提供意见。请审阅。”
• 停止。等待用户审阅后再继续。

如果嵌入在另一个工作流中运行，控制权将返回调用工作流的审查关卡——评估将在那里审阅，并随该工作流的 PR 一同发布。以下独立 PR 步骤将跳过。

---

第 4 阶段 — PR（仅独立模式）

建议调用 incu-way-prepare-pr，推送 assess/arch-{slug} 并创建 PR。不要自行推送或运行 gh pr create。

供 incu-way-prepare-pr 使用的 PR 标题/正文建议：

Title: assess(arch): {target}

PR 正文必须包含：

• 范围： 目标、模式和评估的标准。
• 摘要： 执行摘要以及按严重程度列出的主要发现。
• 建议： 立即处理 / 接下来处理 / 可考虑的事项列表。
• 待解答问题： 需要团队提供意见的未决事项。

PR 创建后，分享 PR URL。到此为止。用户批准前不要合并。

---

快速参考 — 闸门

闸门	触发条件	应说的内容	阻塞至
1	提出范围和标准	“这是针对 {target} 的评估范围和标准。请先确认，然后我再开始评估。”	用户确认
2	完成评估文档	“架构评估已准备就绪，位于 docs/assessments/arch/{slug}/ASSESSMENT.md。请审阅。”	用户审阅
3	（独立模式）完成审阅	建议使用 incu-way-prepare-pr 创建 PR assess/arch-{slug} → develop；用户运行后分享 URL	用户批准 PR

---

产出内容

docs/assessments/arch/{slug}/
  ASSESSMENT.md   # ratings, findings, tech debt, prioritized recommendations, diagrams

---

不要做的事

• 闸门 1 确认范围和标准之前，不要生成评估。
• 不要臆造结构、意图或评级。任何无法验证的内容都应列入 “待解答问题 / 待核实”。
• 不要提出无法追溯的发现——每项发现都必须指向文件、模块、边缘或键。
• 不要按风格偏好确定严重程度；严重程度取决于架构风险。
• 不要在此处实施修复——只提出建议，并让后续的 incu-way-development / incu-way-bugs 事项负责落实更改。
• Mermaid 解析器无法渲染的图表，不要将其标记为完成。
• 嵌入其他流程时，不要单独创建 PR——评估应随发起流程的 PR 一并提交。
• 独立模式下，不要直接写入 develop 或 main——请使用 assess/arch-{slug}。