enterprise-architecture

enterprise-architecture — a Claude Code Agent Skill

A unified enterprise & software architecture skill for Claude Code, grounded in four open-source standards instead of one. It helps Claude produce architecture work the way the standards intend it: diagrams as code, documentation as code, decisions as records, and one traceable model underneath.

🌐 Live site & eval examples: https://gauravs19.github.io/enterprise-architecture-skill/

---

Contents

• Why this exists
• The theory — frameworks in practice
• The mental model — four frameworks, four altitudes
• The four frameworks
• The four modes
• Traceability — one model under everything
• Install
• Usage
• The consistency linter
• Eval results
• Repository layout
• License

---

Why this exists

The open-source ecosystem has excellent single-purpose skills — C4+ArchiMate plugins, arc42 toolkits, ADR generators — but none unify all four frameworks, and none cover TOGAF or architecture review. This skill fills that gap: one skill that picks the right framework at the right altitude, produces everything as code, and keeps a single traceable model under every diagram, doc, and decision.

The theory — frameworks in practice

There's a large gap between how EA frameworks are marketed and how they're used. Almost no organization runs TOGAF or Zachman "by the book" — full-ceremony adoption usually collapses under its own weight. What survives contact with reality is selective borrowing:

Where frameworks genuinely earn their keep: M&A integration (two of everything — what to kill?), cloud migration programs (baseline/target/gap keeps multi-year work coherent), vendor/platform decisions (ADRs make them defensible two years later), regulatory traceability (requirement → capability → app → deployment), and fighting shadow-IT sprawl (a maintained app landscape is the only way anyone knows what exists).

Frameworks are scaffolding, not the building — the value is a handful of living artifacts (a capability map, an application landscape, a decision log, a roadmap), not framework compliance.

→ Full write-up with four worked case studies and the six EA anti-patterns: Frameworks in practice

The mental model — four frameworks, four altitudes

These frameworks are not competitors — they answer different questions. Knowing which one fits the question is most of the skill.

• C4 zooms into one system.
• ArchiMate zooms out to the enterprise.
• TOGAF is the method for changing it.
• arc42 / ADR is how you narrate it.

They compose: an arc42 doc embeds C4 diagrams and links ADRs; a TOGAF engagement produces ArchiMate models and ADRs as deliverables.

---

The four frameworks

Each framework is explained in full — origin, structure, worked examples, what practitioners actually keep — in the frameworks-in-practice guide. For "which framework should I use?" questions, the skill itself loads references/choosing-frameworks.md.

---

The four modes

The skill routes any architectural request to one of four modes — you don't have to name a framework.

Mode 3 grades against ISO/IEC 25010 quality attributes (performance, security, reliability, maintainability, …) plus EA principles, and returns findings categorized Critical / Major / Minor / Suggestion, each with evidence and a concrete remediation, then a verdict (Approved / Approved-with-changes / Needs-revision) — not personal taste.

→ Review rubric: references/review-rubric.md

---

Traceability — one model under everything

Give every architectural element a stable, human-readable ID and reuse it across diagrams, docs, and ADRs. This is what turns a pile of pictures into an actual model.

• ID scheme (URN-style): ea:{org}:{system}:{kind}:{name}
  • e.g. ea:acme:checkout:container:payment-api, ea:acme:enterprise:capability:billing
  • kind ∈ person, system, external, container, component, capability, app, node, decision …
• When a repo exists, persist these in an architecture/ folder (one file per significant artifact, or a Structurizr workspace as the model-of-record) so they're diff-able and greppable, and reference the same ID from the arc42 doc and the ADRs.
• Before inventing a new element, check whether it already exists under another name and reuse the ID. Two names for one thing is the most common EA documentation defect.

---

Install

Option A — clone into your Claude Code skills directory: