oleg-lukasonokandClaude Opus 5.5
d56e784e97
VS Code extension that previews Archify diagrams from their JSON sources (live, as you type) and opens rendered Archify HTML in a viewer tab. Bundles the Archify 3.0.1 renderer and runs it on VS Code's Node runtime. Adds validation diagnostics, JSON schema help, source-link navigation, export saving, render-to-file and open-in-browser commands. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
106 lines
6.4 KiB
Markdown
106 lines
6.4 KiB
Markdown
# Repository-backed architecture authoring
|
|
|
|
Use this reference when a diagram must explain a real repository. The source is
|
|
the authority for responsibilities, calls, boundaries, and persistence. The
|
|
diagram is complete when the requested meaning is covered and every asserted
|
|
fact has supporting source evidence.
|
|
|
|
## Explore on demand
|
|
|
|
1. **Freeze identity.** From the target repository, record `git rev-parse
|
|
HEAD`, `git remote get-url origin`, and `git status --short`. Remove HTTP(S)
|
|
userinfo (including usernames, passwords, and tokens) before recording the
|
|
origin or placing it in the candidate. Preserve its transport, port, path and
|
|
`.git` suffix; do not rewrite an internal SSH origin as HTTPS. Pin the credential-free URL and
|
|
forty-character revision in `meta.repository`. Use `link_mode: "local-only"`
|
|
for an SSH origin, unsupported forge, intentionally local-only source links,
|
|
or a local fixture whose HTTPS URL is only a repository identity; retain the
|
|
URL and revision. Web links require a supported GitHub or Gitee HTTPS origin. If the
|
|
worktree is dirty, record the changed paths. Repository evidence is verified
|
|
against committed bytes at the pinned revision, not working-tree edits:
|
|
inspect a clean checkout at that revision for any cited changed path. Do not
|
|
present uncommitted bytes as evidence for `HEAD`; `local-only` does not record
|
|
a verifiable snapshot of those bytes.
|
|
|
|
2. **Map the slice.** Use project instructions, manifests, entry points,
|
|
registrations, and deployment configuration to locate candidate runtime
|
|
units. Read the entry, configuration, and modules relevant to the request.
|
|
Follow imports and call sites
|
|
until the requested responsibility reaches its actual input, output, or
|
|
side effect. Read a small connected slice instead of scanning the repository
|
|
for a convenient label.
|
|
|
|
3. **Trace ownership.** Derive runtime and I/O relationships from the observed
|
|
actor, operation, and target at their call sites; deployment and trust
|
|
relationships use the corresponding configuration or enforcement evidence. Distinguish the controller requesting
|
|
an operation from the runtime that executes it and the store receiving bytes.
|
|
For a file or database edge, the source must identify its actual reader or
|
|
writer; a responsibility statement such as “maintains tasks” does not prove
|
|
direct I/O. Keep these facts with the source locations while reading, without
|
|
a separate planning artifact. Choose which distinctions need separate
|
|
nodes using [Composition and meaning](authoring-defaults.md#composition-and-meaning);
|
|
discovering an implementation role does not automatically add it to the overview.
|
|
A configured provider, an injected adapter, a local stub, and a durable
|
|
service are different claims; label the one the source supports.
|
|
|
|
4. **Record evidence while reading.** Keep exact repository-relative paths and
|
|
inclusive line ranges for each component and meaningful relationship. Follow
|
|
actual branches, retries, fallbacks, and error handling. A function that is
|
|
exported or configured but never called by the normal path is an optional
|
|
capability, not a required runtime edge. For a claim about authoritative
|
|
state change or control ownership, trace to the actual write or execution
|
|
site and the conditions that permit it; an upstream caller alone does not
|
|
establish those conditions.
|
|
|
|
5. **Name uncertainty.** Write unresolved questions beside the claim they
|
|
affect: for example, “`writeFile` is called here; durability is unknown.”
|
|
Resolve a question by reading the next relevant source range or preserve it
|
|
as an explicit unknown. Never turn a label, package description, or config
|
|
value into an unobserved service or behavior.
|
|
|
|
Stop exploring when every requested responsibility, relationship, and boundary
|
|
has supporting source entailment and the remaining unknowns cannot change that
|
|
coverage. There is no node, edge, citation, view, card, or boundary count to
|
|
hit. Do not add a summary step merely to signal completion.
|
|
|
|
Batch independent relevant files when known. Each additional read should answer
|
|
an unresolved question that can change the diagram. Reuse concise facts and
|
|
their source ranges already verified in this task; across revisions, recheck
|
|
the affected entry points, configuration, dependencies, and evidence.
|
|
|
|
## Choose an example by structure
|
|
|
|
Select the main example in the [Type router](../SKILL.md#type-router) before
|
|
loading its content, using the request and repository metadata already needed
|
|
for source inspection. Selection fits the existing read batch and needs no extra
|
|
message, command, or repository-wide scan. For mixed or unclear tasks, use the
|
|
requested responsibilities and entry points as they become known in normal
|
|
inspection; keep their actual roles. Read another example when a necessary
|
|
capability remains unexplained. Examples teach shape, not facts: a library need
|
|
not acquire filesystem nodes, and finished showcases still follow the
|
|
first-draft automatic-routing rule.
|
|
|
|
## Author from evidence
|
|
|
|
Use the mode's complete JSON shape, including repository identity,
|
|
components, and connections; every repository-backed component needs supporting source
|
|
references, while boundaries or cards are added only when they
|
|
answer a real reader question. Let automatic routes and automatic
|
|
viewBox sizing work first. Keep the primary path readable, put exception paths
|
|
beside their owner, and leave filesystem stores outside a control boundary when
|
|
the source shows a separate responsibility.
|
|
|
|
An existing example teaches field shape, not facts or arbitrary values. It does
|
|
not authorize a new boundary kind, a long note, a viewBox size, or a route
|
|
control. Consult the specific mode schema and `schemas/common.schema.json`
|
|
whether or not the selected example already contains the field; use the
|
|
schema's enum, length, identifier, and repository rules. Architecture
|
|
boundaries currently use `kind: "region"` or `kind: "security-group"`; source
|
|
references use `path`, `line`, and optional `end_line`.
|
|
|
|
Repository-backed components need concise, truthful `sources` references. Preserve
|
|
control ownership when summarizing filesystem I/O: the code that reads or writes
|
|
a file owns that action, while a pure in-memory transform receives and returns
|
|
values. This fact-check does not require a separate overview node for every helper. Use the existing examples for valid field shape, then replace all
|
|
identifiers, wording, source paths, and claims with inspected repository facts.
|