c4-architecture

c4-architecture スキルの概要

c4-architecture スキルは、単に箱を並べた図を描くためのものではなく、Mermaid C4 図としてソフトウェアアーキテクチャ文書を組み立てるのに役立つスキルです。特に、読む相手に合った粒度でシステムを説明できるアーキテクチャ資料が必要なエンジニア、テクニカルライター、スタッフアーキテクト、そしてチームに向いています。広い読者層にはコンテキスト、技術関係者にはコンテナ、開発者にはコンポーネント、運用担当にはデプロイメントビュー、というように使い分けやすいのが強みです。

c4-architecture は何に使うのか

c4-architecture を使うべきなのは、実際の作業が「コードベース」「サービス全体の構成」「ざっくりしたシステム説明」を、構造化されたアーキテクチャ文書へ落とし込むことにある場合です。特に、単発のホワイトボード出力ではなく、Markdown に埋め込み、バージョン管理できる図が必要なときに有効です。

向いているユースケース

この c4-architecture skill が特にフィットするのは、次のような場面です。

• 既存リポジトリをオンボーディング向けに文書化する
• ADR や技術文書向けに system context と container view を作る
• マイクロサービス、イベント駆動システム、外部依存関係を説明する
• docs サイト、wiki、pull request 向けのアーキテクチャ図を作る
• Technical Writing のワークフローで使うアーキテクチャコンテンツを作成する

汎用的な図作成プロンプトと何が違うのか

一般的なプロンプトでも図らしい出力は作れますが、このスキルはワークフローが明確で、初期値も実務寄りです。

• C4 モデルを中心に据えるため、抽象度のレベルがぶれにくい
• Context と Container を「あると便利」ではなく基本ラインとして扱う
• Mermaid C4 図の構文ガイドが含まれている
• 誤解を招く文書を公開する前に、ありがちなモデリングミスへ気づける
• マイクロサービスや複雑なシステム向けの発展パターンもカバーしている

ユーザーが最初に気にするポイント

多くのユーザーが c4-architecture をインストールしたり呼び出したりする前に確認したいのは、次の点です。

• システム理解がまだ不完全でも役立つか？ 役立ちます。少なくとも actor、主要サービス、データストア、外部システムを渡せれば使えます。
• Markdown 中心の文書作成に向いているか？ はい。Mermaid 出力がこのスキルの中核価値です。
• アーキテクチャに深い専門知識がないテクニカルライターにも有用か？ はい。レベル分けと典型的な誤りに対して、このスキルが明確な方針を持っているためです。
• 詳細なアーキテクチャレビューの代わりになるか？ いいえ。初稿作成や構造化された文書化は加速できますが、システムの正確さは最終的に入力情報に依存します。

c4-architecture スキルの使い方

スキル環境に c4-architecture をインストールする

このリポジトリで使われている skills CLI パターンに対応したエージェントなら、次のコマンドでインストールできます。

npx skills add softaworks/agent-toolkit --skill c4-architecture

クローンしたリポジトリからスキルを読み込む環境なら、次の場所にあるスキルを使ってください。

skills/c4-architecture

初回利用前にまず読むべきファイル

短時間で要点をつかめる c4-architecture guide としては、次の順番で読むのがおすすめです。

1. skills/c4-architecture/SKILL.md
2. skills/c4-architecture/references/common-mistakes.md
3. skills/c4-architecture/references/c4-syntax.md
4. skills/c4-architecture/references/advanced-patterns.md
5. skills/c4-architecture/README.md

この順番が機能する理由は以下の通りです。

• SKILL.md で想定ワークフローを把握できる
• common-mistakes.md でよくあるモデリングミスを先回りして防げる
• c4-syntax.md で Mermaid 出力の不具合をすばやく切り分けられる
• advanced-patterns.md は単純なモノリスではないシステムで特に重要になる

プロンプト前に適切な C4 レベルを選ぶ

c4-architecture usage で出力品質を最も大きく左右するのは、読み手に合ったレベル選びです。

• C4Context: まずここから始める。利用者と外部システムを示す
• C4Container: 通常は必須。アプリ、データベース、キュー、サービスを示す
• C4Component: 内部構造が読者理解に本当に役立つ場合にだけ追加する
• C4Deployment: 実行時構成やインフラの関心があるときに使う
• C4Dynamic: 重要なリクエストフローやイベントフローを示すのに使う

よくある失敗は、システム境界の理解ができる前にいきなり component に飛び込み、読者にとって散らかった図を作ってしまうことです。

スキルに必要最低限の入力を渡す

完璧なアーキテクチャノートは不要ですが、構造が足りないとトポロジーをもっともらしく捏造しやすくなります。良い入力には、たとえば次の情報が含まれます。

