c4-codebase-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

# C4 Model Codebase Documentation Skill

## Purpose

This skill helps an agent inspect a codebase and produce useful C4-style architecture documentation. It should combine evidence from the repository with targeted follow-up questions whenever code inspection alone is not enough to determine system boundaries, responsibilities, runtime topology, or business intent.

The skill should be pragmatic rather than dogmatic. The goal is not to force every repository into a perfect set of four diagrams, but to produce the clearest possible architecture view at the right level of detail.

---

## When to use this skill

Use this skill when the user wants to:

* understand the architecture of an existing codebase
* produce C4 documentation for a repository
* generate a system context, container, or component view
* onboard new engineers with architecture docs
* reverse engineer system structure from code and infrastructure definitions
* compare intended architecture with implemented architecture

This skill works best when the repository includes at least some of the following:

* source code
* infrastructure as code
* deployment descriptors
* README or docs
* API specifications
* CI/CD configuration
* test suites

---

## What this skill should produce

The skill should aim to produce some or all of the following, depending on what the codebase supports:

1. **System Context**

   * the system under study
   * human users or personas
   * external systems, APIs, providers, or dependencies
   * key relationships

2. **Container view**

   * main deployable or runnable units
   * databases, queues, frontends, APIs, workers, serverless functions, data stores
   * protocols and interactions between them

3. **Component view**

   * major internal components within a selected container
   * their responsibilities and relationships

4. **Supporting narrative**

   * assumptions made from code inspection
   * unresolved ambiguities
   * questions for the user
   * notable architectural risks or mismatches

5. **Optional diagram source**

   * Mermaid, PlantUML, Structurizr DSL, or plain text diagram descriptions

Unless explicitly requested, the skill does **not** need to generate a full Code-level diagram. It may mention classes, modules, or packages only when that materially improves understanding.

---

## Default operating principles

### 1. Evidence first

Base architectural claims on observable evidence from the repository where possible. Prefer:

* entrypoints
* routing definitions
* package manifests
* deployment descriptors
* infrastructure code
* environment variable usage
* API clients and SDK usage
* integration tests
* queue/topic usage
* persistence code

Do not present guesses as facts.

### 2. Separate facts from inference

When inferring architecture from code, clearly label it as an inference.

For example:

* **Observed**: The repository contains a React app, an Express API, and Terraform for an RDS instance.
* **Inferred**: The system likely uses a browser-based frontend calling a backend API backed by PostgreSQL.

### 3. Ask only high-value questions

When code inspection is insufficient, ask concise, high-leverage questions in batches. Avoid interrogating the user for details that are probably discoverable in the code.

### 4. Respect system boundaries

A repository is not always the whole system. Be explicit about whether the documented scope is:

* this repository only
* a single service within a larger platform
* a monorepo containing multiple systems
* a partial implementation of a broader architecture

### 5. Default to useful levels of detail

Usually the most useful outputs are:

* a System Context diagram
* a Container diagram
* one or two Component diagrams for key containers

From lmammino/c4-codebase-architecture-skill, MIT.