architect

架构评估

评估代码库在结构层面上的组织是否良好。通过分层分析逐步进行：发现价值观、全面扫描、深入分析、评估，以及可选的规划与执行。

这不是代码审查（正确性）、代码简化（清理），也不属于 /ship（PR 前流程）。这些技能关注代码质量和代码变更。/architect 关注代码库的组织方式——模块化、耦合、组合、框架契合度和结构连贯性。

调用方式

命令	行为
/architect	完整流程：Teach（如有需要）> Sweep > Deep Dive > Assess
/architect --teach	重新进行价值观发现
/architect --sweep	仅进行全面扫描，跳过深入分析
/architect <target>	聚焦某个子系统（例如“调度系统”、app/models）。如有需要，先运行 Teach，然后仅针对目标区域进行扫描和深入分析。更新主评估文档。

阶段

1. Teach — 发现价值观（每个项目首次运行时）。以对话形式进行。
2. Sweep — 从 7 个架构视角快速全面扫描。
3. Deep Dive — 并行分析扫描中标记的视角。
4. Assess — 展示发现结果，与用户讨论并生成文档。
5. Plan — 分阶段制定实施策略（按需进行）。
6. Execute — 调用编写计划的流程以重构（按需进行）。

解析参数

解析 $ARGUMENTS 中的标志和目标：

• --teach — 即使配置已存在，也强制重新进行价值观发现
• --sweep — 仅进行全面扫描，跳过深入分析
• 其他所有内容都视为 <target> — 要聚焦的子系统（路径或描述）

多个标志可以组合使用：--teach 搭配目标时，会重新发现价值观，然后聚焦于该子系统。

项目检测

ARCHITECT="$HOME/.claude/skills/architect/scripts/architect.sh"
PROJECT_INFO=$("$ARCHITECT" detect)
SLUG=$(echo "$PROJECT_INFO" | jq -r '.slug')
ROOT=$(echo "$PROJECT_INFO" | jq -r '.root')
CONFIGURED=$(echo "$PROJECT_INFO" | jq -r '.configured')

如果 SLUG 为空，则停止并提示：“当前不在 Git 仓库中。/architect 需要在 Git 仓库中运行。”

阶段 1：Teach — 发现价值观

此阶段以对话形式进行。每次只问一个问题。等待用户回答后再继续。不要一次性列出所有问题。

跳过条件： 如果 CONFIGURED 为 true 且未传入 --teach，则跳过此阶段。改为加载现有配置：

CONFIG=$("$ARCHITECT" config "$SLUG")

然后继续阶段 2（Sweep）。

如果传入了 --teach： 即使配置已存在，也运行此阶段。新配置将覆盖旧配置（使用 --force）。

步骤 1：自动检测框架

扫描项目根目录以查找框架标识：

• 包含 rails 的 Gemfile — Ruby on Rails
• 包含 nuxt 的 package.json — Nuxt.js
• 包含 vue 的 package.json — Vue.js
• 包含 next 或 react 的 package.json — Next.js / React
• go.mod — Go
• 包含 django 的 pyproject.toml 或 requirements.txt — Django
• 包含 flask 或 fastapi 的 pyproject.toml 或 requirements.txt — Flask / FastAPI
• Cargo.toml — Rust
• 包含 phoenix 的 mix.exs — Phoenix (Elixir)

说明检测结果：“我检测到这是一个 [framework] 项目。判断正确吗？或者你能补充一下技术栈的信息吗？”

等待用户确认后再继续。如果用户纠正了检测结果，则采用用户的回答。

Step 2: 了解架构理念

根据检测到的框架，列出 3-4 种思路流派。这些流派决定了技能如何评估架构——没有唯一的“正确”答案，用户的偏好会影响哪些问题算作发现，哪些只是设计选择。

对于 Ruby on Rails：

我想了解你的架构理念。以下是 Rails 中常见的思路流派——你认同哪一种，还是更倾向于混合采用？

1. Rails 之道（DHH） — 约定优于配置。使用 Concern 共享行为。胖模型也没问题。宏伟的单体架构。框架就是架构。
2. Sandi Metz 的面向对象编程 — 小对象、单一职责。组合优于继承。依赖注入。类不超过 100 行，方法不超过 5 行（这是理想目标，不是教条）。
3. 六边形／整洁架构 — 端口与适配器。领域逻辑独立于框架。依赖倒置。Rails 位于边缘，核心使用纯 Ruby。
4. 务实混合 — 各取所长。不拘泥于教条。代码库服务于团队，而非某种理念。

对于 Vue/Nuxt：

1. 组合优先 — 所有逻辑都用 Composable。组件保持精简。逻辑放在 Composable 中，组件只负责模板和编排。
2. 组件中心 — 组件管理自身逻辑。Props 向下传递，事件向上传递。优先使用本地状态。只有在行为确实需要共享时才使用 Composable。
3. Store 驱动 — Pinia Store 是事实来源。组件渲染 Store 状态。业务逻辑放在 Store 和 Action 中。
4. 务实混合 — 根据功能选择合适的方式。不拘泥于单一模式。

对于 Go：

1. 标准库至上 — 尽量减少依赖。使用 net/http，而非框架。采用扁平的包结构。按需发现接口，而非预先设计接口。
2. 领域驱动设计 — 按领域而非层次划分包。使用内部包实现隔离。显式注入依赖。
3. 六边形／整洁架构 — 端口与适配器。框架位于边缘。领域核心不依赖外部组件。
4. 务实混合 — 采用有效的做法。遵循 Go 惯用方式，而非照搬其他模式。

对于其他框架，请提供类似的选项——符合框架惯用方式、侧重面向对象／组合、整洁架构，以及务实混合。保持相同的对话语气。

等待用户回答。保存用户的选择。

Step 3: 了解关键价值取向

根据用户选择的理念，围绕具体偏好提出 3-5 个有针对性的问题。这些问题用于校准技能指出结构性问题的严格程度。一次只问一个问题。

根据框架和用户选择的理念，从以下问题中挑选相关问题：

• 耦合容忍度：“你如何看待与框架的耦合？领域逻辑直接使用 ActiveRecord/Pinia 等组件是否可以，还是你更倾向于设置分离层？”

• 文件大小偏好：“你对文件大小的接受程度如何？200-300 行的类／组件可以接受吗，还是更希望拆分得更小？”

• 抽象倾向：“你如何看待服务对象、表单对象、交互器或 Composable 等抽象？可以自由使用，还是只在问题明显时才使用？”

• 测试架构：“你如何考虑测试的组织方式？与源代码目录树对应？按类型（单元测试／集成测试）分开？测试行为还是实现？”

• 命名约定：“你对命名有什么特别的看法吗？服务、任务、组件等是否遵循特定约定？”

根据框架调整问题——不要在 Go 项目中询问对 ActiveRecord 耦合的看法。如果答案已经明确，问 3 个问题也可以。最多问 5 个。

步骤 4：询问评估文档的存放位置

评估会生成一个存储在项目仓库中的 Markdown 文档。询问应将其放在哪里：

“应该将架构评估文档存放在此仓库的什么位置？常见做法是使用 project/architecture-assessment.md，这样可以吗？还是你有其他偏好？”

存储相对于项目根目录的路径。

步骤 5：处理 slug 冲突

保存前，检查检测到的 slug 是否已有配置指向不同的 project_root：

EXISTING_CONFIG=$("$ARCHITECT" config "$SLUG" 2>/dev/null || echo "")

如果 EXISTING_CONFIG 非空，提取其中的 project_root：

EXISTING_ROOT=$(echo "$EXISTING_CONFIG" | jq -r '.project_root')

如果 EXISTING_ROOT 与 ROOT 不同，则表示存在冲突——两个不同的仓库恰好具有相同的目录名。询问：

“已有一个 slug 为 [slug] 的配置，指向 [existing_root]。此项目位于 [root]。这个项目应该使用什么 slug？”

之后使用用户提供的答案作为 slug。

步骤 6：保存配置

使用收集到的值构建 JSON 配置对象并保存：

"$ARCHITECT" init "$SLUG" '{
  "project_root": "<ROOT>",
  "project_name": "<project name from user or basename of ROOT>",
  "framework": "<detected framework>",
  "philosophy": "<chosen philosophy>",
  "values": {
    "coupling_tolerance": "<answer>",
    "file_size_comfort": "<answer>",
    "abstraction_appetite": "<answer>",
    "test_architecture": "<answer>",
    "naming_conventions": "<answer>"
  },
  "artifact_path": "<chosen path>",
  "created_at": "<ISO timestamp>"
}' --force

仅包含实际询问并得到回答的值。--force 标志可确保重新运行 --teach 时干净地覆盖配置。

向用户确认：“明白了。已为 [slug] 保存配置。接下来进入扫描阶段。”

更新状态，记录教学已完成：

"$ARCHITECT" update-state "$SLUG" "teach_complete=true" "teach_date=$(date -u +%Y-%m-%dT%H:%M:%SZ)"

---

阶段 2：扫描——广泛的架构扫描

快速、广泛地扫描 7 个架构视角。使用单个 Sonnet 子 Agent，以节省成本、提高速度——这是初步筛查，而非深入分析。

