Back to Details

repo-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

RepoSkillOpt — As-Is Architecture Analysis (Canonical Skill)

RepoSkillOpt — 现有架构分析（标准Skill）

Purpose

用途

This is the repo-specializing analysis layer of RepoSkillOpt. The generic understanding skill (
repo-skillopt
) is unchanged — it produces the repo-neutral Repository Specification. This skill specializes on a specific repository: it deepens that Repository Specification into an evidence-grounded view of the current architecture and answers "what would a change ripple into?" — before anything is touched. It produces an Architecture View and a Change-Impact (blast-radius) Analysis, and is the analyze as-is stage the plan to-be skill (
repo-orchestration
) consumes. The skill's own content is vendor-neutral (no coding-agent runtime dependency); its output is repo-specific.
这是RepoSkillOpt的仓库专属分析层。通用理解Skill（
repo-skillopt
）保持不变——它生成与仓库无关的Repository Specification。本Skill专注于特定仓库：它将Repository Specification深化为基于证据的当前架构视图，并回答“变更会波及哪些范围？”——在任何修改之前。它生成Architecture View和变更影响（影响范围）分析，是规划目标状态Skill（
repo-orchestration
）所使用的现有状态分析阶段。本Skill自身内容与厂商无关（无编码Agent运行时依赖）；其输出是仓库专属的。

Trigger Conditions

触发条件

Activate when the user asks to map the architecture, assess dependencies/coupling/layering, or evaluate "what would change if we… / is it safe to change X" — or recognizable equivalents. Do not activate for unrelated requests.
当用户要求绘制架构图、评估依赖/耦合/分层，或者评估“如果我们……会有什么变化 / 修改X是否安全”——或可识别的等效请求时激活。请勿为无关请求激活。

Prerequisite

前置条件

A Repository Specification (
.reposkillopt/specs/repository-specification.md
). If absent, state the prerequisite and point the user to the repository-understanding skill; do not fabricate an architecture from shallow inspection.
需要Repository Specification（
.reposkillopt/specs/repository-specification.md
）。如果缺失，请说明前置条件并引导用户使用仓库理解Skill；请勿通过浅层检查编造架构。

Operating Principles

操作原则

  • Build on the spec, corroborate against code. The Repository Specification is the starting evidence; verify every architectural claim against the actual files, configs, and call sites.
  • Ground every major claim. Each carries exactly one label — 
    **[fact]**
    , 
    **[inference]**
    , 
    **[unknown]**
    , 
    **[human]**
    ; 
    **[fact]**
    MUST carry a resolvable 
    file:line
    /symbol citation.
  • No silent omission. Unresolvable structure or impact is 
    **[unknown]**
    with the reason, never dropped.
  • Do not overclaim. Do not describe layers or flows you have not traced; mark inference as inference.
  • Repository facts stay repository-scoped. Only patterns explicitly marked candidate-for-generic may enter the skill-convergence loop.
  • 基于规范构建，对照代码验证。Repository Specification是初始证据；针对实际文件、配置和调用点验证每一项架构声明。
  • 为每个重要声明标注依据。每个声明需附带一个标签——
    **[fact]**
    、
    **[inference]**
    、
    **[unknown]**
    、
    **[human]**
    ；
    **[fact]**
    必须附带可解析的
    file:line
    /符号引用。
  • 不遗漏未解析内容。无法解析的结构或影响需标记为
    **[unknown]**
    并说明原因，不得丢弃。
  • 不夸大声明。请勿描述未追踪过的层级或流程；将推断内容标记为推断。
  • 仓库事实仅限仓库范围内。只有明确标记为候选通用模式的内容才可进入Skill收敛循环。

Workflow

工作流程

