Archify アーキテクチャ図 Skill チュートリアル：導入、リポジトリ分析、検証、トラブルシューティング

Archify は、Codex CLI、Claude Code、Cursor、OpenCode、および Raven の Agent Skill です。単にテキストを一般的なフローチャートのテンプレートに当てはめるのではなく、システムの説明やコードリポジトリを対話型の技術図に変換します。

生成された結果は、型指定された JSON IR を事実のソースとして使用し、検証後に自己完結型の HTML を提供します。 PNG、SVG、WebM、および 1200×630 の共有カードもブラウザでエクスポートできます。これは、アーキテクチャのレビュー、README 図、障害パスの説明、変更前後の比較に適していますが、ソースコード、デプロイメント構成、および操作ログのレビューに代わるものではありません。

プロジェクトアドレス: tt-a1i/archify

まず、Archify が現在のタスクに適しているかどうかを判断します

Archify には、次の 5 つの主要なグラフタイプが用意されています。

すべての情報を 1 つのアーキテクチャ図に詰め込まないでください。ログイン要求のキャッシュフォールバックはシーケンスに適しています。 CI の承認とロールバックは Workflow に適しています。注文ステータスの遷移はライフサイクルにより適しています。

Archify は、Mermaid テーマ、オンラインホスティングプラットフォーム、または WYSIWYG エディターではありません。公式には、Mermaid の自動解析、ユニバーサル自動レイアウト、ホストされた共有、および WYSIWYG 編集は明らかに現在の範囲外です。

インストール前に Node.js と作業ディレクトリを確認してください

インストールコマンドは npx を通じて実行されるため、最初に Node.js と npm を確認してください。

1
2
3


node --version
npm --version
npx --version

コマンドが存在しない場合は、現在サポートされている Node.js LTS を最初にインストールしてから、ターミナルを再度開きます。 npx が欠落している場合は、インストールの失敗を Codex または Claude Code のせいにしないでください。

また、図を生成するウェアハウスを確認します。

1
2


git rev-parse --show-toplevel
git status --short

コミットされていない変更があるワークスペースも分析できますが、図内のソースコードの証拠は明示的なコミットに対応している必要があります。正式なレビューのために、最初に次のことを記録します。

1

git rev-parse HEAD

Archify スキルをグローバルにインストールします

公式のクイックインストールコマンドは次のとおりです。

1

npx skills add tt-a1i/archify -g

-g はグローバルインストールを表します。各エージェントの共通スキルの場所は異なります。

ツール	一般的な場所
Codex CLI	`~/.agents/skills/`
Claude Code	`~/.claude/skills/`
OpenCode	`~/.config/opencode/skills/`、`.opencode/skills/`、または `.agents/skills/`
Raven	`~/.raven/workspace/skills/archify`

インストーラは、ターゲットエージェントに応じてディレクトリを処理します。同じスキルを複数の不明な場所に手動でコピーすることはお勧めできません。インストールが完了したら、エージェントを再起動し、新しいセッションでスキルが再スキャンされることを確認します。

Codex で一時的に試してみたい場合は、次のコマンドを実行できます。

1

npx skills use tt-a1i/archify@archify --agent codex

一時的なトライアルは効果を検証するのに適しています。チームが安定して再現するには、インストール方法を修正し、Archify ウェアハウスのバージョンまたは提出物をプロジェクトドキュメントに記録する必要があります。

エージェントが実際に Archify を呼び出しているかどうかを確認します

「正常にインストールされた」だけで可用性を判断しないでください。新しいセッションを作成した後、明確に定義されたリクエストを送信します。

1
2
3


分析当前仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，标出一条主请求路径、外部依赖和信任边界。
把补充说明放进卡片，不要继续增加连线。

受付時に確認すべき3つのこと

エージェントは、Mermaid コードの偽装結果を生成する代わりに、Archify を明示的に選択して呼び出します。
出力には、個別に開くことができる HTML と、対応する型付きソースデータが含まれます。
図のコンポーネント、関係、および境界は、根拠のないサービスを使用せずに、ウェアハウスまたは入力説明に戻すことができます。

エージェントが説明のみを返す場合は、まずスキルが見つかったかどうかを説明させ、次にインストールディレクトリと新しいセッションのステータスを確認します。

リポジトリから最初のアーキテクチャ図を生成する

高品質の結果は範囲によって決まります。次のプロンプト単語を使用できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Use archify to map this repository's runtime architecture.