步骤 1：加载配置

CONFIG=$("$ARCHITECT" config "$SLUG")

提取子 Agent 提示词所需的关键字段：

FRAMEWORK=$(echo "$CONFIG" | jq -r '.framework')
PHILOSOPHY=$(echo "$CONFIG" | jq -r '.philosophy')

步骤 2：确定范围

如果传入了 <target>，扫描范围仅限于该子系统。构建范围说明：

• 未指定目标： "扫描 ROOT 中的整个项目。"
• 目标是路径（以 /、./ 开头，或是一个存在的目录）："重点扫描 ROOT/<target>，以及它与代码库其余部分的交互。"
• 目标是描述（例如，“调度系统”）："重点扫描所描述的子系统：<target>。先找出相关文件和目录，再进行分析。"

步骤 3：调度扫描 Agent

使用 Agent 工具调度一个子 Agent：

Agent(model: "sonnet", description: "Sweep: broad architectural scan of {SLUG}")

提示词必须完全自包含——子 Agent 没有对话上下文。需包含它所需的所有内容：

You are an architectural reviewer performing a broad sweep of a codebase.
Your job is to triage — identify areas that need deeper analysis, not to
do the deep analysis yourself.

## Project

- **Root:** {ROOT}
- **Framework:** {FRAMEWORK}
- **Philosophy:** {PHILOSOPHY}
- **Full config:** {CONFIG}

## Scope

{scope_instruction}

## Sampling Strategy

Do NOT read every file. Be strategic:

1. **Directory structure first** — run `ls` and `find` (depth-limited) to
   understand the layout
2. **Key entry points** — main config files, route definitions, application
   entry points, schema files
3. **Representative files per layer** — pick 2-3 files from each major
   directory (models, controllers, views, services, composables, etc.)
4. **Boundary files** — files that connect layers or modules (routers,
   registries, factories, dependency injection setup)
5. **Large files** — check file sizes, sample the biggest ones (often
   where coupling and cohesion issues live)

Budget: aim for ~30-50 files sampled total, more for large codebases.

## Architectural Lenses

Evaluate the codebase through each of these 7 lenses:

### 1. Structural Organization
- Directory layout and file grouping — by layer, by feature, or mixed?
- Separation of concerns — is business logic separated from framework plumbing?
- Naming conventions — consistent? Descriptive? Following framework idioms?
- Co-location — are related files near each other or scattered?

### 2. Design Patterns
- GoF patterns in use: adapter, strategy, facade, observer, factory, etc.
- Are patterns applied appropriately or forced where simpler code would do?
- Missing patterns — places where a well-known pattern would reduce complexity
- Over-patterned code — unnecessary abstraction layers, pattern-for-pattern's-sake

### 3. Composition & Inheritance
- Inheritance depth — deep hierarchies are a red flag
- Composable units — are behaviors composed via mixins/modules/composables or
  hardcoded into class hierarchies?
- Mixin/concern sprawl — too many small mixins that fragment understanding

### 4. Coupling & Cohesion
- Module dependencies — who depends on whom? Are there clear layers?
- Boundary clarity — can you change one module without touching three others?
- God objects — classes/modules that know too much or do too much
- Circular dependencies — A depends on B depends on A

### 5. Framework Alignment
- Convention adherence — is the team using the framework the way it was designed?
- Reinvented wheels — building custom solutions for things the framework provides
- Framework-specific anti-patterns (e.g., Rails: SQL in views, callbacks doing
  business logic, skip_before_action sprawl; Vue: mutating props, massive
  computed properties, v-if/v-for on same element)

### 6. API & Interface Design
- Internal API consistency — do similar operations have similar interfaces?
- Method signatures — clear parameter names? Reasonable arity? Options hashes
  vs. keyword args?
- Public surface area — is the public API minimal and intentional, or does
  everything leak?

### 7. Duplication & Reuse
- Copy-paste patterns — similar code in multiple places that should be shared
- Inconsistent approaches — the same problem solved differently in different places
- Missing shared code — utilities or patterns that should be extracted

## Output Format

Return your findings as a JSON object. Be concise in notes — this is triage,
not a full report. Include file_pointers so the deep dive knows where to look.

```json
{
  "timestamp": "<current ISO timestamp>",
  "scope": "<'full' or the target description>",
  "files_sampled": <number of files you read>,
  "lenses": {
    "structural_organization": {
      "health": "green|yellow|red",
      "notes": "Brief summary — what you found, why this rating",
      "file_pointers": ["paths/that/illustrate/the/finding"]
    },
    "design_patterns": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "composition_inheritance": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "coupling_cohesion": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "framework_alignment": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "api_interface_design": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "duplication_reuse": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    }
  }
}
```