• システム名と目的
• 主な利用者または外部 actor
• 主要なサービス / アプリ / データストア
• 外部システムやベンダー
• 主要な関係性とプロトコル
• 想定読者
• 欲しい図のレベル
• 出力先のファイルまたはドキュメント場所

「自分のアプリの C4 図を作って」とだけ伝えると、出力はかなり汎用的になります。

ざっくりした依頼を強い c4-architecture プロンプトにする

弱いプロンプト:

Create a C4 diagram for our platform.

より強いプロンプト:

Use the c4-architecture skill to document our B2B analytics platform. Audience: engineering and product. Create C4Context and C4Container diagrams in Mermaid plus brief Markdown explanations. System boundary: Analytics Platform. Actors: Customer Admin, Analyst. External systems: Okta, Stripe, Snowflake, SendGrid. Internal containers: React web app, API gateway, Python ingestion service, dbt transform jobs, PostgreSQL app DB, Redis cache. Show key relationships and protocols. Avoid component-level detail unless necessary.

後者のほうが良いのは、読者、対象範囲、システム境界、actor、内部コンテナ、外部依存関係まで具体的に指定しているからです。

一発生成ではなく、実務的なワークフローで使う

c4-architecture install を検討するうえで重要なのは、このスキルの進め方が実際の文書作業に合うかどうかです。実務では、次の流れが安定します。

1. まず context diagram を作る
2. actor や外部システムの漏れをレビューする
3. container diagram を生成する
4. 読者に必要な範囲でのみ component や deployment view を足す
5. 図を短い説明文と一緒に Markdown に保存する

この段階的な進め方は、最初から 5 種類の図を一気に要求するより優れています。というのも、Level 1 や 2 の誤りは、それ以下のすべての図に連鎖するからです。

Technical Writing で c4-architecture を活かす

c4-architecture for Technical Writing は、読みやすく、保守しやすく、コードと一緒に版管理できるアーキテクチャ文書が必要なライターに向いています。このスキルは、Markdown に埋め込める図を生成し、短い説明文と組み合わせやすい点で役立ちます。

テクニカルライティング用途では、次の情報を含めると効果的です。

• 想定読者のレベル: executive、mixed technical、developer、ops
• 用語集や承認済みの製品名
• サービス名やチーム名に関する推奨表記
• /docs/architecture/ のような文書配置先
• 各図について「なぜこの図が必要か」まで説明させるかどうか

これにより、技術的にはもっともらしくても、文書全体のトーンや情報設計と噛み合わない図ができる問題を防げます。

出力品質に大きく効くモデリングルールを押さえる

リポジトリの mistake guide では、特に重要なルールとして次の点が挙げられています。

• containers はクラスではなく、デプロイ可能 / 実行時の単位である
• components は container の内部要素である
• 非公式な C4 レベルを勝手に作らない
• 1 つの図の中では抽象度をそろえる
• 読者の判断に必要な情報だけを追加する

ひとつだけ覚えるならこれです。多くの悪い C4 図は、構文ミスではなくレベル混在によって破綻します。

Mermaid 出力が崩れたらリファレンスを使う

生成された図がレンダリングされない、または構造的におかしく見える場合は、次を確認してください。

• references/c4-syntax.md で有効な C4 Mermaid 宣言と要素を確認する
• まず relationship syntax と boundary syntax を見直す
• C4Container と C4Component のように、正しい diagram type を使っているか確認する

このスキルが単なる汎用プロンプトより使いやすい理由のひとつは、構文リファレンスによって修正の道筋が明確なことです。

advanced patterns が必要になる場面

アーキテクチャに次の要素が含まれるなら、references/advanced-patterns.md を開いてください。

• 複数のサービス境界を持つマイクロサービス
• API gateway
• イベント駆動またはキューベースのワークフロー
• 複数の ownership boundary
• 実ノードや環境をきちんと表す必要がある infrastructure / deployment view

このファイルは、「1 システム、1 アプリ、1 データベース」といった単純な捉え方では誤解を招く文書になってしまうケースで特に役立ちます。

c4-architecture スキル FAQ

c4-architecture は初心者にも向いているか？

はい。特に、システムを平易な言葉で説明できるなら有効です。このスキルのワークフローと mistake guide によって、C4 で起こりがちな初歩的ミスを減らせます。初心者はまず Context と Container に絞り、システム境界が固まるまでは Component 図に手を出さないのがおすすめです。

c4-architecture を使わないほうがよいのはどんなときか？

