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

architecture-diagrams

Author and visually review evidence-based software architecture diagrams as D2 v0.7.1 source rendered with ELK to canonical SVG.

unoplat · 已有 AI 审核记录

安装与使用

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

npx skills add unoplat/unoplat-code-confluence --skill architecture-diagrams

技能说明


name: architecture-diagrams description: >- Author and visually review evidence-based software architecture diagrams as D2 v0.7.1 source rendered with ELK to canonical SVG.

D2 Architecture Diagrams

Use this guide to create or review the repository architecture from current, explicit evidence. The diagram must answer one architectural question clearly; it is not an exhaustive code inventory.

This skill contains authoring guidance and URL-only icon catalogs. It has no executable skill scripts. Runtime artifact ownership, console tools, and the validate_architecture finish rule are defined by the agent instructions—follow those for what you may write and which tools to call. This skill defines how to author and visually approve architecture.d2.

Source format and render expectations

  • Author unfenced D2 only in architecture.d2. Do not wrap the source in a Markdown document or code fence.
  • Target D2 v0.7.1 with ELK. The validator owns syntax checks, version enforcement, rendering, atomic architecture.svg replacement, and digests.
  • The only persisted render is SVG. The validator may attach a temporary visual preview of the exact generated SVG for review; that preview is not a repository artifact and must not be written into the repo.
  • Do not judge final layout from D2 source alone. Inspect the validator preview against the checklists in this skill. Any source edit after a successful validation requires another validate + visual review (see agent finish rule and §8 below).

1. Build an evidence inventory first

Read every explicitly listed, fresh app_interfaces.md artifact. Consult only the minimal source, configuration, deployment, or infrastructure evidence needed to confirm a claim. Do not use stale or unlisted interface artifacts and do not invent components, protocols, dependencies, ownership, or deployment boundaries.

Before writing D2, record a concise inventory:

  • Nodes: actors, entry points, deployable applications and services, data stores, queues, and external systems.
  • Boundaries: supported ownership, deployment, trust, network, or subsystem boundaries.
  • Relationships: source, target, semantic direction, action label, and interaction type.
  • Scope: the primary question, abstraction level, and deliberate omissions.
  • Visual vocabulary: the meaning of shapes, colors, line patterns, and icons.

Treat the relationship inventory as a non-regression checklist. Layout or style changes must never silently remove, merge, reverse, or mislabel an interaction. Co-location in a deployment file proves membership, not communication.

Model independently meaningful runtime nodes. Omit package directories, shared source modules, and library-only codebases unless the chosen architectural question specifically concerns components inside one runtime.

2. Keep one abstraction level

Choose one primary level and architectural question:

  • Context: people and external systems around the system.
  • Container: independently deployable applications, services, and stores.
  • Component: important modules inside one application or service.
  • Deployment: runtime nodes, environments, networks, and infrastructure.
  • Data flow: production, transformation, persistence, and consumption.

Do not combine all levels in one image. Prefer a focused system-level diagram; if multiple views are truly required, use D2 boards or composition rather than crowding unrelated detail together.

Responsibility-oriented container groupings often include consumers and entry points, repository-owned backend services, platform/infrastructure, and external services. Create only evidence-backed, non-empty groups. These roles are useful organization aids, not mandatory decorative boxes.

3. Use stable keys and meaningful containers

Separate machine-friendly keys from reader-facing labels. Relationships must reference keys, including qualified keys across containers:

client_tier: Client tier {
  web_app: Web application
}

service_tier: Service tier {
  order_api: Order API
}

client_tier.web_app -> service_tier.order_api: submit order

Use lower-case stable keys that survive label changes. Keep labels concise and specific. Use containers only when they communicate ownership, deployment, trust, runtime, network, or internal/external responsibility. Keep nesting shallow unless another level adds architectural meaning.

4. Establish topology before styling

Add nodes, boundaries, and evidence-backed relationships before colors, icons, or spacing controls. Select one global direction from the dominant reading order:

direction: right

users -> web_app: send requests
web_app -> api: call API
api -> worker: enqueue job
worker -> database: persist result

Use right when the dominant flow is users → application → dependencies. Use down when it is entry points → processing → persistence. ELK is hierarchical: nested containers do not have independent flow directions. Render promising global directions rather than judging layout from source alone.

Declare the dominant semantic flow in the chosen reading direction when possible. Keep edge labels short, action-oriented, and evidence-backed, such as send request, publish event, read profile, or persist result. Avoid endpoint-name repetition and prose paragraphs on edges.

Preserve the true semantic arrow direction. If available evidence establishes a relationship but not direction, do not invent one.

Reverse and feedback flows

First render the semantically direct edge:

notification_service -> web_app: send live update

A literal reverse edge can create a large loop in a layered layout. Only when it materially damages readability may you declare the edge in the layout direction and place the visible arrowhead at its source:

# Ranked forward for ELK; the visible arrow still points to web_app.
web_app -> notification_service: send live 
阅读完整来源 ↗