**Health ratings:**
- **green** — no significant issues found, aligns with the project's stated philosophy
- **yellow** — some concerns worth investigating, potential improvements
- **red** — clear structural problems that affect maintainability or scalability

Be honest. Green is fine — not every lens will have issues. Don't manufacture
findings. But don't be afraid of red when it's warranted.

Return ONLY the JSON object, no surrounding text.

步骤 4：处理扫描结果

解析子 Agent 返回的 JSON。如果响应不是有效的 JSON，则从响应中提取 JSON（查找从 { 到 } 的代码块）并解析。

步骤 5：记录扫描

"$ARCHITECT" sweep-log "$SLUG" '<sweep_json>'

步骤 6：更新状态

"$ARCHITECT" update-state "$SLUG" "last_sweep=$(date -u +%Y-%m-%dT%H:%M:%SZ)"

步骤 7：检查停止条件

如果传入了 --sweep，以易于阅读的格式向用户展示扫描结果，然后停止：

## Architectural Sweep — {project_name}

| Lens | Health | Notes |
|------|--------|-------|
| Structural Organization | :green_circle: | ... |
| Design Patterns | :yellow_circle: | ... |
| ... | ... | ... |

**Flagged for deep dive:** Design Patterns, Coupling & Cohesion
**Files sampled:** N

Run `/architect` (without --sweep) to continue with deep analysis.

如果未传入 --sweep，则继续进入阶段 3。

---

阶段 3：深入分析——并行视角分析

针对扫描中标记为黄色或红色的每个视角，调度一个专用的 Sonnet 子 Agent 进行详细分析。所有标记的视角均并行运行。

步骤 1：识别已标记的视角

从扫描结果中收集所有 health 为 "yellow" 或 "red" 的视角。如果所有视角均为绿色，则完全跳过阶段 3——仅根据扫描摘要进入阶段 4。告知用户：

“所有 7 个视角的结果均为绿色。无需深入分析——将根据扫描结果继续进行评估。”

步骤 2：调度深入分析 Agent

在一条消息中调度所有已标记视角的 Agent（并行执行）。每个已标记视角对应一个 Agent(model: "sonnet")。

针对每个已标记的视角，根据下方的视角标准和该视角的扫描数据构建提示词。

Agent(model: "sonnet", description: "Deep dive: {lens_name} analysis of {SLUG}")

每个深入分析 Agent 的提示词都必须完全自包含：

You are an architectural analyst performing a deep dive on a specific
structural dimension of a codebase. A broad sweep has already identified
this area as needing investigation. Your job is to produce detailed,
actionable findings.

## Project

- **Root:** {ROOT}
- **Framework:** {FRAMEWORK}
- **Philosophy:** {PHILOSOPHY}
- **Full config:** {CONFIG}

## Your Lens: {LENS_DISPLAY_NAME}

### What the sweep found

- **Health:** {sweep_health}
- **Notes:** {sweep_notes}
- **Key files to start with:** {sweep_file_pointers}

### What to look for

{lens_criteria}

## Analysis Instructions

1. Start with the file_pointers from the sweep — these are your leads
2. Follow the dependency graph outward — what do these files import? What
   imports them?
3. Read the actual code, not just directory listings. You need to see
   implementations to judge quality.
4. Compare against the project's stated philosophy: {PHILOSOPHY}
5. Check for patterns — one instance isn't a finding, repeated instances are

## Output Format

Return your findings as a structured list. Each finding MUST follow this
exact format:

```
Finding: <concise title>
Severity: Low | Medium | High | Critical
Location: <file path(s) — be specific>
What: <description of what you found>
Why it matters: <impact on maintainability, scalability, or developer experience>
Recommendation: <specific, actionable suggestion — not vague advice>
```

Severity definitions:
- **Critical** — actively causing problems now, blocking team velocity, or
  creating risk of bugs/outages. Fix soon.
- **High** — significant structural issue that will compound over time.
  Should be planned.
- **Medium** — real issue but manageable. Worth addressing when touching
  the area.
- **Low** — minor improvement. Address opportunistically.

Be specific. "Consider refactoring" is not a recommendation. "Extract the
fee calculation from MemberPayment into a FeeCalculator service — it's
duplicated in 3 models" is.

If the sweep flagged this lens but your deep analysis finds it's actually
fine, say so. Return an empty findings list with a note explaining why
the flag was a false alarm.

Return ONLY the findings in the format above, no surrounding text. If there
are no findings, return: "No findings — sweep flag was a false positive."