手早いラフスケッチだけ欲しい場合、ピクセル単位で整ったデザイン成果物が必要な場合、あるいは UML 中心の内部設計モデルを作りたい場合は、c4-architecture は外したほうがよいです。このスキルが最も強いのは、網羅的な実装設計ではなく、Mermaid で保守しやすいアーキテクチャ文書を作りたいときです。

AI に直接 Mermaid 図を頼むより良いのか？

アーキテクチャ文書用途なら、たいていはこちらのほうが適しています。汎用プロンプトでも Mermaid 自体は出せますが、c4-architecture には、レベル選択、モデリングの規律、構文リファレンス、既知のアンチパターンという土台があります。そのため、他の人が読んで保守する文書としての信頼性が高くなります。

c4-architecture はモノリスにもマイクロサービスにも使えるか？

はい。モノリスでは context、container、必要に応じた component view の切り分けに役立ちます。マイクロサービスでは、各サービスを container として表すべきか、もっと大きい system boundary として扱うべきかを判断するうえで、advanced patterns のリファレンスが役立ちます。

フルコードベースへのアクセスは必要か？

いいえ。ただし、元になる情報が良いほど結果も良くなります。このスキルは、アーキテクチャノート、リポジトリ構成、サービス一覧、API ドキュメント、デプロイメントマニフェスト、関係者からの説明などをもとに使えます。入力が部分的な場合は、前提を明示して出すよう依頼するとよいです。

c4-architecture で deployment や runtime view も作れるか？

はい。C4Deployment と dynamic flow diagram の両方に対応しています。ただし、実行時トポロジーやリクエストフローが読者にとって重要な場合に限って使うべきです。そうでないと情報ノイズが増えます。

c4-architecture スキルを改善する方法

推測した構造ではなく、まず事実を渡す

c4-architecture の出力を最も手早く改善する方法は、図を依頼する前に事実リストを渡すことです。

• users
• system boundary
• deployable units
• data stores
• external dependencies
• protocols
• environments or hosting model

これで、自信ありげだが誤った関係性が入り込むのを減らせます。

前提条件を明示的に列挙させる

価値の高い追記として、次の一文があります。

If any element is uncertain, list assumptions before generating the final Mermaid.

これは、引き継いだシステムを文書化する場合や、断片的なメモからこのスキルを使う場合に特に有効です。

深掘りする前に context と container の出力を見直す

context と container が正しくないうちは、component diagram を受け入れないでください。container モデルが間違っている状態で component 詳細を追加すると、見た目だけ整っていて中身は不正確な文書になりがちです。

抽象度の誤りは早めに厳しく修正する

出力に classes、packages、endpoints が container として現れていたら、まずそこを止めて修正してください。common-mistakes.md のガイドが重要なのは、抽象度がずれると文書全体の信頼性が大きく下がるからです。

修正指示として有効なのは次のようなものです。

Revise this as a true C4Container diagram. Only include deployable applications, services, data stores, and external systems. Move internal modules to a later component view.

本格的な依頼では毎回 audience を指定する

想定読者によって、「良い出力」の条件は変わります。

• executives には context、成果、外部依存関係が必要
• engineers には containers、protocols、責務境界が必要
• developers には 1 つの container 内の component 詳細が必要なことがある
• ops teams には deployment nodes や environments が必要

audience を指定しないと、構文が正しくても細かさのレベルがずれることがあります。

図に短い説明文を組み合わせる

このスキルは、各図の下に 2〜5 個の箇条書きを付けるよう依頼すると、かなり実用性が上がります。内容としては次のような点です。

• その図が何を示しているか
• なぜそのレベルを選んだか
• 重要な相互作用
• 意図的に省いているもの

この小さな追加だけで、docs や review thread での使いやすさが大きく上がります。

全面書き直しではなく、狙いを絞って反復する

初回出力のあとに品質を上げるなら、「やり直して」ではなく、次のような焦点の合った修正を返すほうが効果的です。

• 抜けている外部システムを追加する
• 製品用語に合わせて container 名を変更する
• 1 つに詰め込みすぎた service を 2 つの container に分ける
• relationship に protocol を追加する
• container view から component 詳細を外す
• 本番環境だけの deployment view を生成する

狙いを絞った反復のほうが、良い構造を保ったまま早く収束します。

c4-architecture を単なる生成器ではなく文書化の仕組みとして使う

c4-architecture skill の長期的なベストな使い方は、リポジトリ内のアーキテクチャ文書を標準化することです。Mermaid 図をコードや docs の近くに置き、pull request でレビューし、サービスや境界が変わったら更新する。この運用に入ると、このスキルは場当たり的なプロンプトより強くなります。Markdown ネイティブで、繰り返し使えるアーキテクチャ文書化を支えられるからです。