Software Architecture

---
name: software-architecture
description: 系统边界、模块职责、依赖方向、运行拓扑、跨边界契约、质量属性与架构演进的专业裁决。
---

# 软件架构

## 目标

对系统边界、职责、依赖、运行拓扑、集成关系与质量属性作出可实施、可验证且可演进的软件架构判断。

## 执行协议

1. 确认本专业范围、任务所指产品与工作边界、授权改动、受影响消费者、验证边界和未知项。
2. 阅读 [能力索引](references/principles.md)，完整读取本次命中分卷，再按“项目记忆”章读取同簇的记忆范围与项目事实；发现新依赖或风险时补读相关分卷。
3. 区分用户已裁定的目标与政策、当前事实、因果推断和待证假设，具体方案不因提出者、既有实现或测试而自动成立。以受影响完整流程的结果、必要状态与交接、契约及副作用、失败恢复、变更扩散和维护成本复核决定。新证据推翻前提，或修复只能依靠新增例外、复制规则或状态、绕过责任边界时，先重审受影响决定，不能继续叠加补丁或牵连仍成立的无关决定；超出专业所有权时说明矛盾、影响和待裁决选项。
4. 对涉及现有行为异常、失败、回归或修复的任务，首次写入前必须完成诊断门：以用户可读的固定字段（当前事实、首个错误状态、最小复现、根因假设、验证动作、预期与禁止结果、实际结果、根因结论、下一步）完成诊断；至少提出两个可区分且可证伪的根因假设，若候选已被证据排除，写出排除依据，不为凑数。只有验证结果能够解释首个错误及相关现象、并排除主要替代假设时，方可编辑业务代码、测试断言或配置；证据不足时只能继续读取、复现、查询或请求澄清。新证据否定当前假设时，立即标记其失效，停止沿该假设修补并回到诊断门。
5. 按真实依赖和可验证的边界变化拆解复杂工作，步骤应最小充分、目标单一并保持受影响契约与系统不变量；简单任务直接处理。在当前授权内依命中准则实施或审查，不扩入无关改动。
6. 阶段目标完成时，按本阶段风险选择并运行相称的依赖、契约及质量场景证据，确认已完成部分自洽后再推进依赖它的工作；结束前核对最终差异、跨界行为与演进约束，记录证据能证明与不能证明的范围。
7. 每次修改后，必须将改动、预期因果路径和验证结果逐项对应。若首个错误仍在、出现新错误或验证未能区分结果，不得在原假设上继续追加补丁；仅回退本轮由该假设产生的改动，保留无关工作区状态，重新进入诊断门，并在无法形成证据时以阻塞或证据不足结束。
8. 工作中按“项目记忆”章随证据维护事实册，结束前完成收口对账；汇报实际结果、验证范围、未解决问题及必要的后续条件。

## 项目记忆

- 当前产品根目录是任务所指产品的工作边界，不要求存在 Git 仓库或 `.git`。用户明确指定的目录优先；否则结合目标文件、产品入口、元数据与调用链确定，进程当前目录、Git 根或 Skill 所在目录都不能单独作为依据。Product Studio 仅作技能提供者时，其源码、安装与缓存目录不属于目标产品；任务明确以插件本身为产品时除外。根目录不唯一时暂停事实册操作，继续已明确范围内的工作。
- 结合产品入口、元数据与目标文件确定稳定、唯一且符合目标文件系统规则的单级 `product-id`，排除 `.`、`..` 和路径分隔符；无法确认时不猜测建册。事实路径为 `<当前产品根目录>/docs/product-studio/<product-id>/software-architecture/<簇卷文件名>.md`，簇卷文件名与本 Skill 的 `references/principles/` 对应。所有事实路径均从已确认产品根解析，不能按进程或技能目录解释相对路径。
- 工作前读取本 Skill 的 `references/memory/` 中与命中簇同名的记忆范围，再读取该簇事实文件；无关簇不读取。命中事实涉及其他簇或专业的约束时，仅沿相关引用补读必要事实并核对权威来源，已读内容不重复加载。文件不存在或引用失效时依据当前产品证据继续工作；旧记忆与当前权威冲突时，以当前权威为准。
- 只保存本轮实际核验、属于本专业所有权、会持续影响后续判断且难从局部代码直接看清的核心认知。本轮新确认的既有事实同样纳入判断，不以 Git 差异为限；不复制源码、配置或可生成清单。
- 只读分析、审查和状态查询不写事实册，除非用户明确要求维护记忆；任务允许修改当前产品根内目标文件时，同根事实册维护属于该写权限，用户排除的路径与资源除外。记忆维护不扩大到产品根之外。
- 符合准入条件的认知形成证据闭环且预计不受剩余工作影响时，即时写入。结束前对本轮核验范围收口对账：可写时直接补录遗漏、更新改变或移除失效事实，不仅列出候选，也不因文件缺失而跳过；没有符合条件的事实差异就不改文件。
- 某簇出现首条事实时创建对应 Owner 目录和事实文件，无事实不建空目录或空文件。文件首行为 `# software-architecture 当前产品事实 · <簇名>`，以稳定、可检索的业务语义作二级标题，用现在时说明当前事实、成立条件、影响边界、相对产品根的权威核验入口及失效或重审条件。
- 同一认知只在主责专业与能力簇保留一份；其他簇仅记录与自身判断有关的影响和相对产品根的事实引用，不复制原认知或代作其他专业裁决。旧内容原位更新或移除，不追加历史版本。某簇末条事实移除后删除该文件；空目录清理仅向上到本 Owner 目录及其空的 `<product-id>` 目录。
- 不记录秘密、令牌、用户数据、任务过程、文件改动清单、迁移进度、运行快照、当前版本、一次性结果或未经验证的推断。