各视角的评估标准

为每个视角使用相应的标准块：

结构组织：

- Directory layout: is it by layer (models/, views/, controllers/) or by
  feature (payments/, members/, dispatch/)? Is it consistent?
- File grouping: are related files co-located or scattered?
- Naming: do file names follow a consistent convention? Do they match
  their contents?
- Separation of concerns: is presentation logic in models? Business logic
  in controllers? Framework plumbing in domain code?
- Dead directories: folders with stale or unused code

设计模式：

- Identify all GoF patterns in use: adapter, strategy, facade, observer,
  factory, decorator, command, etc.
- For each: is it applied correctly? Does it reduce complexity or add it?
- Look for missing patterns: places where a Strategy would eliminate a
  case statement, where an Adapter would decouple a dependency, where a
  Facade would simplify a complex subsystem
- Look for over-patterning: unnecessary indirection, AbstractFactoryFactory
  syndrome, patterns that add layers without adding value

组合与继承：

- Map inheritance hierarchies. Flag any deeper than 3 levels.
- Check for "inheritance for code sharing" — should these be modules/mixins/
  composables instead?
- Count mixins/concerns per class. Flag classes with 5+ includes/extends.
- Look for fragmented behavior — where understanding a class requires reading
  8 different concern files
- Check for composition patterns: dependency injection, strategy objects,
  decorator chains

耦合与内聚：

- Map module dependencies — which modules/classes reference each other?
- Look for circular dependencies between modules
- Identify god objects: classes with 10+ public methods, 300+ lines, or
  that are imported everywhere
- Check boundary clarity: could you extract a module into a gem/package
  without touching 20 other files?
- Look for feature envy: methods that use more of another class's data
  than their own
- Check for law of demeter violations: long method chains (a.b.c.d)

框架适配：

- Check convention adherence for the specific framework
- Rails: callbacks doing business logic? N+1 queries? SQL in views?
  skip_before_action sprawl? Models as god objects?
- Vue/Nuxt: mutating props? Giant computed properties? Business logic in
  components instead of composables? v-if/v-for on same element?
- General: are framework-provided solutions being used, or is the team
  building custom versions of built-in features?
- Are there framework anti-patterns that the community has identified?

API 与接口设计：

- Check internal API consistency: do similar operations have similar
  method signatures?
- Look at method arity: methods with 4+ positional parameters are a flag
- Check for boolean parameters that should be separate methods or enums
- Public surface area: are classes exposing methods that should be private?
- Look for inconsistent return types: same kind of method returning
  different shapes in different classes
- Check service object interfaces: do they follow a consistent pattern
  (call/execute/perform)?

重复与复用：

- Search for copy-paste code: similar logic in multiple files
- Check for inconsistent approaches: the same problem (e.g., date formatting,
  error handling, validation) solved differently in different places
- Identify extraction candidates: code that appears 3+ times and should be
  a shared utility/concern/composable
- Check for "almost the same" code: slight variations that could be unified
  with a parameter

第 3 步：收集结果

等待所有深度分析 Agent 完成。对于每个 Agent：

• **成功：**解析响应中的发现
• **失败：**将该视角标记为未完成： "Deep analysis incomplete for {lens_name} — re-run to retry."

如果一个 Agent 失败，不要让整个技能失败。使用部分结果继续处理。 用户可以重新运行，以重试失败的视角。

第 4 步：合并结果

构建一个合并后的发现对象，其中包含：

• 扫描摘要（全部 7 个视角及其健康评级）
• 每次深度分析的详细发现
• 标记为未完成的视角

将此合并结果存储起来，供第 4 阶段使用。这会保存在内存中——第 4 阶段会将其整理为评估产物。

---

第 4 阶段：评估 — 呈现发现并生成产物

此阶段在主对话中运行（而不是子 Agent），因为需要与用户进行来回讨论。深度分析结果作为输入，评估产物作为输出。

第 1 步：合并深度分析结果

将所有深度分析 Agent 的发现合并为统一视图，按视角组织。纳入扫描中健康评级为绿色的视角（这些视角没有发现，但其健康评级会显示在摘要表中）。

第 2 步：检查现有评估

CONFIG=$("$ARCHITECT" config "$SLUG")
ARTIFACT_PATH=$(echo "$CONFIG" | jq -r '.artifact_path')

检查 $ROOT/$ARTIFACT_PATH 是否已存在。如果存在，则这是一次重新运行：

1. 读取现有产物
2. 原样保留行动计划部分（此内容由用户撰写）
3. 加载之前的扫描结果以进行差异比较：

   LAST_SWEEP=$("$ARCHITECT" last-sweep "$SLUG")
   

