Skip to content

Ai automation

Quick Summary

Six Claude Code skills automate the tedious parts of architecture documentation: creating systems, adding containers, generating technical pages, auditing entity coverage, running Well-Architected reviews, and validating branch changes. Every software system on this site was generated using these skills.

This Site Is the Proof

The BelFoot FC workspace is not a hand-crafted example -- it is the output. Every software system definition, container relationship, and documentation page you see on this site was generated using the AI skills described below. The 28 software systems, 13 bounded contexts, and deployment views were created through a combination of /c4-add-system, /c4-add-container, and /c4-document-system, then assessed with /c4-audit-system, /c4-review, and /c4-validate-changes.

Why Plain Text Makes This Possible

Traditional architecture lives in diagrams -- Visio files, Lucidchart canvases, PowerPoint slides. An AI agent cannot read those. This framework stores everything as plain text: Structurizr DSL for system definitions, Mermaid for domain diagrams, and Markdown for documentation. An AI agent reads, understands, and modifies all of it just as easily as a developer reads source code.

Architecture Skills

/c4-add-system -- Create a Software System

Given a product submission (name, description, tech stack, repositories), Claude generates the full Structurizr DSL definition: software system, containers with technology tags, relationships, and a 0000-introduction.md documentation page with business capabilities, data entities, and reference links.

Input: A product submission form with name, description, tech stack, and repository URLs.

Output: A complete DSL block and documentation page -- ready to commit. Browse any software system on this site (e.g., Player Performance, Ticketing Platform) to see real output from this skill.

/c4-add-container -- Add a Container to an Existing System

Given a container name, technology, and purpose, Claude adds it to an existing software system -- writing the container block, inferring sensible relationships to peers inside and outside the system, and tagging it correctly for styling.

Input: A system name plus the new container's name, technology stack, and role.

Output: An updated DSL block with the new container and its relationships -- consistent with how peer containers in the same system are modeled.

/c4-document-system -- Generate Technical Documentation

Every container in the DSL has a "Repository" property pointing at its source repo (GitHub or Azure DevOps). /c4-document-system uses that URL to pull the latest code, analyze real API endpoints, data models, authentication patterns, and infrastructure, and write a 0001-technical.md page. The output is grounded in what the code actually does -- not what an LLM thinks it might do.

Input: A software system name. The skill resolves the container's Repository URL automatically.

Output: A technical documentation page with endpoint tables, data model descriptions, authentication details, and infrastructure notes. The same 0001-technical.md becomes the ground-truth reference the downstream skills (c4-audit-system, c4-review, c4-validate-changes) read.

See it in action: Open the Ticketing Platform page and select the Technical tab -- that entire section was generated by /c4-document-system from the container's source repo.

/c4-audit-system -- Audit Entity Coverage

Claude compares architecture documentation against the actual code in a repository. It identifies entities that exist in code but are missing from docs, entities documented but no longer in code, and discrepancies in descriptions or relationships.

Input: A software system name and its repository.

Output: An audit report listing gaps, mismatches, and recommendations.

/c4-review -- Run a Well-Architected Review

Claude assesses a software system (or the whole landscape) against the five Azure Well-Architected pillars: Reliability, Security, Cost Optimization, Operational Excellence, and Performance Efficiency. The output is a dated Markdown report in reviews/ with findings and recommendations per pillar.

Input: A software system name (or nothing, to review the landscape).

Output: A Markdown report saved to reviews/YYYY-MM-DD-well-architected.md -- read-only, no changes to the DSL or docs.

/c4-validate-changes -- Validate Before Pull Request

Before creating a pull request, Claude validates architecture changes against documented standards. It checks naming conventions, required properties, documentation completeness, and consistency with peer systems using the same technology stack.

Input: A branch with architecture changes.

Output: A validation report with pass/fail status and specific issues to fix.

How It Fits Into the Workflow

Each skill's output is the next one's input -- intake → detail → ground truth → drift check → assess → ship:

  1. Create a branch for an architecture change
  2. Intake with /c4-add-system for a new system, or /c4-add-container to extend an existing one
  3. Ground truth with /c4-document-system to pull technical detail from the actual code repository
  4. Drift check with /c4-audit-system to spot gaps between docs and code
  5. Assess with /c4-review for a Well-Architected report (optional, but valuable before sign-off)
  6. Ship -- validate with /c4-validate-changes, then open the pull request; CI/CD rebuilds and deploys the site on merge