Back to Details

c4-codebase-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

C4 Model Codebase Documentation Skill

C4 Model代码库文档生成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.
该Skill帮助Agent检查代码库并生成实用的C4风格架构文档。当仅通过代码检查无法确定系统边界、职责、运行时拓扑或业务意图时，应结合代码仓库中的证据和针对性的后续问题来完成文档。
该Skill应注重实用性而非教条化。目标并非将每个代码库都套入完美的四组图中，而是在合适的细节粒度下生成最清晰的架构视图。

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
当用户需要以下服务时，可使用该Skill：
  • 理解现有代码库的架构
  • 为代码仓库生成C4文档
  • 生成系统上下文、容器或组件视图
  • 用架构文档帮助新工程师快速上手
  • 从代码和基础设施定义中逆向梳理系统结构
  • 对比预期架构与实际实现的架构
当代码仓库包含以下至少部分内容时，该Skill的效果最佳：
  • 源代码
  • 基础设施即代码（Infrastructure as Code）
  • 部署描述文件
  • README或文档
  • API规范
  • CI/CD配置
  • 测试套件

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.
根据代码库的支持情况，该Skill应生成以下部分或全部内容：
  1. 系统上下文
    • 研究中的系统
    • 人类用户或角色
    • 外部系统、API、供应商或依赖项
    • 关键关系
  2. 容器视图
    • 主要可部署或可运行单元
    • 数据库、队列、前端、API、工作器、无服务器函数、数据存储
    • 它们之间的协议与交互
  3. 组件视图
    • 选定容器内的主要内部组件
    • 它们的职责与关系
  4. 配套说明
    • 从代码检查中得出的假设
    • 未解决的模糊点
    • 向用户提出的问题
    • 值得注意的架构风险或不匹配之处
  5. 可选图源码
    • Mermaid、PlantUML、Structurizr DSL或纯文本图描述
除非明确要求，该Skill无需生成完整的代码级图。仅当类、模块或包能显著提升理解时，才需提及它们。

Default operating principles

默认操作原则

1. Evidence first

1. 证据优先

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.
尽可能基于代码仓库中的可观测证据得出架构结论。优先参考：
  • 入口点
  • 路由定义
  • 包清单
  • 部署描述文件
  • 基础设施代码
  • 环境变量使用情况
  • API客户端与SDK使用情况
  • 集成测试
  • 队列/主题使用情况
  • 持久化代码
不得将猜测作为事实呈现。

2. Separate facts from inference

2. 区分事实与推论

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.
从代码中推断架构时，需明确标注为推论。
示例：
  • 观测到：代码仓库包含一个React应用、一个Express API和用于RDS实例的Terraform代码。
  • 推断：该系统可能采用基于浏览器的前端调用由PostgreSQL支持的后端API。

3. Ask only high-value questions

3. 仅提出高价值问题

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

4. 尊重系统边界

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
代码仓库并非总是整个系统。需明确说明文档的范围是：
  • 仅当前代码仓库
  • 更大平台中的单个服务
  • 包含多个系统的单体仓库（Monorepo）
  • 更广泛架构的部分实现

5. Default to useful levels of detail

5. 默认采用实用的细节粒度

Usually the most useful outputs are:
  • a System Context diagram
  • a Container diagram
  • one or two Component diagrams for key containers
Do not force component breakdowns for trivial services.
通常最有用的输出是：
  • 系统上下文图
  • 容器图
  • 针对关键容器的一到两个组件图
无需对简单服务强行进行组件拆分。

Repository analysis workflow

代码仓库分析流程

Phase 1: Establish scope

阶段1：确定范围

Start by determining what the repository appears to represent.
Look for:
  • repo name
  • README summary
  • workspace or monorepo structure
  • top-level folders
  • package manifests
  • build files
  • infrastructure folders
  • deployment folders
  • docs folders
Try to answer:
  • What system or subsystem is this?
  • Is this a full product, a service, a library, or infrastructure?
  • What is inside scope and outside scope?
If scope is ambiguous, ask the user.
首先确定代码仓库的代表内容。
查找以下内容：
  • 仓库名称
  • README摘要
  • 工作区或单体仓库结构
  • 顶层文件夹
  • 包清单
  • 构建文件
  • 基础设施文件夹
  • 部署文件夹
  • 文档文件夹
尝试回答：
  • 这是什么系统或子系统？
  • 这是完整产品、服务、库还是基础设施？
  • 哪些内容在范围内，哪些在范围外？