4. 将当前发现与上次扫描结果进行比较：
   • 新发现——当前结果中存在、但上次扫描结果中不存在
   • 已解决的发现——上次扫描结果中存在、但当前结果中不存在；在产物中标记为 [RESOLVED]（追加到发现标题后）
   • 未变化的发现——两次结果中都存在；保持不变
5. 在呈现完整摘要之前，先向用户说明差异：

   "This is a re-run. Since the last assessment: N new findings, N resolved, N unchanged."

如果不存在现有产物，则按全新评估继续。

第 3 步：呈现发现

向用户呈现发现，首先给出执行摘要：

1. 总体健康评估——一句话结论
2. 主要优势——表现良好的方面（引用具体视角／模式）
3. 主要问题——需要关注的方面（引用具体发现）
4. 发现数量——按严重程度统计发现总数（Critical：N，High：N， Medium：N，Low：N）
5. 视角健康状况表：

| Lens | Health |
|------|--------|
| Structural Organization | Good / Needs Attention / Significant Concerns |
| Design Patterns | ... |
| Composition & Inheritance | ... |
| Coupling & Cohesion | ... |
| Framework Alignment | ... |
| API & Interface Design | ... |
| Duplication & Reuse | ... |

扫描评级与健康状况的对应关系：

• green → 良好
• yellow → 需要关注
• red → 存在重大问题

然后按视角分组呈现详细发现——每项发现均包含严重程度、位置、描述、影响和建议。

第 4 步：讨论

呈现发现后，暂停并等待用户输入。在用户有机会进行以下操作之前，不要继续提出建议：

• 询问具体发现
• 对自己有异议的发现提出质疑
• 补充你可能遗漏的背景信息
• 根据业务实际情况调整优先级

这是一次对话，而不是信息倾倒。等待用户表示对这些发现感到满意后，再继续。

步骤 5：制定优先级建议

讨论结束后，将所有建议分为三个级别：

• 快速见效项——耗时数小时、风险低、能显著提升清晰度。这些事项应当是有人本周就能着手完成的工作。
• 中等工作量——耗时数天至一周，需要适度重构。可能需要协调，或会影响多个文件／模块。
• 战略性重构——耗时数周至数月，需要分阶段推进。这些是较大的架构调整，需要制定计划。

每个级别内按影响程度排序（从高到低）。

步骤 6：生成评估文档

使用以下模板构建文档。将其写入 $ROOT/$ARTIFACT_PATH。

评估文档模板

# Architecture Assessment — <Project Name>
Generated: YYYY-MM-DD | Framework: Rails 8.x / Nuxt 4.x / etc.

## Summary
2-3 paragraph executive overview. Overall health, biggest strengths,
biggest concerns.

## Findings by Lens

### <Lens Name>
**Health: Good / Needs Attention / Significant Concerns**

#### Finding: <title>
- **Severity:** Low / Medium / High / Critical
- **Location:** app/services/, app/models/
- **What:** Description of what was found
- **Why it matters:** Impact on maintainability, velocity, correctness
- **Recommendation:** What to do about it

(repeat per finding, per lens)

## Prioritized Recommendations
Ordered list grouped into:
- **Quick wins** — hours, low risk, high clarity improvement
- **Medium efforts** — days to a week, moderate restructuring
- **Strategic restructuring** — weeks to months, phased approach needed

## Action Plan
Empty until the user decides what to act on. Populated during Phase 5
with phased implementation strategies. Updated as phases complete.

模板说明：

• 从配置中填写 <Project Name>、日期和框架
• 根据步骤 3 中给出的执行摘要填写 Summary
• 根据合并后的深入分析结果填写 Findings by Lens
• 根据步骤 5 填写 Prioritized Recommendations
• 首次运行时将 Action Plan 留空；重新运行时保留其内容
• 已解决的问题应在问题标题末尾追加 [RESOLVED]，例如：#### Finding: God object in User model [RESOLVED]
• 包含所有视角（即使是绿色视角）——绿色视角应有一行健康状况说明，但其下不应有问题

步骤 7：提交文档

cd "$ROOT"
git add "$ARTIFACT_PATH"
git commit -m "docs: architecture assessment — $(date +%Y-%m-%d)"
git push

告诉用户文档提交到了哪里。

步骤 8：更新状态

解析已提交的文档并更新项目状态：

PARSED=$("$ARCHITECT" parse-artifact "$SLUG")
FINDINGS_TOTAL=$(echo "$PARSED" | jq -r '.findings_total')
FINDINGS_RESOLVED=$(echo "$PARSED" | jq -r '.findings_resolved')
PLAN_PHASES=$(echo "$PARSED" | jq -r '.action_plan_phases')
PLAN_COMPLETED=$(echo "$PARSED" | jq -r '.action_plan_completed')

