repo-architecture

RepoSkillOpt — 现状架构分析（规范技能）

目的

这是 RepoSkillOpt 的仓库专用分析层。通用理解技能 （repo-skillopt）保持不变——它会生成与仓库无关的仓库规范。此技能 针对特定仓库进行专门分析：在仓库规范的基础上深入分析，形成有证据支撑的 当前架构视图，并回答“如果进行某项更改，会波及哪些部分？” ——在触及任何内容之前。它会生成架构视图和变更影响 （波及范围）分析；现状分析阶段的结果将由目标状态规划技能（repo-orchestration） 使用。技能本身的内容与供应商无关（不依赖任何编码 Agent 运行时）；其输出则针对具体仓库。

触发条件

当用户要求梳理架构、评估依赖关系／耦合／分层， 或评估“如果我们……会有什么变化／更改 X 是否安全”——或提出可识别的同类请求时，激活此技能。 对于无关请求，不要激活。

前置条件

仓库规范（.reposkillopt/specs/repository-specification.md）。如果不存在，请说明 此前置条件，并引导用户使用仓库理解技能；不要根据浅层检查臆造架构。

操作原则

• 以规范为基础，并通过代码佐证。 仓库规范是起始证据；应根据实际文件、配置和调用点验证每一项架构断言。
• 为每项重要断言提供依据。 每项恰好带有一个标签——**[fact]**、**[inference]**、 **[unknown]**、**[human]**；**[fact]** 必须附带可解析的 file:line／符号引用。
• 不得悄然省略。 无法解析的结构或影响应标为 **[unknown]** 并说明原因，绝不可省略。
• 不得夸大结论。 不要描述未追踪过的层或流程；推断应明确标为推断。
• 仓库事实仅适用于该仓库。 只有明确标记为“可作为通用候选”的模式，才能进入技能收敛流程。

工作流

(a) 阅读仓库规范，以及其中引用的入口点、清单和核心模块。

(b) 架构视图（.reposkillopt/architecture/architecture-view.md，遵循 templates/architecture-view.md）：采用 C4 风格的层级——上下文（系统 + 外部参与者）、 容器（运行时／可部署单元）、组件（容器内的模块）——以及关键序列（端到端流程，每个环节均附引用） 和依赖关系图（内部边均附引用）。每个组件和边都必须引用真实的 file:line。图示 （graph、sequenceDiagram）仅用于可视化，不附引用；图中展示的每个节点／边也必须出现在带引用的行中。

(c) 变更影响分析（.reposkillopt/impact/change-impact-analysis.md，遵循 templates/change-impact-analysis.md）：针对指定目标／变更，列出受影响的模块、测试、契约和调用点——每一行都带有与证据强度对应的置信度标签（直接引用的调用点 = 高；名称解析／推断 = 中；动态／无法解析 = 低且标为 **[unknown]**），并附上引用。使用快速扫描器（rg／grep）定位影响，只阅读所引用的匹配行。

(d) 确定性完整性检查。 完成前，产物必须通过确定性检查（check_architecture_view、check_impact_analysis）：每个组件／边均有引用且可解析；每条影响记录均带有引用和置信度标签。

输出规范

标签：**[fact]**（已验证；有引用）、**[inference]**（说明依据）、**[unknown]**（同时列为未知项）、**[human]**（引用 Feedback Item ID）。引用格式为 path:line、 path:start-end、path:Symbol[:line] 或 cmd:／output:。无需为简单复述添加标签。

人工反馈循环

修正内容会作为 反馈项（templates/human-feedback.md）记录在 .reposkillopt/feedback/ 下，并直接应用于相应工件。特定于仓库的修正仅作用于该仓库。

技能收敛循环

当标记为 candidate-for-generic 的反复反馈（≥3 条相关反馈项）揭示出此技能存在弱点时，起草一份 技能编辑提案（templates/skill-edit-proposal.md）。只有通过验证门槛（rubric/validation-gate.md）后，提案才能被接受：针对一组互不重叠的留出参考集重新生成工件，且各维度评分均无退步（参见 rubric/asis-architecture-rubric.md），并且确定性检查仍然通过。任何内容都不会被静默提升；接受提案时会递增版本号并添加一条 CHANGELOG 记录。每项获接受的编辑都必须同步到四个适配器中（适配器等效性）。