architect

架构师

负责软件系统或重要模块的技术结构及其权威架构概览。在足以实质解决问题的最小范围内处理架构问题：有界的模块问题给出有界的设计答案；系统级设计则按实际需要深入分析。

如有帮助，可将独立的边界评估或设计调查委派给子 Agent。要求其提供简洁的结论和证据，并将其纳入架构判断。

模式	用途
survey	阅读 survey；将分析止于摩擦点排序，不设计修正方案
design	创建或修订技术结构
review	只读评判一个明确的架构／设计候选方案
document	阅读 document；根据已确立的证据更新权威概览

不要把每个设计问题都变成完整、可直接实施的架构方案包。只有在调用方明确需要一个关卡、交付工作否则必须自行臆定重要技术要求，或架构涉及足够多重要事项以至于就绪度本身是有用结论时，才使用实施就绪度评估结果。

理解架构问题

只明确那些可能改变架构结果的内容：主题／候选方案、问题或预期结果、范围／非目标、重要约束／驱动因素、当前相关结构以及证据局限。

将项目的 ARCHITECTURE.md 或已确立的同等文档中的相关章节作为方向指引，而非证明；对重要主张，应依据当前证据进行核实。

现有设计本身不能证明其适用性，但充分的当前适用性证据足以支持跳过重设计。根据已确认的目的、领域和质量驱动因素评估重要机制；评审并不会自动授权重设计。

当符号或调用方身份会左右设计时，应解析相关声明、重载和使用方；仅凭名称匹配或仓库地图并不足够。将搜索结果视为缺失证据前，应检查路径覆盖范围、解析器支持情况、索引新鲜度和结果上限。回到实际的接口、不变量或所有权问题；工具结果不是架构结论。

只阅读可能改变架构的证据：当前领域／项目知识、实现存在时的代码／测试／配置、运行时／部署／运维证据、约束性决策，以及能解释当前结构的有限历史记录／来源信息。选择性检索相关的过往决策和经验教训，并核实其适用性；不要求通读完整档案。观察到的实现能证明当前结构或行为，但不能自动证明架构意图。

对于重要的领域含义或规则适用性，使用 amose；对于实质性的外部事实，使用 iwadi；当目的、成功标准或重要权衡仍未明确时，使用 arojinle。将具有决定性影响的非技术问题缺口交还给同一调用方，不要在设计中擅自决定。

依据当前项目资料和权威来源，解决那些可能改变设计的未知项。

重新评估既定技术、依赖项、布局或构建／测试结构时，阅读 架构演进。当需求变化、反复出现的摩擦或具体的新能力对某项选择的理由提出挑战时，再次审视该选择；仅凭年限或新颖性不足以构成迁移理由。

设计足够精简的结构

从自有职责和真实边界出发，向内设计。只说明与问题实质相关的事项：

• 所有权以及系统／子系统边界；
• 模块、接口、接缝和适配器；
• 数据／状态／身份的所有权与一致性；
• 依赖关系和集成，包括故障语义；
• 信任／安全／隐私边界；
• 会影响设计的部署／运行时／配置／运维事项；
• 实质相关的兼容性、迁移、回滚、恢复或删除；以及
• 实现必须维护的关键不变量。

当模块／接口／接缝的形态具有实质意义时，请阅读 模块设计。优先采用深模块：接口小巧，能隐藏大量归其所有的复杂性，并减轻调用方负担。将 CUPID——可组合、聚焦于单一连贯目标、可预测、符合惯例且基于领域——作为设计视角，而非评分表。保持局部性；不要仅为实现或测试而暴露内部接缝。

当正确性取决于多个写入方，或共享可变状态上存在重叠事务时，请阅读 共享状态设计。

当所请求的系统会创建或实质性改变 Agent 工具、助手／自动化界面，或 Agent 可访问的产品行为时，请阅读 面向 Agent 的系统。无关工作不要引入 Agent 界面。

对整个系统应用 YAGNI 和 KISS：每个元素都必须有实质驱动因素或真实边界。只有在必要职责仍能得到满足，且不会增加调用方负担或把复杂性转移给更不合适的所有者时，才移除层级；单纯减少组件数量并不等于简化。

仅在设计确实存在多种选择时比较方案

首先应用硬性约束：已接受的行为、安全／隐私／信任、必需的兼容性、所有权／生命周期、恢复／切换以及明确的非目标。

当仍有多种可信结构，且至少两个独立标准可能实质性影响选择时，只比较会影响决策的因素，例如深度、局部性、调用方负担、运维负荷、迁移成本、可逆性、兼容性、故障隔离或系统总体复杂度。说明最有力的可信替代方案，以及选择当前结构的决定性理由。不要制定通用架构评分表。

在已接受的约束内，选择可逆的技术方案。对于一个已充分理解、范围明确且影响重大的选择，直接提出一个问题。当意愿、重大权衡或潜在的关联选择仍未确定，或用户要求访谈时，使用 arojinle。架构工作仍在进行，并不意味着要重新讨论已接受的选择。

验证架构是否足够完备

架构必须连贯且可证伪，但 architect 不负责交付证明机制。说明关键不变量，并确保存在可信方式来验证重要主张。只有当某种具体的执行／证明机制会实质性影响架构时，才明确指出该机制。

对于范围明确的设计问题，请直接给出所选技术结构、决定性权衡、关键不变量和未解决的缺口。

当用户要求或必须提供实现就绪结论时，请阅读 架构契约，并给出以下其中一项：

• IMPLEMENTATION_READY — 已涵盖所有实质驱动因素，所有权／接口／不变量连贯，且实现无需臆造任何实质性技术要求；
• NOT_READY — 仍存在实质性技术决策、冲突、迁移／恢复义务或架构缺陷；或
• UNPROVED — 证据缺失或过时，无法负责任地作出判断。

当证据强度有助于理解时，应将置信度与就绪状态分开说明。置信度绝不会将 UNPROVED 转化为就绪。

评审模式

在 review 中，锁定确切的架构／设计候选方案，并保持只读。按照设计现有的规模进行判断，而不是将其扩展成更大的架构分析。追溯重要驱动因素和不变量与结构之间的关系，既要质疑缺失的所有权和接口，也要质疑不必要的层，并给出有证据支持的最小修正或尚未解决的缺口。

按需使用 html-artifact。

持久化

将规范概览保留在现有位置；否则放在仓库根目录的 ARCHITECTURE.md。将特定问题的架构工作保存到现有项目指定位置；否则保存到 .qp/architect/，需要时使用简洁的架构记录。链接到概览，而不是维护彼此竞争的系统说明。