"$ARCHITECT" update-state "$SLUG" \
  last_full_run="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  findings_total="$FINDINGS_TOTAL" \
  findings_resolved="$FINDINGS_RESOLVED" \
  action_plan_phases="$PLAN_PHASES" \
  action_plan_completed="$PLAN_COMPLETED"

---

阶段 5：规划 — 分阶段实施策略

此阶段采用对话式方式（在主对话中进行，而非子 Agent）。按需运行——当用户决定着手处理发现的问题时运行，可以是在评估对话期间，也可以是在之后的会话中。

步骤 1：加载评估

CONFIG=$("$ARCHITECT" config "$SLUG")
ARTIFACT_PATH=$(echo "$CONFIG" | jq -r '.artifact_path')

读取 $ROOT/$ARTIFACT_PATH 中现有的评估文档。如果该文档不存在，请告知用户：“未找到评估。请先运行 /architect 生成评估。”然后停止。

步骤 2：询问要处理的事项

向用户展示当前发现的问题和优先级建议，然后询问他们想处理哪些内容：

“以下是当前发现的问题和建议。你想规划处理哪些内容？可以选择单个问题、一个建议级别（例如‘所有快速见效项’），或多个选项的组合。”

等待用户回答。

步骤 3：界定每个选项的范围

针对每个选定的项目，讨论：

• 变更范围——会影响哪些文件、模块或层？
• 风险级别——这是安全的重命名／提取，还是会改变行为？可能导致测试失败吗？会影响公共 API 吗？
• 对其他变更的依赖——这项工作需要在其他计划的变更之前还是之后进行？
• 预估工作量——需要数小时、数天还是数周？将测试更新也考虑在内。

这是一个对话过程——与用户逐项讨论。不要直接给出计划后就结束。随着讨论进行，用户可能会调整优先级、推迟某些事项，或合并相关变更。

步骤 4：制定行动计划

用户对范围界定满意后，在文档的 ## Action Plan 部分制定分阶段计划。每个阶段将可以一起完成的相关变更归为一组：

## Action Plan

### Phase 1: <title> [NOT STARTED]
**Target findings:** Finding X, Finding Y
**Scope:** <description of what changes and where>
**Risk:** Low / Medium / High
**Estimated effort:** <timeframe>
**Dependencies:** None / Phase N must complete first

### Phase 2: <title> [NOT STARTED]
**Target findings:** Finding Z
**Scope:** <description>
**Risk:** <level>
**Estimated effort:** <timeframe>
**Dependencies:** <if any>

阶段状态：

• [NOT STARTED]——已规划但尚未开始
• [IN PROGRESS]——工作已开始（阶段 6 启动时设置）
• [COMPLETE]——已完成并验证

**排序：**将快速见效项和低风险阶段放在前面。战略性重构放在最后。遵循依赖顺序——如果阶段 3 依赖阶段 1，阶段 1 必须排在前面。

步骤 5：提交更新后的文档

cd "$ROOT"
git add "$ARTIFACT_PATH"
git commit -m "docs: architecture action plan — $(date +%Y-%m-%d)"
git push

告诉用户：“行动计划已提交。使用 /architect 执行各个阶段，并告诉我执行哪个阶段。”

步骤 6：更新状态

解析已提交的文档并更新项目状态：

PARSED=$("$ARCHITECT" parse-artifact "$SLUG")
FINDINGS_TOTAL=$(echo "$PARSED" | jq -r '.findings_total')
FINDINGS_RESOLVED=$(echo "$PARSED" | jq -r '.findings_resolved')
PLAN_PHASES=$(echo "$PARSED" | jq -r '.action_plan_phases')
PLAN_COMPLETED=$(echo "$PARSED" | jq -r '.action_plan_completed')

"$ARCHITECT" update-state "$SLUG" \
  action_plan_phases="$PLAN_PHASES" \
  action_plan_completed="$PLAN_COMPLETED" \
  findings_total="$FINDINGS_TOTAL" \
  findings_resolved="$FINDINGS_RESOLVED"

---

阶段 6：执行 — 调用编写计划以重构

此阶段按需运行——用户会明确触发，例如说“我们来处理阶段 1”或“执行快速见效项”。它绝不会自动运行。

步骤 1：确定目标阶段

阅读评估产物。找到用户提到的阶段。如果该阶段状态为 [COMPLETE]，告知用户该阶段已完成，并询问是否要重新运行。

