architect-implement

Name: architect-implement
Author: tikalk

github.com/tikalk开发143189 次安装今天更新

代码仓库

关于 architect-implement

该 skill 通过多 Agent DAG 工作流，将架构决策记录（ADR）整理为统一的架构说明文档 AD.md，适用于已批准决策后的系统架构文档编写。

主要功能

01分析 ADR 并识别子系统
02规划可定制的视图生成 DAG
03结合依赖上下文生成架构视图
04在视图生成过程中应用架构视角
05汇总视图并解决跨子系统冲突
06验证工作流状态和 ADR 状态

适用场景

01ADR 获批后编写架构文档
02新增决策后重新生成 AD.md
03生成部署或运维视图
04跨 Agent 会话恢复架构文档工作

安装

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

$npx skills add https://github.com/tikalk/adlc-team-skills --skill architect-implement

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

详细介绍

architect-implement

此技能的作用

采用多 Agent DAG 编排方法，根据架构决策记录（ADR）生成完整的架构描述（AD.md）：

规划 Agent：分析 ADR，识别子系统，生成定制 DAG，并征求用户批准。
执行 Agent：遵循 DAG，为每个子系统生成架构视图，并传递依赖上下文。
总结 Agent：汇总所有视图，解决跨子系统冲突，并生成统一的 AD.md。

关键见解：ADR 记录决策背后的原因；架构描述则记录这些决策所形成的系统形态。

适用场景

在 /architect-specify 或 /architect-clarify 之后：根据已讨论并接受的 ADR 生成 AD。
在 /architect-init 之后：记录棕地项目的架构。
ADR 更新：有新决策后重新生成 AD.md。
文档冲刺：创建全面的架构文档。

不适用场景

不存在 ADR：请先使用 /architect-specify 或 /architect-init。
功能级架构：功能 AD 会在该功能的规划阶段生成，而不是通过此技能生成。
小幅更新：小改动请直接编辑。

流程

用户输入

$ARGUMENTS

继续之前，必须考虑用户输入（如果不为空）。

用户输入示例：

"重点关注部署和运维视图——我们需要基础设施文档"
"生成所有视图，重点关注安全视角"
"根据近期决策中的新 ADR 更新现有 AD.md"
空输入：根据所有 ADR 生成完整的架构描述

标志

--views VIEWS：要生成的架构视图
- core（默认）：上下文、功能、信息、开发、部署（5 个核心视图）
- all：全部 7 个视图，包括并发和运维
- 自定义：逗号分隔（例如，concurrency,operational）——始终包含核心视图
--sequential（默认）：按顺序执行视图，以获得最高质量
- 建议使用：可在功能视图之后设置检查点
--parallel：在依赖链允许的情况下并行执行
- 警告：可能降低跨视图的一致性；仅在时间紧迫时使用
--no-checkpoint：跳过功能视图检查点（不建议）
- 警告：功能视图是塑造其他所有视图的“基石”
--force：绕过工作流状态验证（仅用于紧急情况）
- 警告：仅在了解风险时使用
- 跳过澄清阶段 5.5 的完成检查
- 跳过飞行前 ADR 状态验证
- 可能导致架构不完整或不一致

重要：当 --views 为 core（默认值）时，完全跳过并发视图（3.4）和运维视图（3.7）。仅在通过 --views all 或 --views concurrency,operational 明确请求时才生成这两个视图。

与 Rozanski & Woods 方法论保持一致

此命令实现了 Nick Rozanski 和 Eoin Woods 在 Software Systems Architecture（第 2 版）中提出的视点与视角框架。

核心原则

功能视图是基石

“功能视图是大多数 AD 的基石……它通常决定其他系统结构的形态，例如信息结构、并发结构、部署结构等。” — Rozanski & Woods
视图彼此关联，并非相互独立

“在一个视图中做出的决策可能会对其他视图产生重大影响；架构师的重要职责之一，就是确保这些影响得到理解。”
视角应用于视图

“你不会孤立地使用视角，而是将其与各个视图结合，用于分析和验证架构的质量。”
质量优先于速度 架构错误的修复成本很高。默认按顺序执行并设置检查点，以确保质量。

视点依赖图

                    ┌──────────┐
                    │ Context  │  (System boundaries)
                    └────┬─────┘
                         │
                         ▼
                 ┌───────────────┐
                 │  FUNCTIONAL   │  ★ CORNERSTONE ★
                 │  (Drives all  │  USER CHECKPOINT
                 │   other views)│  REQUIRED HERE
                 └───────┬───────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
   ┌───────────┐   ┌───────────┐   ┌───────────┐
   │Information│   │Concurrency│   │Development│
   │           │   │(optional) │   │           │
   └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
         │               │               │
         └───────────────┼───────────────┘
                         │
                         ▼
                  ┌────────────┐
                  │ Deployment │
                  └──────┬─────┘
                         │
                         ▼
                  ┌────────────┐
                  │ Operational│  (optional)
                  └────────────┘

动态视点与视角选择

根据系统特征动态选择视点和视角：

类别	始终包含	自动检测（可选）
视点	上下文、功能	信息、并发、开发、部署、运维
视角	安全、性能	无障碍、可用性、演进、国际化、位置、法规、可用性、开发资源

参考：https://www.viewpoints-and-perspectives.info/

目标

采用多 Agent DAG 编排方法，将架构决策记录（ADR）转换为全面的架构描述（AD.md）：

规划 Agent：分析 ADR，检测子系统，生成定制的 DAG，并征求用户批准
执行 Agent：遵循 DAG 为每个子系统生成视图，并提供依赖上下文
汇总 Agent：汇总所有视图，解决冲突，生成统一的 AD.md

角色与上下文

你将担任架构编排器，负责管理多阶段文档生成工作流。你的职责包括：

根据子系统分析规划生成 DAG
按正确的依赖顺序执行视图生成
将视图汇总为统一的架构描述
持久化状态，以便在 AI Agent 会话之间恢复

架构文档层级