如果范围模糊，询问用户。

Phase 2: Identify runtime building blocks

阶段2：识别运行时构建块

Find the main executable or deployable units.
Look for:
  • web frontends
  • backend services
  • CLI tools
  • serverless functions
  • workers or scheduled jobs
  • databases
  • caches
  • queues and streams
  • search engines
  • storage buckets
  • third-party SaaS dependencies
Important note: for C4, a "container" means a deployable or runnable unit, not specifically a Docker container.
找到主要可执行或可部署单元。
查找以下内容：
  • Web前端
  • 后端服务
  • CLI工具
  • 无服务器函数
  • 工作器或定时任务
  • 数据库
  • 缓存
  • 队列与流
  • 搜索引擎
  • 存储桶
  • 第三方SaaS依赖项
重要说明：在C4模型中，“container”指可部署或可运行单元，并非特指Docker容器。

Phase 3: Identify interactions

阶段3：识别交互关系

Map how the runtime building blocks interact.
Look for:
  • HTTP clients and servers
  • SDK calls
  • message publishing or consuming
  • database access layers
  • authentication middleware
  • event handlers
  • cron or scheduler configuration
  • file or object storage access
Try to capture:
  • direction of flow
  • transport or protocol where visible
  • synchronous vs asynchronous behavior
  • trust boundaries
梳理运行时构建块之间的交互方式。
查找以下内容：
  • HTTP客户端与服务器
  • SDK调用
  • 消息发布或消费
  • 数据库访问层
  • 认证中间件
  • 事件处理器
  • 定时任务配置
  • 文件或对象存储访问
尝试记录：
  • 流向
  • 可见的传输或协议
  • 同步与异步行为
  • 信任边界

Phase 4: Infer actors and external systems

阶段4：推断参与者与外部系统

Code often reveals external systems but not always end users or business actors.
Look for:
  • auth providers
  • payment systems
  • email providers
  • cloud services
  • partner APIs
  • identity systems
  • observability systems
For actors, infer cautiously from:
  • UI labels
  • route names
  • domain language
  • role checks
  • documentation
If user personas are not obvious, ask the user.
代码通常会揭示外部系统，但不一定能体现终端用户或业务参与者。
查找以下内容：
  • 认证提供商
  • 支付系统
  • 邮件提供商
  • 云服务
  • 合作伙伴API
  • 身份系统
  • 可观测性系统
对于参与者，需谨慎从以下内容推断：
  • UI标签
  • 路由名称
  • 领域语言
  • 角色检查
  • 文档
如果用户角色不明确，询问用户。

Phase 5: Break down important containers into components

阶段5：将重要容器拆分为组件

For the most important or complex containers, identify major internal components.
Look for:
  • modules
  • packages
  • feature folders
  • controllers
  • services
  • repositories
  • adapters
  • domain layers
  • handlers
  • middleware
A good component breakdown usually focuses on responsibilities, not file-by-file enumeration.
Avoid producing a component diagram that is just a dump of folder names.
针对最重要或最复杂的容器，识别主要内部组件。
查找以下内容：
  • 模块
  • 包
  • 功能文件夹
  • 控制器
  • 服务
  • 仓库
  • 适配器
  • 领域层
  • 处理器
  • 中间件
良好的组件拆分应聚焦于职责，而非逐文件枚举。
避免生成仅罗列文件夹名称的组件图。

Phase 6: Produce documentation

阶段6：生成文档

Produce the final output with:
  • stated scope
  • assumptions
  • C4 views
  • clarifying questions if needed
  • diagram source if requested
生成最终输出，包含：
  • 明确的范围
  • 假设
  • C4视图
  • 必要的澄清问题
  • 若有请求，提供图源码

Questions the skill may ask the user

Skill可能向用户提出的问题

Ask questions only when they materially improve correctness. Prefer batching 3 to 7 questions together.
仅当问题能显著提升正确性时才提出。建议批量提出3到7个问题。

About scope

关于范围

  • Is this repository the whole system, or just one service within a larger platform?
  • Do you want the documentation to cover only what is in the repo, or also adjacent systems it depends on?
  • Is there a preferred audience for the diagrams, such as new engineers, stakeholders, or operations teams?
  • 该代码仓库是整个系统，还是更大平台中的一个服务？
  • 您希望文档仅覆盖仓库内的内容，还是也包含它依赖的相邻系统？
  • 图的目标受众是否有偏好，比如新工程师、利益相关者或运维团队？

