跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

ln-22-current-architecture-documenter

Documents current architecture from implementation evidence; does not propose a target or audit fitness.

levnikolaevich · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add levnikolaevich/claude-code-skills --skill ln-22-current-architecture-documenter

技能说明


name: ln-22-current-architecture-documenter description: "Documents current architecture from implementation evidence; does not propose a target or audit fitness."

Current Architecture Documenter

Goal: Produce a trustworthy snapshot of the architecture implemented in the checked-out repository. Document what exists and how it behaves; do not score it, prescribe a target architecture, repair code, or turn intended diagrams into facts.

Execution contract: The ordered checkboxes are the Definition of Done. Track every item internally as PENDING, PROVEN with concrete evidence, CLEARED with evidence that its condition is absent, or UNPROVEN with a gap; reading, delegation, or tool failure is not proof. Reconcile items after each section. Before returning, resolve all PENDING and count only PROVEN and CLEARED; apply the skill's verdict and approval rules to every gap. Preserve user intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without silently skipping checks. Preserve dependency and safety ordering; otherwise choose the verification method appropriate to each obligation. Treat equivalent user or repository evidence as valid input; another skill, named artifact, or complete lifecycle is not a prerequisite. Preserve source requirement and decision identifiers when available. Bind reused evidence to the relevant source version, dirty changes, configuration, and environment; invalidate only affected claims after a change. On continuation, reconcile the task, existing authorization, current state, and unresolved evidence before resuming. For long work, return a compact continuation record or update an already authorized task artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and authority to perform an external action. Prepare authorized work before any required approval. If an instruction prevents progress, identify its exact source and explain the unresolved boundary; do not invent an approval gate from general caution.

Tool Routing

NeedPreferred capabilityFallback
Snapshot identity and worktree stateGit status, branch, remote, and HEADRecord the supplied snapshot as UNVERIFIED
Structure and configurationNative listing, search, manifests, and direct file readsNarrow manual inspection
Symbols, dependencies, and consumersLanguage intelligence or resolved dependency toolingSearch definitions, registrations, imports, and callers
Runtime and deployment topologyEntrypoints, IaC, containers, CI, configuration, and runtime evidenceMark deployment relationships UNKNOWN
Document mutationMinimal patch to the approved architecture documentReturn BLOCKED if no writable path is authorized

Prefer local evidence over remote repository state. A path, diagram, or naming convention is a lead until executable wiring or an authoritative contract confirms it.

Artifact Rules

  • Reuse a clear current-state architecture document; otherwise use docs/architecture/current-state.md.
  • Anchor the document to remote, branch, HEAD, worktree state, and observation date.
  • Cite material claims with file paths, symbols, commands, or configuration keys.
  • Label claims OBSERVED, DOCUMENTED, INFERRED, or UNKNOWN.
  • Separate actual structure from intended target design and from audit findings.
  • Map the declared system scope at a coarse level first, then deepen only what explains its critical behavior; do not expand a bounded request into a repository-wide inventory.
  • Prefer responsibility-oriented descriptions over exhaustive file inventories.
  • Record the evidence cutoff so readers can distinguish uninspected scope from genuine absence.
  • Keep volatile counts or inventories only when they affect architectural understanding.

Checklist

1. Establish the Documentation Contract

  • Resolve repository scope, intended readers, approved destination, required depth, and language.
  • Read repository instructions and record snapshot identity plus dirty-worktree limitations.
  • Search for existing current-state, baseline, target-design, decision, diagram, and deployment artifacts.
  • Reuse an unambiguous current-state document or select the default path without duplicating project knowledge.
  • Keep the run read-only except for the approved architecture document.

2. Map the System Breadth

  • Identify languages, frameworks, package roots, generated surfaces, and canonical build or run commands from manifests and CI.
  • Identify users, external systems, entrypoints, applications, services, processes, workers, scheduled jobs, and deployment units.
  • Map major domains or modules, responsibilities, ownership, and dependency direction.
  • Map data stores, caches, queues, files, external APIs, schemas, and systems of record.
  • Record public interfaces, runtime discovery, registration, configuration composition, and environment boundaries.
  • Record build, deploy, scale, and failure boundaries without inferring independence from directory names.

3. Trace Critical Behavior

  • Select representative critical flows based on business importance and architectural reach.
  • Trace each flow from actor or trigger through entrypoint, runtime coordination, domain behavior, persistence or integration, and observable outcome.
  • Record synchronous and asynchronous hops, transaction ownership, consistency, retry, timeout, idempotency, and error propagation where evidenced.
  • Describe deployment, startup, shutdown, health, observability, and recovery paths visible from repository evidence.
  • Deepen only subsystems whose complexity or uncertainty affects architectural understanding; keep ordinary implementation detail out of the architecture document.

4. Write the Current-State Artifa

阅读完整来源 ↗