AGENT SKILL

architecture-audit

Systematic architecture review workflow. Use before major feature work on an unfamiliar or inherited codebase, before scaling milestones, or as a periodic health check. Maps the system as-built (not as-documented), dispatches parallel specialist reviews, and produces an evidence-backed findings report with severity verdicts.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
architecture-audit
description
Systematic architecture review workflow. Use before major feature work on an unfamiliar or inherited codebase, before scaling milestones, or as a periodic health check. Maps the system as-built (not as-documented), dispatches parallel specialist reviews, and produces an evidence-backed findings report with severity verdicts.

03 SKILL.md 正文

Architecture Audit

The Law

AN ARCHITECTURE CLAIM WITHOUT A FILE REFERENCE IS AN OPINION.
"The service layer is tightly coupled" is not a finding.
"OrderService imports 14 concrete classes from 6 modules (src/services/order.ts:1-22),
so a payment-provider swap requires touching all 6" is a finding.

When to Use

  • Before major feature work on an inherited or unfamiliar codebase
  • Before a scaling milestone (10× users, new region, new platform)
  • After rapid growth phases where structure was sacrificed for speed
  • As a periodic health check on long-lived systems
  • NOT for greenfield design — use the architect agent and brainstorming skill instead

Audit Workflow

Step 1: Map the System As-Built

Document what the code actually does, not what the docs or diagrams claim. Read entry points, build files, and dependency manifests before any source.

## System Map — YYYY-MM-DD

**Entry points:** (servers, CLIs, cron jobs, queue consumers — with file paths)
**Modules/layers:** (as they exist in the folder structure, not the intended design)
**External dependencies:** (databases, queues, third-party APIs — where each is called from)
**Data flow:** (request → response path for the 2-3 most important operations)
**Trust boundaries:** (where unvalidated input enters, where auth is checked)

If the as-built map contradicts existing architecture docs, record every divergence — each one is a finding.

Step 2: Identify Load-Bearing Decisions

List the architectural decisions the system depends on, whether or not anyone made them deliberately:

Decision Where visible Deliberate or accidental?
Monolith vs services repo layout, deploy config
Sync vs async processing queue usage, HTTP call chains
Data ownership which modules write which tables
Coupling direction import graph between layers
State management session stores, caches, singletons

Step 3: Dispatch Parallel Specialist Reviews

Use the dispatching-parallel-agents skill. Each specialist gets the Step 1 system map plus a scoped question:

Agent Scoped question
architect Do module boundaries and coupling direction support the next 12 months of planned work?
security-reviewer Are trust boundaries enforced at every entry point in the system map?
performance-profiler Which architectural choices (N+1 patterns, sync chains, missing caches) cap throughput?
database-reviewer Does data ownership match module boundaries? Any schema shared by unrelated modules?
infra-reviewer Does the deploy topology match the code topology? Any single points of failure?

Skip a specialist only if their domain is absent (e.g., no database → no database-reviewer).

Step 4: Consolidate Findings with Evidence

Every finding must carry a file reference and a consequence:

## Finding N: <one-line statement>

**Evidence:** `path/to/file.ts:12-40` — <what the code shows>
**Consequence:** <what breaks, slows, or blocks because of this>
**Effort to fix:** S / M / L
**Risk if unfixed:** <concrete scenario, not "tech debt">

Findings without evidence are deleted, not softened.

Step 5: Classify Severity

Severity Criteria Action
CRITICAL Data loss, security boundary bypass, or scaling wall within one milestone Block feature work until addressed
HIGH Change amplification — routine features require touching 3+ modules Schedule before next major feature
MEDIUM Coupling or duplication that slows work but doesn't block it Backlog with owner
LOW Style-level structure issues Note only

Step 6: Verdict and Report

## Architecture Audit — YYYY-MM-DD

**Scope:** <what was audited>
**System map:** (Step 1 output)
**Findings:** N critical / N high / N medium / N low
**Verdict:** SOUND | SOUND-WITH-RISKS | INTERVENTION-REQUIRED

**Top 3 actions:** (ordered by risk-to-effort ratio)
Verdict Criteria
SOUND No critical or high findings — proceed with planned work
SOUND-WITH-RISKS High findings exist with agreed mitigation dates
INTERVENTION-REQUIRED Any critical finding — architecture work precedes feature work

Feed CRITICAL and HIGH findings into the writing-plans skill as remediation plans. Record accepted risks as ADRs via the architect agent so the next audit can check whether the risk materialised.

Rationalization Red Flags

  • "The architecture is fine, the team just needs to be careful" — change amplification is structural, not behavioural
  • "We'll audit after this next feature ships" — the next feature is built on the unaudited structure
  • "The diagram in the wiki shows clean layers" — audit the code, not the diagram

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k