文档	用途	位置
`{REPO_ROOT}/.adlc/drafts/adr/`	记录架构决策及其理由（单独文件格式）	输入
`{REPO_ROOT}/.adlc/architect/state.json`	DAG 执行状态	状态
`{REPO_ROOT}/docs/adlc/architect/views/{subsystem}/{view}.md`	每个视图的输出	参考
`{REPO_ROOT}/docs/adlc/architect/AD.md`	完整架构描述	输出
`{REPO_ROOT}/docs/adlc/memory/constitution.md`（旧版 `.adlc/memory/constitution.md` 回退路径）	治理原则	约束

重要 - 路径解析：

设置脚本会输出 REPO_ROOT，请用它来确定正确的路径
通过从当前目录向上搜索 .adlc 目录来找到 REPO_ROOT
切勿使用 .adlc/drafts/adr.md 这样的相对路径；始终使用 {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md
设置脚本会从 adr/ 目录读取单独的 ADR 文件
从子目录（例如子项目目录）运行时，.adlc 可能位于父目录中

视图模板

位于该技能的 templates/ 目录中：

模板	用途
`templates/views/context.md`	上下文视图模板
`templates/views/functional.md`	功能视图模板
`templates/views/information.md`	信息视图模板
`templates/views/concurrency.md`	并发视图模板（可选）
`templates/views/development.md`	开发视图模板
`templates/views/deployment.md`	部署视图模板
`templates/views/operational.md`	运维视图模板（可选）

视角模板（共 10 个）
`templates/perspectives/security.md`
`templates/perspectives/performance.md`
`templates/perspectives/accessibility.md`
`templates/perspectives/availability.md`
`templates/perspectives/evolution.md`
`templates/perspectives/internationalization.md`
`templates/perspectives/location.md`
`templates/perspectives/regulation.md`
`templates/perspectives/usability.md`
`templates/perspectives/development-resource.md`

三阶段 DAG 工作流

┌─────────────────────────────────────────────────────────────────────────────┐
│                          PHASE 1: PLAN                                      │
│  ┌─────────────┐    ┌─────────────────┐    ┌─────────────────────────────┐ │
│  │ Load ADRs   │───▶│ Detect Sub-     │───▶│ Generate DAG per Sub-system │ │
│  │             │    │ systems         │    │ (apply customization rules) │ │
│  └─────────────┘    └─────────────────┘    └──────────────┬──────────────┘ │
│                                                           │                 │
│                                            ┌──────────────▼──────────────┐ │
│                                            │ Present Plan for Approval   │ │
│                                            │ (user confirms or modifies) │ │
│                                            └──────────────┬──────────────┘ │
│                                                           │                 │
│                                            ┌──────────────▼──────────────┐ │
│                                            │ Write state.json            │ │
│                                            └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          PHASE 2: EXECUTE                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  For each sub-system, execute DAG in topological order:             │   │
│  │                                                                      │   │
│  │  ┌─────────┐    ┌────────────┐    ┌─────────────┐    ┌───────────┐ │   │
│  │  │ Context │───▶│ Functional │───▶│ Information │───▶│Development│ │   │
│  │  └─────────┘    └────────────┘    └─────────────┘    └───────────┘ │   │
│  │                        │                                    │       │   │
│  │                        ▼                                    ▼       │   │
│  │               ┌─────────────┐                      ┌────────────┐  │   │
│  │               │ Concurrency │                      │ Deployment │  │   │
│  │               │ (optional)  │                      └────────────┘  │   │
│  │               └─────────────┘                             │        │   │
│  │                                                           ▼        │   │
│  │                                                   ┌─────────────┐  │   │
│  │                                                   │ Operational │  │   │
│  │                                                   │ (optional)  │  │   │
│  │                                                   └─────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  Each view: Read dependencies → Generate content (with perspectives inline)
│             → Update state.json with progress                               │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          PHASE 3: SUMMARIZE                                 │
│  ┌──────────────────┐    ┌─────────────────────┐    ┌──────────────────┐   │
│  │ Read all view    │───▶│ Detect cross-       │───▶│ Resolve conflicts│   │
│  │ files            │    │ subsystem conflicts │    │ using ADRs       │   │
│  └──────────────────┘    └─────────────────────┘    └────────┬─────────┘   │
│                                                               │             │
│  ┌──────────────────┐                       ┌──────────────▼───────────┐ │
│  │ Move Accepted    │◀─────────────────────────│ Aggregate into            │ │
│  │ ADRs to memory   │                         │ unified AD.md (views include│ │
│  └──────────────────┘                         │ perspective sections)     │ │
│                                             └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

注意：现在会在第 2 阶段生成视图期间应用视角（安全、性能等），而不是将其作为第 3 阶段的独立步骤。这遵循 R&W 原则：“将其用于每个视图，以分析并验证架构的质量属性。”

预检验证（强制 — 严格执行）

重要：这些验证将严格执行。如果检查失败，执行将停止。仅在紧急情况下且充分了解风险后，才使用 --force 标志。

开始第 1 阶段前，必须验证先决条件：

工作流状态检查（除非使用 --force）

检查 state.json 中的 clarify 完成状态：

加载 {REPO_ROOT}/.adlc/architect/state.json
检查 workflow.clarify_completed 字段

如果为 false 或缺失：

❌ 工作流验证失败

implement 命令要求先通过 /architect-clarify 批准 ADR。

当前工作流状态：clarify_completed = false

要求：运行 /architect-clarify 并完成第 5.5 阶段（ADR 批准）

选项：
1. 运行 /architect-clarify 批准 ADR
2. 使用 --force 绕过（不推荐 — 可能导致架构不一致）

⚠️  使用 --force 会跳过重要的验证步骤，可能导致：
   - 处理未获批准的 ADR
   - 遗漏关键架构决策
   - 架构文档不完整

停止执行（除非提供了 --force 标志）

ADR 状态检查

检查 ADR 是否存在：验证 {REPO_ROOT}/.adlc/drafts/adr/ 或 {REPO_ROOT}/docs/adlc/memory/adr/（回退到旧版 {REPO_ROOT}/.adlc/memory/adr/）是否存在（单文件格式）
检查是否有已接受的 ADR：统计状态为 "Accepted" 的 ADR 数量
- 如果没有已接受的 ADR：停止并输出：
```
❌ 无法继续：未找到状态为 Accepted 的 ADR

implement 命令要求 ADR 的状态为 "Accepted"。
当前 ADR 状态：[列出找到的状态]

请先运行 /architect-clarify 审查并批准 ADR。
```
- 如果至少有 1 个已接受的 ADR：继续并报告：“✓ 找到 N 个状态为 Accepted 的 ADR”

强制执行约束

关键——请在继续之前阅读

以下约束均为强制要求。违反任何一项约束都会导致输出无效，必须重新开始。

约束 1：视图文件必须写入磁盘

在继续处理下一个视图之前，必须先将每个视图分别写入磁盘。位置：{REPO_ROOT}/docs/adlc/architect/views/{subsystem}/{view}.md

不要将视图保留在内存中，只写入 AD.md

不要通过一次写入操作合并多个视图

每个文件都必须可读且独立完整

内容至少为 20 行，并包含规范的章节标题

约束 2：每个视图完成后都必须更新状态

必须在每个视图文件写入磁盘并确认可读后，立即更新 state.json，然后才能开始处理 DAG 中的下一个视图。不要按子系统或阶段批量更新。只有在文件已存在于磁盘且已通过回读验证后，才能将每个视图的进度标记为 "completed"。

约束 3：必须在功能视图处设置检查点

功能视图完成后，必须暂停并等待用户检查点确认（除非使用 --no-checkpoint）。不要在未提示的情况下继续。请提供 A/B/C/D 检查点选项并等待回复。功能视图是“基石”，必须获得用户批准。

约束 4：阶段标记为 "completed" 前必须完成验证

在以下各项完成之前，不得在 state.json 中将阶段标记为 "completed"：

所有视图文件都已存在于磁盘上（逐一回读验证）

已写入 AD.md，且内容汇总自视图文件

已执行草稿清理并完成验证

已输出最终验证表（10 项检查）

约束 5：AD.md 内容必须来自视图文件

不得直接根据 ADR 编写 AD.md。AD.md 的内容必须来自读取生成的视图文件。流程必须严格遵循： ADR → 视图（磁盘上的文件）→ AD.md（由视图汇总而成）

约束 6：第 3 阶段必须从磁盘读取

在第 3 阶段，必须从磁盘读取视图文件，不能使用内存中的内容。请使用文件读取操作，以确保流程可恢复且可审计。如果无法读取某个视图文件，请停止并报告错误。

约束 7：视图必须属于子系统 DAG

不得生成未列入 state.json 中该子系统 dag 数组的视图。在生成任何视图之前，先检查 DAG。如果视图不在其中，请在 state.json 中将其标记为 skipped 并继续。在 DAG 之外生成视图会产生孤立文件，并使架构无效。

约束 8：AD.md 必须按视点组织

AD.md 必须按视点组织（§3.1 上下文、§3.2 功能、§3.3 信息等），不得按子系统组织。每个视点章节都应呈现整合所有子系统内容后的系统级统一视角。子系统专属详情可通过“子系统详情”链接访问（参见步骤 3.5）。

错误（按子系统组织——这是子系统视图文件的用途）： ## 5. 子系统：Auth → ### 5.1 上下文 → ### 5.2 功能

正确（按视点组织——整合所有子系统）： ## 3. 架构视图 → ### 3.1 上下文视图 → ### 3.2 功能视图

约束 9：图表必须使用 Mermaid 语法

所有架构图（包括视图文件和 AD.md 中的图表）必须使用 Mermaid 语法。ASCII 方框图（如 ┌、└、 ├、│、───、═══ 等字符）不得用于架构图。

接受的 Mermaid 图表类型：

graph TB/LR——架构、拓扑、流程图

erDiagram——数据模型和实体关系

sequenceDiagram——交互流程

flowchart——流程图

目录树（代码组织结构）可以使用普通的 text 代码块；这不属于架构图。

阶段 1：规划（规划 Agent）

目标：分析 ADR、检测子系统、生成定制 DAG，并获得用户批准

脚本操作：运行 {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh（需要 architect-clarify 技能：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。该脚本在内部调用 plan-dag

步骤 1.1：加载并分析 ADR

读取 ADR 目录：从 {REPO_ROOT}/.adlc/drafts/adr/ 加载 ADR（如果 drafts 为空，则检查 {REPO_ROOT}/docs/adlc/memory/adr/ 或旧版 {REPO_ROOT}/.adlc/memory/adr/）
解析 ADR 索引：从 {REPO_ROOT}/.adlc/drafts/adr/adr.md 或单个 ADR 文件中提取子系统
按子系统分组 ADR：创建子系统 → ADR 的映射

验证 ADR 状态（必须）：

按状态统计 ADR：已接受 / 提议中 / 已发现

如果已接受的 ADR 数量为零：停止执行并输出错误：

❌ 阶段 1 已阻止：没有已接受的 ADR

发现：[N] 个提议中、[M] 个已发现、[0] 个已接受

implement 命令仅处理“已接受”的 ADR。
在实现之前，请运行 /architect-clarify 批准 ADR。

向用户报告：“✓ 找到 [N] 个可供实现的已接受 ADR”

ADR 索引表格格式：

| ID | Sub-System | Decision | Status | Date | Owner |
|----|------------|----------|--------|------|-------|
| ADR-001 | Core | Microservices architecture | Accepted | 2024-01-15 | @architect |
| ADR-002 | Auth | OAuth2 with PKCE | Accepted | 2024-01-16 | @security |
| ADR-003 | Data | PostgreSQL primary store | Accepted | 2024-01-17 | @data |

步骤 1.2：检测子系统及其特征

针对每个子系统，分析 ADR 以检测：

特征	检测模式	DAG 定制
无服务器	Lambda、Functions、serverless	优先展示部署视图
事件驱动	Events、messaging、async、Kafka、RabbitMQ	包含并发视图
数据密集型	Analytics、ETL、data pipeline	信息视图优先
API 优先	REST、GraphQL、OpenAPI	功能视图优先
多区域	Global、multi-region、geo	部署 + 运维

步骤 1.3：为每个子系统生成定制 DAG

默认 DAG（核心视图）：

Context → Functional → Information → Development → Deployment

扩展 DAG（所有视图）：

Context → Functional → Information ──┬─→ Development → Deployment → Operational
                                     └─→ Concurrency ─────────────────┘

DAG 定制规则：

检测到的模式	DAG 修改
无服务器	将部署置于开发之前
事件驱动	在信息之后添加并发
数据密集型	信息在上下文之后具有最高优先级
微服务	添加并发，扩展功能
单体	简化功能，跳过并发

步骤 1.4：提交计划供用户批准

强制执行子系统数量阈值（必须）：无论 /architect-specify 之前是否已获得批准，在提交 DAG 计划之前，都必须 应用以下规则：

子系统数量	必需操作
1–3	提交计划；允许自动批准
4–6	必须征求用户确认——未经明确批准不得继续
>6	必须建议分组，并且必须征求确认

重要：/architect-specify（阶段 0）的批准不能替代 DAG 执行计划的批准。用户必须独立确认每个子系统的 DAG 计划。

向用户提交执行计划：

## DAG Execution Plan

**Sub-systems detected**: 3
**Total views to generate**: 15 (5 views × 3 sub-systems)

### Sub-system: Core
**ADRs**: ADR-001, ADR-005, ADR-008
**Characteristics**: Microservices, Event-driven
**DAG**: Context → Functional → Information → Concurrency → Development → Deployment

### Sub-system: Auth
**ADRs**: ADR-002, ADR-006
**Characteristics**: API-first
**DAG**: Context → Functional → Information → Development → Deployment

### Sub-system: Data
**ADRs**: ADR-003, ADR-004, ADR-007
**Characteristics**: Data-intensive
**DAG**: Context → Information → Functional → Development → Deployment

---

**Approve this plan?** [Yes/Modify/Cancel]

步骤 1.5：写入 state.json

用户批准后，将执行计划写入 {REPO_ROOT}/.adlc/architect/state.json：

{
  "version": "1.1.0",
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T10:30:00Z",
  "phase": "plan_approved",
  "views_mode": "core",
  "workflow": {
    "clarify_completed": false,
    "clarify_completed_at": null,
    "adrs_approved_count": 0,
    "implement_started": false,
    "implement_started_at": null
  },
  "subsystems": [
    {
      "id": "core",
      "name": "Core",
      "adrs": ["ADR-001", "ADR-005", "ADR-008"],
      "characteristics": ["microservices", "event-driven"],
      "dag": ["context", "functional", "information", "concurrency", "development", "deployment"],
      "progress": {
        "context": "pending",
        "functional": "pending",
        "information": "pending",
        "concurrency": "pending",
        "development": "pending",
        "deployment": "pending"
      }
    },
    {
      "id": "auth",
      "name": "Auth",
      "adrs": ["ADR-002", "ADR-006"],
      "characteristics": ["api-first"],
      "dag": ["context", "functional", "information", "development", "deployment"],
      "progress": {
        "context": "pending",
        "functional": "pending",
        "information": "pending",
        "development": "pending",
        "deployment": "pending"
      }
    }
  ],
  "perspectives": ["security", "performance"],
  "output_file": "docs/adlc/architect/AD.md"
}

阶段 2：执行（执行 Agent）

目标：按照 DAG 为每个子系统生成视图，并传递依赖上下文

脚本操作：Agent 读取 state.json，并按 DAG 顺序执行视图

步骤 2.1：读取执行状态

加载 {REPO_ROOT}/.adlc/architect/state.json
确定接下来要生成的视图（所有依赖均已完成的视图）
加载当前子系统的相关 ADR

步骤 2.2：按 DAG 顺序生成视图

针对 DAG 中的每个视图：

检查 DAG 成员资格：确认该视图列在 state.json 中子系统的 dag 数组中。如果不存在 → 标记为 skipped，不要生成，继续处理下一个视图。
检查依赖项：确保所有依赖视图均已完成
加载依赖上下文：读取已完成的视图文件以获取上下文
加载视图模板：从 templates/views/{view}.md 读取
生成视图内容：填充模板，内容源自 ADR
写入视图文件：保存到 {REPO_ROOT}/docs/adlc/architect/views/{subsystem}/{view}.md
更新状态：在 state.json 中将视图标记为“completed”

结合依赖上下文生成视图：

## Generating: Functional View for "Core" sub-system

**Dependencies loaded**:
- Context View: {REPO_ROOT}/docs/adlc/architect/views/core/context.md (completed)

**ADRs for this view**: ADR-001 (Microservices), ADR-005 (API Gateway)

**Generating content...**

步骤 2.3：视图模板和占位符

每个视图模板都包含待填充的占位符：

占位符	替换内容
`[SUB_SYSTEM_NAME]`	state.json 中的子系统名称
`[ADR_IDS]`	以逗号分隔的 ADR ID
`[DATE]`	当前日期（YYYY-MM-DD）
`[ENTITY_N]`	从 ADR 中提取
`[COMPONENT_N]`	从 ADR 中提取

步骤 2.4：视图生成详情

上下文视图

目的：系统范围和外部交互（黑盒视图） 依赖项：无（DAG 中的第一个）模板：templates/views/context.md 主要内容：

系统范围说明
外部实体表（仅包含利益相关方和外部系统）
上下文图（将系统表示为一个黑盒）
外部依赖项表

功能视图（★ 基石 - 用户检查点）

目的：内部组件、职责和交互 依赖项：上下文视图模板：templates/views/functional.md 主要内容：

功能元素表
元素交互图
功能边界

重要：生成功能视图后，执行将暂停，等待用户批准。这是塑造所有后续视图的“基石”视图。

Rozanski & Woods：“功能视图是基石……它通常决定其他系统结构的形态。”

检查点选项：

A：批准 - 继续生成其余视图

B：修改 - 编辑功能视图，然后继续

C：重新开始 - 根据反馈重新生成

D：取消 - 停止执行

跳过检查点时（--no-checkpoint 标志）：生成时不暂停，但记录警告。

信息视图

目的：数据存储、管理和流动 依赖项：上下文视图、功能视图模板：templates/views/information.md 主要内容：

数据实体表
ER 图
数据流说明

并发视图（可选）

目的：运行时进程、线程和协调 依赖项：功能视图、信息视图模板：templates/views/concurrency.md 条件：仅当使用 --views all 或 --views concurrency 时生成 主要内容：

进程结构表
时序图
协调机制

开发视图

目的：代码组织、依赖项、CI/CD 依赖项：功能视图模板：templates/views/development.md 主要内容：

代码组织结构
模块依赖项
构建和 CI/CD 说明

部署视图

目的：物理环境、节点和网络 依赖项：开发视图模板：templates/views/deployment.md 主要内容：

运行时环境表
网络拓扑图
硬件要求

运维视图（可选）

目的：运维、支持和维护 依赖项：部署视图模板：templates/views/operational.md 条件：仅当使用 --views all 或 --views operational 时生成 主要内容：

运维职责
监控和告警
灾难恢复

步骤 2.5：更新 state.json 中的进度

WARNING：批量更新状态（例如，在某个子系统的所有视图完成后才更新）违反约束 2。每写入并验证一个视图文件后，都必须立即更新 state.json。

每生成一个视图后：

{
  "progress": {
    "context": "completed",
    "functional": "completed",
    "information": "in_progress",
    "development": "pending",
    "deployment": "pending"
  },
  "updated_at": "2024-01-20T11:15:00Z"
}

步骤 2.6：可恢复性

如果 Agent 会话中断：

下一次会话加载 state.json
找出状态为 "pending" 或 "in_progress" 的视图
从中断处继续
跳过已处于 "completed" 状态的视图

阶段 2→3 门槛：验证视图文件是否存在（MANDATORY）

进入阶段 3 前，必须验证所有预期的视图文件都存在于磁盘上：

对于 state.json 中的每个子系统，检查每个状态为 "completed" 的视图
验证文件是否存在：{REPO_ROOT}/docs/adlc/architect/views/{subsystem}/{view}.md
验证每个文件均可读取且包含最低限度的内容（≥20 行）
Mermaid 扫描（约束 9）：扫描每个视图文件，查找 ASCII 框线字符（┌、└、├、│、═、───）。如果任何应包含架构图（上下文、功能、信息、部署）的视图中出现这些字符，则标记为警告，并记录需要修正的文件。

验证清单（输出此表格）：

子系统	视图	文件路径	存在	可读	行数	Mermaid 正常
{subsystem}	{view}	{path}	✓/✗	✓/✗	{N}	✓/⚠

门槛判定：

如果所有检查均通过 → 进入阶段 3

如果有 Mermaid 警告 → 记录警告，但继续执行（不阻塞）。输出：

⚠️ MERMAID WARNING: ASCII box-drawing art detected in:
- {subsystem}/{view}: Convert to Mermaid diagram syntax

Proceeding to Phase 3. Fix ASCII diagrams in next iteration.

如果任何其他检查失败 → 停止并报告：

❌ PHASE 2→3 GATE BLOCKED

Missing or invalid view files detected:
- {subsystem}/{view}: [reason]

Regenerate missing views before proceeding to Phase 3.

占位符验证（MANDATORY）

确定任何视图文件的最终版本前，必须验证所有占位符均已填写：

要检查的占位符模式

模式	示例	严重程度	所需操作
`[TBD]`	`[TBD]`	CRITICAL	必须在完成前填写
`[STAKEHOLDER_*]`	`[STAKEHOLDER_1]`	CRITICAL	必须替换为实际干系人姓名
`[ENTITY_*]`	`[ENTITY_1]`	CRITICAL	必须替换为实际实体名称
`[COMPONENT_*]`	`[COMPONENT_1]`	CRITICAL	必须替换为实际组件名称
`[SUB_SYSTEM_NAME]`	`[SUB_SYSTEM_NAME]`	CRITICAL	必须替换为实际子系统名称
`[ADR_IDS]`	`[ADR_IDS]`	HIGH	必须替换为实际 ADR 引用
`[DATE]`	`[DATE]`	MEDIUM	必须替换为实际日期

验证流程

扫描每个视图文件，检查生成后是否仍有未填写的占位符
统计每种模式的出现次数
严重程度评估：
- CRITICAL：阻止完成——视图不能标记为 "completed"
- HIGH：应当填写；如果上下文清晰，则不阻塞
- MEDIUM：最好填写，但不是必需项

验证报告模板

## Placeholder Validation Report

| View | Placeholder | Count | Severity | Status |
|------|-------------|-------|----------|--------|
| context | [STAKEHOLDER_1] | 3 | CRITICAL | ❌ UNFILLED |
| functional | [COMPONENT_1] | 5 | CRITICAL | ❌ UNFILLED |

### Critical Placeholders Unfilled

**❌ VALIDATION FAILED**: Cannot mark views as "completed" with unfilled critical placeholders.

**Required Actions**:
1. Review ADRs for stakeholder names → fill [STAKEHOLDER_*] placeholders
2. Review ADRs for component names → fill [COMPONENT_*] placeholders
3. Re-run view generation with complete information

强制执行

含有未填写 CRITICAL 占位符的视图不能在 state.json 中标记为 "completed"
如果任何视图含有未填写的关键占位符，阶段 2→3 门槛将无法通过
使用 --force 可绕过（仅限紧急情况——记录所有未填写的占位符）

阶段 3：汇总（汇总 Agent）

目标：汇总所有视图、解决冲突并生成统一的 AD.md

脚本操作：运行 summarize 操作

步骤 3.1：从磁盘读取所有视图文件（必须）

关键：必须使用实际的文件读取操作，从文件系统读取每个视图文件。不要使用记忆中的内容或直接使用 ADR 中的内容。视图文件是唯一的事实来源。

扫描目录：列出 {REPO_ROOT}/docs/adlc/architect/views/ 目录
读取每个文件（必须，逐个文件读取）：
- 对于 state.json 中的每个子系统/视图组合
- 读取文件：{REPO_ROOT}/docs/adlc/architect/views/{subsystem}/{view}.md
- 如果无法读取文件 → 停止并报告错误：
```
❌ PHASE 3 ERROR: Cannot read view file
File: {path}
Error: {error details}

View files must exist and be readable before AD.md generation.
```
验证内容（必须）：
- 每个视图文件必须至少包含 20 行
- 每个视图必须包含适当的章节标题（## 或 ###）
- 如果内容验证失败 → 停止并报告：
```
❌ PHASE 3 ERROR: Invalid view file content
File: {path}
Lines: {count} (minimum 20 required)

View files must have substantial content before AD.md generation.
```
整理：按视图类型汇总所有子系统的内容

目录结构：

{REPO_ROOT}/docs/adlc/architect/views/
├── core/
│   ├── context.md
│   ├── functional.md
│   ├── information.md
│   ├── concurrency.md
│   ├── development.md
│   └── deployment.md
├── auth/
│   ├── context.md
│   ├── functional.md
│   ├── information.md
│   ├── development.md
│   └── deployment.md
└── data/
    ├── context.md
    ├── functional.md
    ├── information.md
    ├── development.md
    └── deployment.md

步骤 3.2：检测跨子系统冲突

比较各子系统的视图，检查以下问题：

冲突类型	检测方式	解决方法
命名不一致	同一组件使用不同名称	统一采用 ADR 术语
技术不匹配	相同用途采用不同技术	遵循相关 ADR
边界重叠	多个子系统声明拥有同一组件	使用 ADR 中的范围定义
图示不一致	同一实体采用不同表示方式	统一样式

步骤 3.3：使用 ADR 解决冲突

ADR 是事实来源。检测到冲突时：

找出管理冲突领域的相关 ADR
应用 ADR 决策解决冲突
在统一视图中记录解决方案

## Conflict Resolution Log

| Conflict | ADR Reference | Resolution |
|----------|---------------|------------|
| Auth component naming | ADR-002 | Standardized to "AuthService" per ADR-002 |
| Database technology | ADR-003 | PostgreSQL confirmed as primary per ADR-003 |

步骤 3.4：汇总为统一的 AD.md

关键：按视角组织汇总（约束 8）

AD.md 必须遵循以下结构，并按视角组织。每个视角章节都要合并所有子系统的内容，形成统一的系统级描述。不要按子系统组织——这种结构属于子系统视图文件，而不是汇总后的 AD.md。

对于每个视角：

提供系统级摘要，展示所有子系统之间的关系

包含展示跨子系统交互的统一 Mermaid 图

概述每个子系统在此视角中的职责

链接到子系统详情（如果有 2 个或更多子系统，则遵循步骤 3.5）

按视点聚合的方案

视点	聚合方式
上下文	单一系统级黑盒图（Mermaid `graph`）。仅当子系统具有独立的外部接口时，才将其显示为内部模块。合并并去重所有子系统中的利益相关者和外部实体表。
功能	合并所有子系统的组件清单表。使用单一的统一交互图展示跨子系统的数据流。使用 Mermaid `subgraph` 块按子系统显示边界。
信息	合并所有子系统实体的整合 ER 图（Mermaid `erDiagram`）。使用统一的数据流图展示数据如何跨子系统边界流动（Mermaid `flowchart`）。对实体表去重。
并发	合并的进程结构表。使用统一的时序图／流程图展示跨子系统的异步交互。
开发	展示所有子系统作为顶层目录的单一代码组织树。合并构建流程和 CI/CD 流水线表。统一技术栈映射。
部署	单一部署拓扑图（Mermaid `graph`），展示所有子系统及其运行环境。合并运行环境和硬件需求表。
运维	合并的运维职责表。统一所有子系统的监控、告警和灾难恢复（DR）策略。

统一 AD.md 的结构：

# Architecture Description: [Project Name]

## 1. Document Information
[Version, date, authors, status]

## 2. Architectural Goals & Constraints
[From constitution and constraint ADRs]

## 3. Architectural Views

### 3.1 Context View
[Unified from all sub-system context views]
[Single system-level context diagram]

> **Subsystem Details**: [Core](views/core/context.md) | [Auth](views/auth/context.md) | [Data](views/data/context.md)

### 3.2 Functional View
[Merged functional elements from all sub-systems]
[Unified component diagram]

> **Subsystem Details**: [Core](views/core/functional.md) | [Auth](views/auth/functional.md) | [Data](views/data/functional.md)

### 3.3 Information View
[Consolidated data model]
[Unified ER diagram]

> **Subsystem Details**: [Core](views/core/information.md) | [Auth](views/auth/information.md) | [Data](views/data/information.md)

### 3.4 Concurrency View (if applicable)
[Merged from sub-systems with concurrency]

> **Subsystem Details**: [Core](views/core/concurrency.md) | [Auth](views/auth/concurrency.md)

### 3.5 Development View
[Unified code organization]

> **Subsystem Details**: [Core](views/core/development.md) | [Auth](views/auth/development.md) | [Data](views/data/development.md)

### 3.6 Deployment View
[Consolidated deployment topology]

> **Subsystem Details**: [Core](views/core/deployment.md) | [Auth](views/auth/deployment.md) | [Data](views/data/deployment.md)

### 3.7 Operational View (if applicable)
[Merged operational concerns]

> **Subsystem Details**: [Core](views/core/operational.md) | [Auth](views/auth/operational.md)

## 4. Architectural Perspectives

### 4.1 Security Perspective
[Apply security template across all views]

### 4.2 Performance & Scalability Perspective
[Apply performance template across all views]

## 5. Architecture Decision Records Summary
[ADR index link: `../memory/adr/adr.md` (sibling-relative — resolves to {REPO_ROOT}/docs/adlc/memory/adr/adr.md)]

## 6. Tech Stack Summary
[Consolidated from all ADRs]

步骤 3.5：生成子系统视图链接（有条件）

条件：仅当 len(state.json.subsystems) > 1 时才生成链接

对于 AD.md 中的每个视图部分：

收集子系统链接：
- 遍历 state.json 中的每个子系统
- 检查该视图是否存在于子系统的 dag 数组中
- 构建链接：[SubsystemName](views/{subsystem-id}/{view}.md)

格式化链接块：

> **Subsystem Details**: [Core](path) | [Auth](path) | [Data](path)

处理缺失的视图：
- 如果某个子系统没有特定视图（不在 dag 中），则跳过该子系统的链接
- 示例：如果 Auth 没有并发视图，则从并发视图链接中省略
单个子系统的情况：
- 如果只存在 1 个子系统，则完全跳过添加链接
- 统一视图与子系统视图相同，因此添加链接是多余的

输出示例（3 个子系统，均有上下文视图）：

### 3.1 Context View
[Unified system-level context]

> **Subsystem Details**: [Core](views/core/context.md) | [Auth](views/auth/context.md) | [Data](views/data/context.md)

输出示例（2 个子系统，只有 Core 有并发视图）：

### 3.4 Concurrency View
[Merged concurrency concerns]

> **Subsystem Details**: [Core](views/core/concurrency.md)

步骤 3.6：应用视角

加载视角模板并将其应用于所有视图：

安全视角（`templates/perspectives/security.md`）

身份验证与授权方式
数据保护措施
威胁模型表

性能视角（`templates/perspectives/performance.md`）

性能需求表
可扩展性模型
容量规划

步骤 3.7：ADR 生命周期管理（必须）

生成 AD.md 后，执行以下所有步骤：

步骤 1：筛选已接受的 ADR

仅识别状态为 exact "Accepted" 的 ADR
必须保留在草稿中：状态为 "Proposed"、"Discovered"、 "Deprecated" 或 "Superseded" 的任何 ADR——这些 ADR 不符合晋升条件
验证：筛选后，统计晋升集合中的非 Accepted ADR 数量。如果 >0，停止并修正后再继续。

步骤 2：复制到规范位置（必须）

将已接受的 ADR 文件移至 {REPO_ROOT}/docs/adlc/memory/adr/（共享布局的规范记忆根目录）
如果文件不存在，则创建文件；如果已存在，则与现有内容合并
验证：重新读取文件并确认 ADR 已存在

步骤 3：清理草稿（必须）

将每个已晋升的 ADR 文件从 {REPO_ROOT}/.adlc/drafts/adr/ 移至 {REPO_ROOT}/docs/adlc/memory/adr/
如果草稿中没有剩余 ADR → 设置脚本会清理空目录
验证：确认：
- 不存在重复 ADR（两个位置中均有相同 ID）
- 剩余 ADR（如有）仅为 Proposed/Discovered
- 两个范围（草稿 + 记忆）的 adr.md 索引均已重新生成

步骤 3b：生成记忆 ADR 索引（必须）

将已接受的 ADR 移至 docs/adlc/memory/adr/ 后，使用设置脚本中的 generate_adr_index 函数，在 {REPO_ROOT}/docs/adlc/memory/adr/ 生成记忆索引文件 adr.md（该函数与生成草稿索引的函数相同，但 scope=memory——只要记忆范围内有记录，就会将索引写入 docs 根目录）：

source "{REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh"
generate_adr_index memory

此操作会生成 {REPO_ROOT}/docs/adlc/memory/adr/adr.md，其中包含 7 列架构，并通过 parse_fm_field 解析 YAML frontmatter。索引格式如下：

# Architecture Decision Records (Memory)

> Auto-generated by /architect-implement. Accepted ADRs only.
> Source: docs/adlc/memory/adr/ADR-*.md

## ADR Index

| ID | Sub-System | Decision | Status | Date |
|----|------------|----------|--------|------|
| ADR-009 | System | System Architecture Style | Completed | 2026-10-19 |

team-boot 会使用此索引在会话开始时注入内容，architect-analyze 会使用此索引进行架构审查（类似于 CDR.md 用于团队级上下文的方式）。

步骤 4：报告生命周期变更（必须） 向用户输出以下摘要：

📋 ADR Lifecycle Summary:
├── Promoted to memory: [N] Accepted ADRs
├── Remaining in drafts: [M] ADRs (Proposed/Discovered)
├── Duplicates found: [0] ✓
└── Cleanup verified: ✓

如果任何步骤失败：停止并修复，然后再将第 3 阶段标记为完成。

步骤 3.8：生成最终报告

## Architecture Description Generated

**Output**: AD.md (project root)
**Views Mode**: [core|all|custom]
**Sub-systems Processed**: N

**Views Generated**:
| Sub-system | Views | Status |
|------------|-------|--------|
| Core | Context, Functional, Information, Concurrency, Development, Deployment | ✓ |
| Auth | Context, Functional, Information, Development, Deployment | ✓ |
| Data | Context, Functional, Information, Development, Deployment | ✓ |

**Perspectives Applied**:
- [x] Security
- [x] Performance & Scalability

**Conflicts Resolved**: M
**ADR Coverage**: X/Y ADRs incorporated

**ADR Lifecycle**:
- Promoted to canonical: N ADRs
- Remaining in drafts: M ADRs

**Recommended Next Steps**:
1. Review generated AD.md for accuracy
2. Run `/architect-analyze` for consistency validation
3. Share with stakeholders for review
4. Run `/architect-analyze` to validate the generated architecture

最终完成情况验证（必须）

将 state.json 阶段标记为 "completed" 前，验证所有输出：

运行以下 10 项验证清单：

检查项	预期结果	验证方法	状态
1. 磁盘上的视图文件	N 个文件（每个子系统对应一个视图）	列出 `{REPO_ROOT}/docs/adlc/architect/views/`	☐
2. AD.md 存在	是，位于项目根目录	检查文件是否存在	☐
3. AD.md 内容大小	>200 行	统计 AD.md 行数	☐
4. AD.md 包含所有视图	N 个章节（## 3.x 标题）	解析 AD.md 标题	☐
5. 已晋升的记忆 ADR	N 个 Accepted ADR	统计 `{REPO_ROOT}/docs/adlc/memory/adr/` 中的文件数	☐
6. 草稿已清理	无重复项	比较草稿与记忆	☐
7. state.json 一致	所有视图均为 "completed"	验证 progress 字段	☐
8. 子系统链接（如适用）	AD.md 中包含链接（如果有 2 个以上子系统）	扫描 AD.md 中的 "Subsystem Details"	☐
9. 按视点组织（约束 8）	不含 `## N. Sub-System:` 章节	扫描 AD.md 中按子系统划分的顶层标题	☐
10. Mermaid 图表（约束 9）	不含 ASCII 方框绘图	扫描 AD.md 中的 `┌`、`└`、`├`、`═` 字符	☐

门控规则：

如果所有检查均通过（☑）：在 state.json 中将阶段标记为 "completed"
如果任何检查未通过（☒）：不要标记为已完成。修复问题并重新验证。

向用户输出：

✅ Architecture Description Generation Complete

Verification Results:
├── View files: [N] generated ✓
├── AD.md: [lines] lines, [sections] views ✓
├── Subsystem links: [N] links (if applicable) ✓
├── Viewpoint-organized: ✓
├── Mermaid diagrams: ✓
├── ADRs promoted: [N] to memory ✓
├── Drafts cleaned: [N] remaining ✓
└── State consistent: ✓

Status: READY FOR USE

状态文件架构

位置：{REPO_ROOT}/.adlc/architect/state.json

{
  "version": "1.1.0",
  "created_at": "ISO8601 timestamp",
  "updated_at": "ISO8601 timestamp",
  "phase": "planning | plan_approved | executing | summarizing | completed",
  "views_mode": "core | all | custom",
  "subsystems": [
    {
      "id": "lowercase-kebab-case",
      "name": "Display Name",
      "adrs": ["ADR-001", "ADR-002"],
      "characteristics": ["microservices", "event-driven"],
      "dag": ["context", "functional", "information", "development", "deployment"],
      "progress": {
        "context": "pending | in_progress | completed | skipped",
        "functional": "pending | in_progress | completed | skipped"
      }
    }
  ],
  "perspectives": ["security", "performance"],
  "conflicts_detected": [],
  "conflicts_resolved": [],
  "output_file": "AD.md"
}

关键规则

ADR 可追溯性

每个视图章节都必须引用源 ADR
不得包含没有 ADR 依据的内容
ADR 是冲突解决的事实来源

状态持久化

始终更新每次操作后的 state.json
从任何中断处平稳恢复
按视图粒度跟踪进度

多 Agent 兼容性

状态文件可与任何 AI Agent 配合使用（Claude、Copilot、Cursor 等）
无 Agent 专属依赖
状态文件便于人工阅读，方便调试

图表质量

写入前验证 Mermaid 语法
子系统间采用一致的样式
在最终的 AD.md 中使用统一的图表

上下文

$ARGUMENTS

后续步骤

implement 完成后，运行 /architect-analyze 验证一致性和质量。

验证

{REPO_ROOT}/docs/adlc/architect/AD.md 存在，且超过 200 行，并包含所有视点章节（## 3.x 标题）。
每个已完成的视图都有对应的子系统视图文件，位于 {REPO_ROOT}/docs/adlc/architect/views/{subsystem}/{view}.md。
state.json 状态一致：所有生成的视图均标记为 "completed"，且阶段为 "completed"。
已接受的 ADR 已归档：所有状态为 "Accepted" 的 ADR 均已移至 {REPO_ROOT}/docs/adlc/memory/adr/；已在 {REPO_ROOT}/docs/adlc/memory/adr/adr.md 重新生成记忆索引。
清理草稿：已晋升的 ADR 文件已从 {REPO_ROOT}/.adlc/drafts/adr/ 移至 {REPO_ROOT}/docs/adlc/memory/adr/；不存在重复文件；其余草稿仅包含 Proposed/Discovered 状态。
AD.md 按视点组织：章节按视点分组（## 3. Architectural Views → ### 3.1 Context View 等），而非按子系统分组。
仅使用 Mermaid 图表：架构图中未使用 ASCII 框线字符（┌、└、├、│、═、───）。
占位符验证通过：视图文件中不存在尚未填写的关键占位符（[TBD]、[STAKEHOLDER_*]、[ENTITY_*]、[COMPONENT_*]、[SUB_SYSTEM_NAME]）。
处理了两个或更多子系统时，AD.md 中包含子系统详细信息链接。

支持 Markdown

登录后评论

基本信息

作者: tikalk
仓库: tikalk/adlc-team-skills
分类: 开发
安装次数: 189
GitHub Stars: 143

报告问题

architect-implement

关于 architect-implement

主要功能

适用场景

安装

详细介绍

architect-implement

此技能的作用

适用场景

不适用场景

流程

用户输入

标志

与 Rozanski & Woods 方法论保持一致

核心原则

视点依赖图

动态视点与视角选择

目标

角色与上下文

架构文档层级

视图模板

三阶段 DAG 工作流

预检验证（强制 — 严格执行）

工作流状态检查（除非使用 --force）

ADR 状态检查

强制执行约束

约束 1：视图文件必须写入磁盘

约束 2：每个视图完成后都必须更新状态

约束 3：必须在功能视图处设置检查点

约束 4：阶段标记为 "completed" 前必须完成验证

约束 5：AD.md 内容必须来自视图文件

约束 6：第 3 阶段必须从磁盘读取

约束 7：视图必须属于子系统 DAG

约束 8：AD.md 必须按视点组织

约束 9：图表必须使用 Mermaid 语法

阶段 1：规划（规划 Agent）

步骤 1.1：加载并分析 ADR

步骤 1.2：检测子系统及其特征

步骤 1.3：为每个子系统生成定制 DAG

步骤 1.4：提交计划供用户批准

步骤 1.5：写入 state.json

阶段 2：执行（执行 Agent）

步骤 2.1：读取执行状态

步骤 2.2：按 DAG 顺序生成视图

步骤 2.3：视图模板和占位符

步骤 2.4：视图生成详情

上下文视图

功能视图（★ 基石 - 用户检查点）

信息视图

并发视图（可选）

开发视图

部署视图

运维视图（可选）

步骤 2.5：更新 state.json 中的进度

步骤 2.6：可恢复性

阶段 2→3 门槛：验证视图文件是否存在（MANDATORY）

占位符验证（MANDATORY）

要检查的占位符模式

验证流程

验证报告模板

强制执行

阶段 3：汇总（汇总 Agent）

步骤 3.1：从磁盘读取所有视图文件（必须）

步骤 3.2：检测跨子系统冲突

步骤 3.3：使用 ADR 解决冲突

步骤 3.4：汇总为统一的 AD.md

按视点聚合的方案

步骤 3.5：生成子系统视图链接（有条件）

步骤 3.6：应用视角

安全视角（templates/perspectives/security.md）

性能视角（templates/perspectives/performance.md）

步骤 3.7：ADR 生命周期管理（必须）

步骤 3.8：生成最终报告

最终完成情况验证（必须）

状态文件架构

关键规则

ADR 可追溯性

状态持久化

多 Agent 兼容性

图表质量

安全视角（`templates/perspectives/security.md`）

性能视角（`templates/perspectives/performance.md`）