在产物中将目标阶段标记为 [IN PROGRESS]。

步骤 2：收集上下文

从产物中收集：

• 阶段标题和范围描述
• 该阶段要处理的目标发现（完整的发现详情：位置、问题、重要性、建议）
• 任何依赖项——确认前置阶段均为 [COMPLETE]

如果某个依赖项尚未完成，提醒用户：

“阶段 N 依赖阶段 M，而阶段 M 仍为 [NOT STARTED]。你想继续执行，还是先处理阶段 M？”

等待确认。

步骤 3：调用编写计划

调用 superpowers:writing-plans 技能，为该阶段创建详细的实施计划：

/superpowers:writing-plans

向该技能提供：

• 目标： 行动计划中的阶段标题和范围
• 上下文： 此阶段针对的每项发现的完整详情（位置、问题、重要性、建议）
• 项目根目录： $ROOT
• 框架和理念： 来自架构师配置

编写计划技能会处理其余事项——任务拆分、TDD、执行。

步骤 4：执行后更新产物

执行完成后：

1. 在行动计划中将阶段标记为 [COMPLETE]：

   ### Phase 1: <title> [COMPLETE]
   

2. 在每项已解决发现的标题后追加 [RESOLVED]：

   #### Finding: God object in User model [RESOLVED]
   

   仅当执行确实处理了相关问题时，才将发现标记为已解决。 如果某项发现只得到部分处理，则不要标记，并添加备注。

3. 提交更新后的产物：

   cd "$ROOT"
   git add "$ARTIFACT_PATH"
   git commit -m "docs: architecture phase complete — <phase title>"
   git push
   

步骤 5：更新状态

PARSED=$("$ARCHITECT" parse-artifact "$SLUG")
FINDINGS_TOTAL=$(echo "$PARSED" | jq -r '.findings_total')
FINDINGS_RESOLVED=$(echo "$PARSED" | jq -r '.findings_resolved')
PLAN_PHASES=$(echo "$PARSED" | jq -r '.action_plan_phases')
PLAN_COMPLETED=$(echo "$PARSED" | jq -r '.action_plan_completed')

"$ARCHITECT" update-state "$SLUG" \
  action_plan_phases="$PLAN_PHASES" \
  action_plan_completed="$PLAN_COMPLETED" \
  findings_total="$FINDINGS_TOTAL" \
  findings_resolved="$FINDINGS_RESOLVED"

告知用户已完成的事项和剩余工作：

“阶段 1 已完成。已解决 N 项发现。行动计划中还剩 M 个阶段。”

---

定向调用 — /architect <target>

用户使用目标调用 /architect 时（例如 /architect app/models 或 /architect the dispatch system），本次运行将限定在该子系统内。

范围限定的工作方式

目标处理已内置于现有阶段中：

1. 传授（Teach） — 如有需要则正常运行（相关理念适用于整个项目）
2. 扫描（Sweep，阶段 2，步骤 2） — 范围检测已支持目标：
   • 路径目标（app/models、src/features/dispatch）会将扫描范围限定在相应目录树内
   • 概念目标（“the dispatch system”）会指示扫描 Agent 先识别相关文件，再限定范围
3. 深入分析（Deep Dive，阶段 3） — Agent 会接收扫描提供的限定范围文件指针，因此会自然聚焦于目标区域
4. 评估（Assess，阶段 4） — 仅针对目标范围生成发现

合并到主产物

定向运行的主要区别在于结果如何合并到评估产物中：

如果评估产物已存在：

1. 阅读现有产物
2. 对每个分析视角，将新发现与现有发现合并：
   • 目标范围内的新发现 — 附加到相应的分析视角部分。为清楚起见，在发现标题前加上范围，例如： #### Finding: User 模型中的 God 对象 (app/models)
   • 目标范围外的现有发现 — 保持不变
   • 目标范围内的现有发现 — 替换为新结果（本次新分析将取代该区域的旧分析）
3. 重新进行优先级排序：将新发现整合到现有建议层级中
4. 原样保留行动计划部分——定向运行不会修改现有计划

如果不存在评估产物：

使用标准模板创建新产物。在摘要中注明本次评估仅涵盖目标区域：

## Summary
This assessment covers **<target description>** only, not the full codebase.
Run `/architect` without a target for a complete assessment.

工件提交

与阶段 4、第 7 步相同：

cd "$ROOT"
git add "$ARTIFACT_PATH"
git commit -m "docs: architecture assessment — <target> — $(date +%Y-%m-%d)"
git push

状态更新

与阶段 4、第 8 步相同——解析工件并更新状态。状态 会跟踪所有运行（完整运行和定向运行）的汇总结果。