name: architect-first description: 实施“架构优先”开发哲学的指南 - 完美架构、务实执行、测试保证质量。在启动新功能、重构系统或需要架构决策时使用此技能。强制执行不可协商的原则，如编码前完成设计/文档化、零耦合，以及结构决策前的多视角验证。

架构优先

概述

这个技能体现“架构优先”开发哲学：完美架构、务实执行、测试保证质量。在进行架构决策、启动新功能、重构现有系统或需要执行质量门禁时应用此技能。

核心原则：架构和文档化是不可协商的，必须在实现之前完成。代码质量是可协商的，前提是以测试作为安全网（逃生口）。

核心哲学

信条

“完美架构、务实执行、测试保证质量”

质量门禁

不可协商（如果违反则停止）：

架构：编码前完成设计和文档化
文档化：必须先于并伴随实现
能力保留：永不丧失相对于先前版本的能力/粒度
零耦合：扩展包必须独立
多智能体验证：结构决策需经产品负责人/架构师/用户验证

可协商（带逃生口）：

代码风格：如果以测试作为安全网则可接受
功能完整性：80%可接受，前提是核心用例工作
快速脏代码：仅允许在具有测试计划和最小日志记录的情况下

决策模式

架构优先模式（默认）：

编码前完全设计和文档化
在提议实现前映射结构和指针
用多个智能体/视角验证架构
将所有可变配置外部化到YAML

快速模式（仅限验证后）：

二元决策和快速委派
仅在架构验证完成后激活
通过自动化加速，而非捷径

工作流决策树

新任务/功能请求
    ↓
┌──────────────────────────────────────┐
│ 这是一个结构/架构决策吗？            │
└──────────────────────────────────────┘
    ↓ 是                     ↓ 否
    ↓                        ↓
[架构流程]              [执行流程]

架构流程（结构决策）

停止并遵循此序列：

先映射后修改
- 完全记录当前状态
- 识别所有依赖和接触点
- 创建架构图/流程图
- 加载 references/architecture-checklist.md 进行验证
多智能体验证
- 用明确权衡展示A/B/C选项
- 从以下获取验证：
  - 产品负责人（业务对齐）
  - 架构师（技术合理性）
  - 用户（最终决策）
- 记录决策理由
设计文档化
- 编码前完成设计文档
- 包括：
  - 系统架构图
  - 组件交互
  - 数据流
  - 配置模式（YAML）
  - 集成点
- 使用 assets/architecture-template.md 中的模板
黄金标准基线
- 确保新设计达到或超过能力基线
- 验证：是否保持所有先前能力？
- 如果检测到能力丧失 → 停止，恢复或重新设计
零耦合验证
- 运行验证脚本：scripts/check_coupling.py
- 确保扩展包独立
- 无硬编码跨模块依赖
进行实现
- 现在且仅现在：编写代码
- 遵循执行流程进行实现

执行流程（实现）

预实现检查清单
- [ ] 架构是否已记录和验证？
- [ ] 核心用例是否明确定义？
- [ ] 配置是否已外部化到YAML？
- [ ] 测试策略是否定义？
- 使用 references/pre-implementation-checklist.md
测试驱动安全网
- 首先定义测试计划
- 识别日志/观察点
- 测试允许暂时不完美（逃生口）
- 通过以下验证质量：测试 + 日志 + 手动检查

实现风格

可接受：
✓ “丑陋”代码带全面测试
✓ 80%功能完整性，前提是核心用例工作
✓ 快速实现带测试计划和日志记录

拒绝：
✗ “丑陋”代码无测试
✗ 能力丧失无明确理由
✗ 硬编码可变值（必须是YAML）
✗ 部署时核心用例未工作

调试哲学
- 通过日志观察（控制台/日志记录）> 静态分析
- 调试前添加战略日志点
- 检查实际运行时行为
- 通过执行验证，而非仅阅读代码
文档化
- 随代码演化更新文档
- 保持简短和可操作：“如何自定义”
- 包括代码示例
- 记录配置选项

启发式（决策规则）

做决策时应用这些启发式：

黄金标准基线：最少22个工件（根据上下文调整）
永不丧失能力：积累，永不减少
先架构后构建：始终先设计/文档化后编码
零耦合，最大模块化：独立扩展包
配置优于硬编码：将所有可变值外部化到YAML
先映射后修改：修改前记录结构
验证后二元决策：架构验证后快速执行
通过自动化加速：非通过捷径或偷工减料
质量逃生口：测试允许暂时不完美

停止规则（硬边界）

如果检测到以下立即停止：

⛔ 能力丧失相对于基线
⛔ 结构决策无多智能体验证
⛔ 模块间耦合
⛔ 缺少架构文档化
⛔ 快速脏代码无测试计划和日志
⛔ 硬编码可变配置值

停止时，参考 references/stop-rules-guide.md 进行修复。

风险缓解

常见风险及其缓解策略：

风险	缓解策略
过度规划	时间盒化 + 正式化前的强制概念验证
完美主义级联	3规则：简单试点 → 2次迭代 → 正式化
过早配置	仅在实际场景≥2后泛化
上下文切换	每次转折时的待办事项检查清单

使用 scripts/validate_risk_mitigation.py 检查风险缓解覆盖。

协作契约

使用此技能时，遵循这些协作模式：

✓ 做：

用明确权衡展示A/B/C选项
提议代码前映射结构和指针
在YAML中外部化配置；无硬编码可变值
交付简短、可操作的文档（“如何自定义”）
对于快速代码：包括测试计划和日志点
转折时记录待办事项

✗ 不做：

无架构上下文提议代码
硬编码可能变化的值
跳过结构变更的多智能体验证
编写无测试的“快速脏代码”
单方面做架构决策

验收标准

将接受

✓ “丑陋”代码带全面测试
✓ 80%功能，前提是核心用例覆盖
✓ 增加灵活性的大型重构
✓ 广泛的文档化，如果它教授自定义

将拒绝

✗ “丑陋”代码无测试
✗ 能力丧失无明确理由
✗ 硬编码可变值
✗ 部署时核心用例未工作

未知领域（用于未来精炼）

哲学中尚未完全定义的领域：

热修复哲学（生产紧急情况）
性能阈值（延迟/吞吐量最低要求）
代码重复容忍度（何时重构）
可观察性目标（日志级别、相关性、追踪）

遇到这些领域时，应用核心启发式并记录决策以供未来精炼。

资源

scripts/

验证和自动化脚本：

check_coupling.py - 验证零耦合原则
validate_risk_mitigation.py - 检查风险覆盖
architecture_validator.py - 验证架构完整性

references/

详细检查清单和指南：

architecture-checklist.md - 完整架构验证检查清单
pre-implementation-checklist.md - 预编码验证
stop-rules-guide.md - 当停止规则触发时的修复指南
testing-strategy-guide.md - 测试驱动开发模式

assets/

一致输出模板：

architecture-template.md - 标准架构文档模板
config-template.yaml - 配置外部化模板
adr-template.md - 架构决策记录模板

快速参考

启动新功能：

映射当前架构（references/architecture-checklist.md）
用A/B/C选项设计
多智能体验证
记录架构（assets/architecture-template.md）
定义测试
实现带日志记录
验证和迭代

进行架构变更：

停止 - 暂不编码
完全记录当前状态
用权衡展示选项
获取产品负责人/架构师/用户验证
检查耦合（scripts/check_coupling.py）
记录决策（assets/adr-template.md）
现在实现

快速实现（带安全网）：

预实现检查清单
定义测试计划
添加日志点
实现（可以是“丑陋”的）
验证测试通过
检查日志
如果需要则重构