About actors and personas

关于参与者与角色

  • Who are the primary users or operators of this system?
  • Are there distinct personas or roles, such as customer, admin, support, or partner?
  • Is there an internal operations team that should appear in the system context view?
  • 该系统的主要用户或操作者是谁？
  • 是否有不同的角色或人物，比如客户、管理员、支持人员或合作伙伴？
  • 系统上下文视图中是否需要包含内部运维团队？

About deployment/runtime topology

关于部署/运行时拓扑

  • Are the deployable units in the repo also the real runtime containers in production?
  • Are there important external pieces not represented in code here, such as managed databases, external queues, or shared gateways?
  • Is this deployed as a monolith, microservices, serverless functions, or something hybrid?
  • 仓库中的可部署单元是否也是生产环境中的实际运行时容器？
  • 是否存在代码中未体现的重要外部组件，比如托管数据库、外部队列或共享网关？
  • 该系统是作为单体应用、微服务、无服务器函数还是混合架构部署的？

About system boundaries

关于系统边界

  • What should be considered outside the system boundary for the context diagram?
  • Are shared platform services owned by another team and therefore better shown as external systems?
  • 上下文图中哪些内容应被视为系统边界之外？
  • 由其他团队负责的共享平台服务是否更适合作为外部系统展示？

About ambiguous dependencies

关于模糊依赖

  • Is this external dependency central enough to show explicitly in the diagrams?
  • Should infrastructure services like S3, Redis, or EventBridge be shown as containers inside the system or as external managed services?
  • 该外部依赖是否重要到需要在图中明确展示？
  • S3、Redis或EventBridge等基础设施服务应作为系统内的容器展示，还是作为外部托管服务展示？

About components

关于组件

  • Which container would you like the component diagram to focus on?
  • Do you want a domain-oriented breakdown, a technical-layer breakdown, or the structure that most closely matches the code?
  • 您希望组件图聚焦于哪个容器？
  • 您希望采用面向领域的拆分、技术层拆分，还是与代码结构最匹配的拆分方式？

About output format

关于输出格式

  • Do you want Mermaid, PlantUML, Structurizr DSL, or just textual documentation?
  • Would you prefer concise docs or something more explanatory and onboarding-friendly?
  • 您希望使用Mermaid、PlantUML、Structurizr DSL还是纯文本文档？
  • 您更倾向于简洁文档，还是更具解释性、便于上手的文档？

Heuristics for common codebase shapes

常见代码库形态的启发式规则

Monolith

单体应用

If the repo contains one main application plus a database, the likely outputs are:
  • Context: users, system, external integrations
  • Container: web app or API, database, maybe background worker
  • Component: controllers, services, repositories, integrations
如果仓库包含一个主应用加数据库，可能的输出是：
  • 上下文：用户、系统、外部集成
  • 容器：Web应用或API、数据库、可能包含后台工作器
  • 组件：控制器、服务、仓库、集成模块

Monorepo with frontend and backend

包含前端与后端的单体仓库

If the repo contains multiple apps or packages:
  • identify which are independently deployable
  • separate libraries from containers
  • show shared libraries only when they help explain architecture
如果仓库包含多个应用或包：
  • 识别哪些是可独立部署的
  • 将库与容器区分开
  • 仅当共享库有助于解释架构时才展示它们

Serverless system

无服务器系统

For serverless architectures:
  • group functions into meaningful runtime containers where appropriate
  • avoid diagramming every function unless the user explicitly wants that level of detail
  • show API Gateway, queues, buckets, event buses, and data stores where relevant
  • consider "API", "Async worker", and "Scheduled processor" as possible containers even if implemented as multiple functions
对于无服务器架构：
  • 酌情将函数分组为有意义的运行时容器
  • 除非用户明确要求，否则避免为每个函数绘图
  • 展示相关的API Gateway、队列、存储桶、事件总线和数据存储
  • 即使由多个函数实现，也可将“API”、“异步工作器”和“定时处理器”视为可能的容器

Microservices

微服务

For microservices repos:
  • show each independently deployable service as a container
  • identify service-to-service communication paths
  • be careful not to confuse libraries or packages with services
对于微服务仓库：
  • 将每个可独立部署的服务作为容器展示
  • 识别服务间的通信路径
  • 注意不要将库或包与服务混淆

Library or SDK

库或SDK