Scope:
- entry points and long-running processes
- API, worker, database, cache and external services
- one primary request path
- authentication and trust boundaries

Constraints:
- 8–12 main nodes
- do not infer services that are not present in source or configuration
- place evidence and secondary details in cards
- deliver the validated HTML and typed source together

モノリポジトリの場合、最初にディレクトリを修飾する必要があります。

1
2


只分析 apps/api、packages/auth 和 packages/database。
忽略 examples、generated、vendor 和构建产物。

スコープが制限されていない場合、エージェントはテスト、スクリプト、および過去の実装を運用コンポーネントとして描画する可能性があり、その結果、ノードが多すぎてエッジの意味が不明瞭になります。

特定のリンクのシーケンスまたはデータフローを選択します

キャッシュフォールバックは次のタイミング図に適合します。

1
2
3
4


Use archify to draw this login sequence:
Browser -> Web App -> API -> JWT validation -> Redis session lookup.
When Redis misses, query PostgreSQL and repopulate Redis.
Show failure returns and timeout boundaries, but keep the happy path primary.

プライバシーとデータの処理に関しては、代わりにデータフローを使用してください。

1
2
3


画出用户上传文件后的数据流。
标出上传入口、病毒扫描、对象存储、元数据数据库、异步处理器和下载消费者。
明确包含个人信息的节点、跨边界传输和保留期限，不推测未提供的加密方式。

違いは、シーケンスは呼び出しシーケンスに焦点を当てていることです。データフローは、データの移動、変換、ストレージ、機密境界に焦点を当てています。

スクリーンショットだけでなく JSON IR も保存する

Archify は、型付きの JSON IR を使用してレンダリングを駆動します。チームは以下も保存する必要があります。

オリジナルの JSON;
HTMLを確認しました。
ドキュメント用の SVG または PNG。
生成時の対応する Git 送信。
記録の手動レビュー。

PNG だけを保持すると、反復可能な編集機能と検証機能が失われます。 HTML はインタラクティブな表示に適しており、SVG はドキュメントとバージョン管理に適しており、PNG は SVG をサポートしていないプラットフォームに適しています。

推奨されるディレクトリの例:

1
2
3
4
5


docs/architecture/
├── runtime.architecture.json
├── runtime.architecture.html
├── runtime.architecture.svg
└── README.md

README.md のスコープとコミットを文書化します:

1
2
3
4


Source revision: 4f2c1ab
Scope: apps/api, packages/auth, packages/database
Excluded: tests, generated, vendor
Review status: manually checked

リポジトリ CLI を使用して検証して配信します

Archify ウェアハウス内のバリデーターを直接呼び出す必要がある場合は、まずプロジェクトのクローンを作成し、ディレクトリを入力します。

1
2
3


git clone https://github.com/tt-a1i/archify.git
cd archify
node bin/archify.mjs doctor

まず組み込みの例をチェックアウトしてください。

1
2


node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"

Workflow JSON を確認します:

1
2
3
4


node bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

1 回限りの成果物 HTML を生成します:

1
2
3
4
5
6


node bin/archify.mjs deliver workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase \
  --open \
  --json

失敗した場合は、diagnostics[]、ルールコード、具象オブジェクト、および supportedFixes を読み取り、指摘された問題のみを変更します。 1 つの検証エラーが発生したからといって、エージェントにグラフ全体を書き直させないでください。

ローカルプレビューのセキュリティ境界

変更と読み取りを同時に行う必要がある場合は、preview を使用できます。

1
2
3
4


node bin/archify.mjs preview workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase

公式プレビューモードは、127.0.0.1 のランダムポートのみをバインドし、指定された JSON ファイルのみをリッスンします。候補ファイルが検証に失敗した場合、ブラウザは以前の適格な結果を表示し続けます。

リモートアクセス用にプレビューサービスを 0.0.0.0 に変更しないでください。管理されたドキュメントシステムで静的エクスポートファイルを共有または公開する必要がある場合は、自己完結型の HTML を提供します。

Architecture Delta で変更を確認します

設計または PR のレビューでは、2 つの検証済みスナップショットを比較できます。

1
2
3
4
5


node archify/bin/archify.mjs compare architecture \
  base.json \
  head.json \
  architecture-delta.html \
  --json

結果には、追加、削除、変更、移動、または再ルーティングされたファクトを区別して、Before、Delta、After が表示されます。これは、記述され検証された 2 つの構造を比較するものであり、リスク、範囲、またはそれらを組み合わせられるかどうかを自動的に決定するものではありません。