(a) Read the Repository Specification and the entrypoints, manifests, and core modules it cites.
(b) Architecture View (
.reposkillopt/architecture/architecture-view.md
, per 
templates/architecture-view.md
): C4-style levels — Context (system + external actors), Containers (runtime/deployable units), Components (modules within containers) — plus Key sequences (end-to-end flows, cited at each hop) and a Dependency graph (cited internal edges). Every component and edge cites a real 
file:line
. Diagrams (
graph
, 
sequenceDiagram
) are visual aids and carry no citations; every node/edge they show also appears as a cited line.
(c) Change-Impact Analysis (
.reposkillopt/impact/change-impact-analysis.md
, per 
templates/change-impact-analysis.md
): for the named target/change, the affected modules, tests, contracts, and call sites — each row with a confidence label (high|medium|low) tied to evidence strength (direct cited call site = high; name-resolution/inference = medium; dynamic/unresolved = low and 
**[unknown]**
) and a citation. Locate impact with a fast scanner (
rg
/
grep
) and read only the matched lines you cite.
(d) Deterministic completeness gate. Before finishing, the artifacts MUST pass the deterministic checks (
check_architecture_view
, 
check_impact_analysis
): every component/edge cited and resolvable; every impact row carries a citation and a confidence label.
(a) 读取Repository Specification及其引用的入口点、清单和核心模块。
(b) Architecture View（
.reposkillopt/architecture/architecture-view.md
，遵循
templates/architecture-view.md
模板）：采用C4-style层级——Context（系统+外部参与者）、Containers（运行时/可部署单元）、Components（容器内的模块）——外加关键序列（端到端流程，在每个环节引用）和依赖图（引用内部连接）。每个组件和连接都需引用真实的
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
）：每个引用的组件/连接均可解析；每个影响行都带有引用和置信度标签。

Output Discipline

输出规范

Labels: 
**[fact]**
(verified; cited), 
**[inference]**
(state the basis), 
**[unknown]**
(also listed as such), 
**[human]**
(cite the Feedback Item id). Citations use 
path:line
, 
path:start-end
, 
path:Symbol[:line]
, or 
cmd:
/
output:
. Trivial recitations need no label.
标签：
**[fact]**
（已验证；带引用）、
**[inference]**
（说明依据）、
**[unknown]**
（同样标记）、
**[human]**
（引用反馈项ID）。引用格式为
path:line
、
path:start-end
、
path:Symbol[:line]
或
cmd:
/
output:
。无需为琐碎陈述添加标签。

Human Feedback Loop

人工反馈循环

Corrections are recorded as Feedback Items (
templates/human-feedback.md
) under 
.reposkillopt/feedback/
and applied to the artifact in place. Repository-specific corrections stay repository-scoped.
修正内容记录为反馈项（
templates/human-feedback.md
），存储在
.reposkillopt/feedback/
目录下，并直接应用到产物中。仓库专属的修正内容仅限该仓库范围内使用。

Skill Convergence Loop

Skill收敛循环

When recurrent feedback (≥3 related items) marked candidate-for-generic reveals a weakness in this skill, draft a Skill Edit Proposal (
templates/skill-edit-proposal.md
). It may be accepted only after passing the validation gate (
rubric/validation-gate.md
): regenerate the artifacts for a disjoint held-out reference set with no per-dimension rubric regression (see 
rubric/asis-architecture-rubric.md
) and the deterministic checks still passing. Nothing is silently promoted; acceptance bumps the version + adds a CHANGELOG entry. Mirror every accepted edit into the four adapters (adapter-equivalence).
当标记为候选通用模式的重复反馈（≥3个相关项）暴露出本Skill的缺陷时，起草Skill编辑提案（
templates/skill-edit-proposal.md
）。只有通过验证检查（
rubric/validation-gate.md
）后才可被接受：针对一组不相交的预留参考集重新生成产物，确保每个维度的评分标准无退化（参见
rubric/asis-architecture-rubric.md
），且确定性检查仍通过。所有内容均需明确升级；接受后需更新版本并添加CHANGELOG条目。将每个已接受的编辑同步到四个适配器中（适配器等效性）。