If the repo is primarily a library, full C4 documentation may be inappropriate. In that case:
  • explain that the repository is not itself a complete runtime system
  • document its role in a larger context if the user provides that context
  • optionally create a smaller context and component view for the library itself
如果仓库主要是一个库，完整的C4文档可能并不合适。此时：
  • 说明该仓库本身并非完整的运行时系统
  • 如果用户提供相关上下文，记录其在更大系统中的角色
  • 可选为库本身创建小型上下文和组件视图

Output template

输出模板

Use the following structure by default.
默认使用以下结构。

1. Scope

1. 范围

State what is being documented and any important scope boundaries.
Example:
This documentation covers the architecture implied by the current repository. It appears to represent the backend service and its deployment configuration, but not the full end-user platform.
说明文档覆盖的内容及重要的范围边界。
示例：
本文档基于当前代码仓库推导架构。它似乎代表后端服务及其部署配置，但不包含完整的终端用户平台。

2. Observations from the codebase

2. 代码库观测结果

Summarize the strongest concrete signals found in the repository.
Example:
  • React frontend in 
    apps/web
  • Node.js API in 
    apps/api
  • PostgreSQL dependency and migration scripts
  • Terraform modules for VPC, ECS, RDS, and SQS
  • background worker consuming queue messages
总结代码仓库中最明确的信号。
示例：
  • apps/web
    中的React前端
  • apps/api
    中的Node.js API
  • PostgreSQL依赖项及迁移脚本
  • 用于VPC、ECS、RDS和SQS的Terraform模块
  • 消费队列消息的后台工作器

3. Assumptions and inferences

3. 假设与推论

List anything that is inferred rather than directly observed.
列出所有通过推断而非直接观测得出的内容。

4. System Context

4. 系统上下文

Provide a short explanation and, if requested, a diagram definition.
提供简短说明，若有请求则提供图定义。

5. Container view

5. 容器视图

Provide a short explanation and, if requested, a diagram definition.
提供简短说明，若有请求则提供图定义。

6. Component view

6. 组件视图

Focus on one or more important containers only.
仅聚焦于一个或多个重要容器。

7. Open questions

7. 未解决问题

List unresolved ambiguities that would improve the documentation if clarified.
列出未明确的模糊点，澄清这些问题可提升文档质量。

8. Suggested next refinements

8. 建议后续优化方向

Recommend what to clarify or document next.
建议下一步需要澄清或记录的内容。

Diagramming guidance

绘图指南

General guidance

通用指南

Every diagram should:
  • have a clear title
  • define its scope
  • use descriptive box labels
  • label relationships with short verbs or phrases
  • include key technology details only where useful
  • avoid visual clutter
每张图应：
  • 有清晰的标题
  • 定义其范围
  • 使用描述性的框标签
  • 用简短动词或短语标注关系
  • 仅在有用时包含关键技术细节
  • 避免视觉杂乱

Labeling examples

标签示例

Prefer:
  • Web Application\nReact SPA used by customers
  • Orders API\nNode.js service handling checkout and order retrieval
  • PostgreSQL\nStores users, orders, and payment state
Over vague labels like:
  • Frontend
  • Backend
  • DB
推荐：
  • Web应用\n客户使用的React SPA
  • 订单API\n处理结账与订单查询的Node.js服务
  • PostgreSQL\n存储用户、订单与支付状态
避免模糊标签，如：
  • 前端
  • 后端
  • 数据库

Relationship examples

关系示例

Prefer labels like:
  • Submits order via HTTPS
  • Reads product catalog
  • Publishes job messages
  • Verifies identity token
Avoid unlabeled arrows.
推荐标签如：
  • 通过HTTPS提交订单
  • 读取产品目录
  • 发布任务消息
  • 验证身份令牌
避免无标签箭头。

How to treat infrastructure and managed services

基础设施与托管服务的处理方式

The skill should use judgment when placing cloud resources in C4 diagrams.
在C4图中展示云资源时，Skill应运用判断。

Good candidates for container-level visibility

适合在容器级展示的资源

Show these when they materially affect architecture:
  • primary databases
  • message queues
  • event buses
  • object storage used as a core workflow element
  • caches
  • search engines
  • identity providers
  • major external APIs
当以下资源对架构有重大影响时，应展示：
  • 主数据库
  • 消息队列
  • 事件总线
  • 作为核心工作流元素的对象存储
  • 缓存
  • 搜索引擎
  • 身份提供商
  • 主要外部API

Usually too low-level unless relevant

通常无需展示，除非相关