したがって、手動による回答が依然として必要です。

変更が実際のコードと構成によるものであるかどうか。
信頼境界が変更されるかどうか。
データストレージまたは外部依存関係が新たに追加されるかどうか。
導入シーケンスとロールバックを調整する必要があるかどうか。
新しいパスがカバーされているかどうかをテストします。

生成した図を検証する方法

まず事実を確認してから、ビジュアルを確認してください。

ファクトチェック

エントリが実際の起動コマンドと一致しているかどうか。
サービス関係がコード、構成、またはドキュメントで見つかるかどうか。
同期呼び出しと非同期メッセージを区別するかどうか。
データベース、キャッシュ、キューは同じストレージ内に混在しません。
信頼境界と外部システムは除外されません。
画像にはエージェントが独自に追加できる「共通コンポーネント」はありません。

目視検査

主要なパスは数秒以内に識別できます。
ノードは相互にブロックしません。
接続線はラベルを通過しません。
二次情報が一次関係を圧倒しない。
暗いテーマと明るいテーマの両方で読むことができます。
SVG、PNG、および HTML のエクスポートされた式は一貫しています。

到達性チェック

HTML は、切断された環境でも開くことができます。
JSON と HTML は同じバージョンを使用します。
ファイル名は安定しており、一時的なランダムな名前は含まれません。
この図にはキー、イントラネットアドレス、顧客データは含まれていません。
Git コミットとビルドのスコープが文書化されています。

一般的なトラブルシューティング

エージェントが Archify を見つけられません

インストールとセッションを再確認します。

1

npx skills add tt-a1i/archify -g

その後、完全に終了して、Codex または Claude Code を再起動します。同時に複数のスキルディレクトリがある場合は、エージェントが実際にどれを読み取るかを確認し、インストールを繰り返さないでください。

Archify HTML ではなく Mermaid が生成される

プロンプトに明示的に「archify を使用」と書き込み、検証済みの HTML と入力されたソースの配信を要求します。それでも呼び出されない場合は、スキルが発見されていないか、他のルールでカバーされていることを意味します。

図内のコンポーネントが多すぎる

リクエストを単一のランタイムパスに絞り込み、マスターノードを 8 ～ 12 に制限し、ログ、メトリクス、テスト、およびヘルパースクリプトを説明カードに移動します。

図の構造がソースコードと矛盾しています

まず、Git の送信および分析ディレクトリを修正してから、証拠が見つからないノードを 1 つずつ削除します。「通常は Redis がある」などの経験を実際のウェアハウスに追加しないでください。

検証に失敗しましたが、古いイメージが表示されたままです

これは、最後に有効なプレビューメカニズムです。 diagnostics[] を確認し、現在の候補を修正してください。新しいバージョンが正常に検証されたため、古いイメージがまだ表示されているという事実を誤解しないでください。

ドキュメントプラットフォームで SVG が正しく表示されない

まずブラウザで直接 SVG を開き、フォント、外部リソース、トリミング範囲を確認します。表示が安定しない場合は PNG を使用しますが、SVG および JSON のソースファイルは引き続き保持します。

再利用可能な受け入れチェックリスト

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


[ ] 已记录 Archify 安装方式和版本
[ ] 已记录仓库 Git 提交与分析范围
[ ] 图表类型与问题匹配
[ ] 主路径、外部依赖和信任边界明确
[ ] JSON IR 与 HTML 同时保存
[ ] validate 或 deliver 返回成功
[ ] 图中每个关键关系都有输入或源码依据
[ ] 深色与浅色主题可读
[ ] SVG/PNG 导出可打开
[ ] 不包含密钥、内网地址或客户数据
[ ] 人工评审没有把图当作运行时事实证明

概要

Archify の価値は、「一文で自動的に描画する」ことではなく、技術的な説明を入力済みで検証可能でインタラクティブな成果物に編成することです。信頼性の高いプロセスは、スコープを制限し、正しいイメージタイプを選択し、JSON IR を生成し、検証に合格し、事実を手動で確認してから、HTML と静的エクスポートを提供することです。

特に、コードリポジトリの Git コミットと分析スコープを保持します。図はチームがアーキテクチャを議論するのに役立ちますが、ソースコード、構成、テスト、および運用データが最終的な基礎であることに変わりはありません。