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
）保持不变——它生成与仓库无关的仓库规范。本Skill专门针对特定仓库：它将仓库规范深化为基于证据的当前架构视图，并回答“变更会引发哪些连锁反应？”——在任何修改操作之前。它生成架构视图和变更影响（影响范围）分析，是“规划目标状态”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是否安全？”——或类似表述时触发。请勿为无关请求激活本Skill。

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.
需存在仓库规范文件（
.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.
  • 基于规范构建，结合代码验证：仓库规范是初始证据；所有架构结论均需与实际文件、配置和调用位点进行验证。
  • 所有重要结论需标注依据：每个结论需标注唯一标签——
    **[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) 读取仓库规范及其引用的入口点、清单和核心模块。
(b) 架构视图（
.reposkillopt/architecture/architecture-view.md
，遵循
templates/architecture-view.md
模板）：采用C4-style层级——上下文（系统+外部参与者）、容器（运行时/可部署单元）、组件（容器内的模块）——外加关键流程（端到端流程，每个环节附带引用）和依赖图（内部关联边的引用）。每个组件和关联边均需引用真实的
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条目。需将所有已接受的编辑同步到四个适配器中（适配器一致性）。