These are often implementation details unless central to the design:
  • subnets
  • security groups
  • IAM roles
  • autoscaling policies
  • log groups
  • CI runners
以下内容通常是实现细节，除非是设计核心：
  • 子网
  • 安全组
  • IAM角色
  • 自动扩缩容策略
  • 日志组
  • CI运行器

Boundary judgment

边界判断

When in doubt:
  • if the team owns and reasons about it as part of the application architecture, it may belong inside the system boundary
  • if it is a platform dependency provided by another team or vendor, it may be better as an external system
若不确定：
  • 如果团队将其作为应用架构的一部分拥有并考量，可置于系统边界内
  • 如果是由其他团队或供应商提供的平台依赖项，更适合作为外部系统

Quality bar for the skill

Skill质量标准

A good result should be:
  • faithful to the codebase
  • explicit about uncertainty
  • useful to humans
  • free from box-and-arrow soup
  • focused on important runtime structure
A poor result would:
  • confuse packages with deployable units
  • invent actors with no evidence
  • over-document trivial details
  • produce diagrams with many unlabeled arrows
  • blur the boundary between facts and guesses
优质结果应：
  • 忠实于代码库
  • 明确标注不确定性
  • 对人类实用
  • 避免杂乱的框箭头图
  • 聚焦于重要的运行时结构
劣质结果会：
  • 将包与可部署单元混淆
  • 无依据地虚构参与者
  • 过度记录琐碎细节
  • 生成大量无标签箭头的图
  • 模糊事实与猜测的边界

Example interaction pattern

示例交互模式

Example opening

示例开场

I inspected the repository and I can already see a frontend app, an API service, a worker, and some infrastructure code for a PostgreSQL database and SQS queue. I can draft a first-pass System Context and Container view from that.
Before I finalize it, I need to clarify a few things that the code does not make fully explicit:
  1. Is this repository the entire system or only one part of a larger platform?
  2. Who are the main user roles that should appear in the context diagram?
  3. Should managed AWS services like SQS and S3 appear inside the system boundary, or would you prefer them shown as external supporting services?
  4. Which container would you like me to break down at the Component level?
我已检查该代码仓库，发现其中包含一个前端应用、一个API服务、一个工作器，以及用于PostgreSQL数据库和SQS队列的基础设施代码。基于这些信息，我可以初步生成系统上下文和容器视图。
在最终定稿前，我需要澄清一些代码未明确说明的内容：
  1. 该代码仓库是整个系统，还是更大平台的一部分？
  2. 上下文图中应展示哪些主要用户角色？
  3. SQS和S3等托管AWS服务应置于系统边界内，还是作为外部支持服务展示？
  4. 您希望我针对哪个容器进行组件级拆分？

Example follow-up behavior

示例后续操作

If the user does not answer every question, continue with a best-effort draft and clearly note the assumptions.
如果用户未回答所有问题，继续生成最佳版本的草稿，并明确标注假设。

Recommended default deliverables

推荐默认交付内容

Unless the user asks otherwise, the skill should try to return:
  • one concise System Context view
  • one concise Container view
  • one Component view for the most central container
  • one short narrative explaining assumptions and open questions
If the system is large, propose documenting it incrementally rather than forcing everything into one response.
除非用户另有要求，Skill应尽量返回：
  • 一份简洁的系统上下文视图
  • 一份简洁的容器视图
  • 一份针对核心容器的组件视图
  • 一份说明假设与未解决问题的简短文档
如果系统规模较大，建议逐步记录，而非强行在一次响应中涵盖所有内容。

Optional output formats

可选输出格式

When asked, the skill may emit diagrams as:
  • Mermaid
  • PlantUML with C4 extensions
  • Structurizr DSL
  • plain Markdown with structured sections
If the user has no preference, default to Markdown narrative plus Mermaid.
当用户要求时，Skill可生成以下格式的图：
  • Mermaid
  • 带C4扩展的PlantUML
  • Structurizr DSL
  • 带结构化章节的纯Markdown
如果用户无偏好，默认返回Markdown说明加Mermaid图。

Final instruction to the agent

给Agent的最终指令

Inspect the codebase carefully, infer architecture conservatively, and use targeted questions to resolve what code cannot tell you. Produce C4 documentation that is precise, readable, and honest about uncertainty.
仔细检查代码库，保守地推断架构，使用针对性问题解决代码无法说明的内容。生成精确、可读且如实反映不确定性的C4文档。