archify

Archify

検証済みのスタンドアロン HTML を、ネイティブ図または質問に答える 1 ページの解説として作成します。

コマンドは作業ディレクトリから実行します。ユーザーが別の場所を指定しない限り、新しい成果物の依頼ごとに、そのディレクトリ内に専用のフォルダー .archify/<type>-<slug>-<YYYYMMDD-HHMMSS>/ を作成します（ローカル時刻を使用し、時刻は一度だけ決定します）。候補と <slug>.html はその中に保存し、修正にも同じフォルダーを使います。ネイティブ図では candidate.json を使い、meta.output は作業ディレクトリからの相対パスにします。解説では candidate.archify.md と、移植可能な出力ファイル名を使用できます。後続の依頼には新しいフォルダーを作成します。各コマンドの bin/archify.mjs は、インストール済みパッケージの絶対パス、または作業ディレクトリからの相対パスに置き換えてください。CLI の入力パスと出力パスは、そのディレクトリを基準に解決されます。

実際のコードベースを対象にネイティブ図を作成する場合は、依頼された動作を追跡しながらリポジトリの作成ガイドを読んでください。システムの説明には以下のネイティブ手順を使い、固定済みの候補には引き継ぎ手順を使います。

成果物を選ぶ

• ユーザーがシステム、フロー、スキーマ、履歴の図示や可視化を求めている場合は、ネイティブ図と Type router を使います。
• ユーザーがページでの回答を求めている場合（「1 ページにして」「ページで説明して」「共有できるもの」など）は、explainer を使います。このような依頼がない場合は、文章で回答するか、求められた図を作成します。依頼に応じてページを作成した場合は、Output にあるモード提案の 1 行を返信の末尾に付けます。
• コンテキスト内のルール行によって、この動作は変わります。[archify explainer: proactive]：表、手順、複数のセクションが必要な説明、比較、トレードオフ、判断、診断、レビュー、計画については、明示的に求められていなくてもページを作成します。[archify explainer: always-on]：結論に至るすべての返信に、最大 4 パネルの簡潔なページを追加し、開かずに届けます。返信の末尾はそのリンクにします。[archify explainer: on-demand]：求められた場合に限り、ページを作成します。モードの提案は行いません。
• どのモードでも、ページには、その裏付けとなる一定の構成を伴う結論が必要です。雑談、一行の回答、生のコマンド出力、テキストのみの依頼にはページを作成しません。
• explainer では、結論、理由、対象範囲、ボードのレイアウト、任意のネイティブ図について、解説の作成ガイドを読んでください。完全な下書きを作成してから、finalize explainer を実行して検証、アトミックな納品、成果物のチェックを行います。内容の局所的な修正には panel patch を使います。

既存候補の引き継ぎ

ユーザーから固定済みの候補が提供された場合は、最初に finalize を 1 回の CLI 呼び出しで実行します。合格のレシートを受け取れば、自動ゲートの確認は完了です。視覚品質を主張する前に、Delivery に記載された視覚レビューの推奨事項に従ってください。修正する場合は手順 5 に従います。

finalize は納品レシートに、範囲を限定した更新チェックも含めます。Update awareness を参照してください。

ネイティブ図の作成

通常の生成では、この手順を使います。分岐別の参考資料は、記載された条件に該当する場合にのみ読んでください。

1. 質問に応じて、architecture、workflow、sequence、dataflow、lifecycle、erd、class、tree、timeline、waterfallから選びます。

2. Type routerに記載された正確なスキーマとサンプルのパスを使用し、ディレクトリは一覧表示しないでください。Authoring defaultsと、モードのサンプルを、プロジェクト文書や完全なスキーマとは分けて、切り詰められない範囲のバッチで読み込みます。書き始める前に、不足しているセクションがあれば補ってください。Architectureでは、対応するショーケースのサンプルを使用します。Architecture以外のすべてのモードでは、モード固有のスキーマと共通スキーマも読み込みます。新しいフィールド、列挙値、または制約付きテキストを選ぶ前に、関連するスキーマ定義を確認してください。特に境界の種類については必ず確認します。サンプルから学ぶのは形式であり、事実ではありません。ID、文言、レイアウトは新たに作成してください。事前の支援、doctor、starter validation、一時的な図、出力パスの一覧表示を行わず、候補を直接作成します。マークが明示的に要求された場合に限りブランドを調べます。未知のマークについてユーザー提供のURLがある場合は、Brand marksを読みます。

3. 要求された範囲と、実際のコードベースを扱う場合はソースの根拠を確認したら、文章で座標を計画せず、候補全体を直接作成します。座標を決める前に、Authoring defaultsに従ってArchitectureの抽象度と、つながりを保った配置を選びます。主要なユーザージャーニーと必要な分岐を示し、制御の役割と動作を変える条件を維持し、実際の関係ラベルを収める十分な余白を確保します。ノード、関係、ソース、ビュー、カード、境界の数は、目標でも上限でもありません。自動ルートを最初に使用し、必要な分岐、戻り、指定されたジオメトリ、または測定後の修正に限って明示的なルーティングを追加します。ユーザーが密度の高いstandardを希望しない限り、meta.quality_profileは"showcase"に設定します。ERDではテーブルを中心にレイアウトします。物理カラムはすべてentities[].attributesに記載し、SQL型とソースのコメントを維持します。カラムが担うキーの役割はすべて指定します（keyには1つの役割または役割のリストを指定できるため、中間テーブルのカラムは["pk", "fk"]となり、fkカラムには"orders.id"のようなreferencesも必要です）。テーブルの代わりにカードへカラムを移してはいけません。配置前にテーブルを機能ドメインに分類し、各ドメインに簡潔なtagを付け、そのメンバーをグリッドセルの単一の塗りつぶされた長方形（単一行、単一列、または塗りつぶされた矩形ブロック。L字型や斜めの配置は不可）に配置します。タグ付きのテーブルには必ずrow/colが必要です。絶対座標ではグリッドセルがなく、ドメイン内のテーブルが1つの長方形を埋めない場合は帯状に描画できないため、図を公開せず、レンダラーはerd/domain-not-drawnを報告します。複数ドメインを含むスキーマは、ドメインごとに1列とするレイアウトが最も読みやすくなります。各tagを縦に並べます。読者は横に広いキャンバスを表示幅に合わせて拡大し、縦に長いキャンバスはページに収まるまで縮小するため、横に広い配置のほうがノートPCの表示領域でも全体を読みやすく保てます。テーブルが概ね8個、またはフィールドが50個を超えるスキーマ中心のERDは、それ自体が密度の高いマップです。まず、全フィールドを含む初回版をstandardで作成し、レイアウトが読みやすい場合に限ってアップグレードします。

4. 候補の初回版を完成させたら、直接finalizeを実行します。最初のゲートはショーケース検証です。初回ドラフトが正常であれば、別途の事前検証は不要です。コマンドの実行中は候補を変更しないでください。

   node bin/archify.mjs finalize <type> <candidate.json> <output.html> --quality showcase --json
   

   リポジトリに基づく候補では、初回ドラフトに根拠を含め、完全な初回コマンドを使用します。node bin/archify.mjs finalize <type> <candidate.json> <output.html> --repo-root <repo-root> --quality showcase --json。meta.quality_profileに一致する--qualityを渡します。たとえば、密度の高いERDの初回版ではstandardを指定します。

   合格レシートは、含まれるvalidate、deliver、厳格なcheck、および実ブラウザーでのbrowser-checkの各ゲートに合格したことを示します。簡潔なサマリーを使用し、別途の依頼がある場合、または特定の失敗を診断する場合に限り、単独のコマンドを実行してください。

5. 終了コードが 0 以外の場合、成功ではありません。簡潔な標準出力または evidence.summaryReceipt を確認し、失敗したゲートを修復してください。修復の上限も確認してください。依頼された意味とソースの根拠を保持してください。複雑に絡み合った Architecture のルートが複数ある場合は、Architecture レイアウトの修復を確認してください。フィールドやジオメトリの実測値に関する失敗の場合は、オーサリング契約を確認してください。関連する範囲を編集し、手順 4 の finalize コマンド全体を再実行してください。実行が browser-check に到達した後は、その出力パスが証拠を保持します。その後の実行では、それぞれに専用の --out-dir <folder>/review-<n> を指定してください。

更新の確認

finalize と単独の deliver は、レシートに update を含みます。同じ納品について、別途確認を実行しないでください。update.noticeRequired が true の場合は、references/update-awareness.md を確認し、品質ゲートが失敗した場合も、最終回答にユーザー向けの簡潔な更新通知を 1 件含めてください。図が複数あるタスクでは、最終回答で更新について一度だけ言及してください。ユーザーから明示的に依頼された場合に限り、リマインダーをスヌーズまたは無視してください。自発的にインストールや更新を行ってはいけません。

最初の候補を作成する前に、Archify の実装やテストではなく、オーサリングに関するリファレンスと関連するリポジトリのソースを使用してください。対象を絞った修復を行っても診断結果から対応策を判断できない場合は、Archify の実装を調べてください。

タイプルーター

タイプ	用途	スキーマ	例
architecture	コンポーネント、サービス、クラウド／セキュリティ境界、インフラストラクチャ。日常的なものが何で構成されているか	schemas/architecture.schema.json	システムの説明、サービス、ライブラリ、CLI リポジトリ：examples/web-app.architecture.json。デプロイ用リポジトリ：examples/production-deployment.architecture.json
workflow	プロセス、承認ゲート、ツール呼び出し、ランブック、CI/CD。計画や、段階を追って進む日常のプロセス	schemas/workflow.schema.json	examples/agent-tool-call.workflow.json
sequence	API 呼び出しチェーン、リクエストのライフサイクル、非同期トレース、戻り値。人同士のやり取り	schemas/sequence.schema.json	examples/cache-miss-request.sequence.json
dataflow	パイプライン、ETL/ELT、リネージ、ガバナンス、利用者。お金や書類の流れ	schemas/dataflow.schema.json	examples/product-analytics.dataflow.json
lifecycle	状態／ステータスの遷移、再試行、待機状態と終端状態。アプリケーションや注文の現在の状況	schemas/lifecycle.schema.json	examples/deployment-release.lifecycle.json
erd	テーブル／エンティティ、属性、主キー／外部キー／一意キー、それらの間の多重度	schemas/erd.schema.json	examples/orders.erd.json
tree	単一の親を持つ包含関係：リポジトリ／モジュールのツリー、機能や特徴の分解、組織図のような階層構造	schemas/tree.schema.json	examples/payment-platform.tree.json
class	クラス、インターフェース、選択したメンバー、型間の依存／関連／継承／実現／コンポジション	schemas/class.schema.json	examples/payments.class.json
timeline	出来事の発生時刻：インシデントレビュー、リリース履歴、ソースごとのレーンを持つ比例スケール上のタイムスタンプ付きイベント	schemas/timeline.schema.json	examples/payment-incident.timeline.json
waterfall	所要時間の内訳：共通の時間軸上に示す、単一のリクエストまたはエージェント実行のスパンの長さ、重なり、入れ子構造	schemas/waterfall.schema.json	examples/checkout-request.waterfall.json

ネイティブの図のタイプを選びにくい場合は、node bin/archify.mjs guide "<scenario>" --json を実行してください。シナリオの証明用の例は構造上の参考資料であり、事実としてそのままコピーするものではありません。

日常的な題材では、同じ図のモードと意味タイプを維持したうえで、読者になじみのある名前を付けてください。Node icons のように、日常的な icon の値と meta.legend のラベルを使用します。日付、金額、ルールを捏造せず、不足している個人的な事実は質問して確認してください。

Mermaid 入力

トポロジーと意味を読み取り、新しい Archify JSON を作成してください。Mermaid のスタイルを機械的に再現しないでください。

• flowchart / graph → workflow。コンポーネントマップの場合は architecture。
• sequenceDiagram → sequence。参加者は意味を持つ参加者となり、矢印はメッセージとなります。
• stateDiagram → lifecycle。状態と遷移の意味を維持し、Mermaid のスタイルは引き継ぎません。
• erDiagram → erd。エンティティ名、関係名、キー、多重度の意味を維持し、Mermaid のスタイルは引き継ぎません。
• classDiagram → class。型の種類、選択したメンバー、関係の種類の意味を維持し、Mermaid のスタイルは引き継ぎません。

配信

最初の候補と修正後の候補には、上記の finalize コマンドを使用します。

finalize は、最初に不合格となったゲートで停止します。簡潔な標準出力と <output-stem>.finalize-summary.json は、通常の証拠です。合格した実行ではスクリーンショットは作成されず、visualReview: "not-requested" が報告されます。

合格した Architecture のレシートで visualReviewRecommendation.signals.resolvedCrossovers が報告された場合は、候補のコピーを別に保存し、ノードの位置とサイズのみを変更する一度の編集でヒントを適用します。すべてのノード、関係（from と to を含む）、ラベル、ソースは変更しないでください。前の HTML がすでにブラウザーの証拠を保持しているため、--out-dir <folder>/review-2 を指定して finalize 全体を一度再実行します。--out-dir によって移動されるのは、新しいブラウザーチェックとデフォルトの finalize レシートであり、HTML やその配信レシートではありません。配信に成功すると、指定された出力パスにそのペアが再生成されます。以前のレビュー証拠は、元のアーティファクトのバイト列に紐付いたままです。レビュー証拠のパスを参照してください。その実行が失敗した場合、交差が増えた場合、または signals.routesOverSuggestedBends が増えた状態で同じ交差が報告された場合は、保存したコピーを復元し、--out-dir <folder>/review-3 を指定して finalize します。2回目の配置調整は行わないでください。追加の曲がりに関するヒントのみの場合は、適用するかどうかは任意です。

layoutReviewRecommendation.action が inspect-sequence-width の場合、新たに作成した Sequence を引き渡す前に、Sequence の幅レビューに従ってください。

新たに位置を調整した Architecture を含め、通常の生成における知覚的レビューは任意です。ユーザーからビジュアルレビューを依頼された場合、開発時の監査の場合、または具体的なルート／ブラウザー上の懸念がある場合は、--out-dir <folder>/visual-check を使用して任意のキャプチャ証拠を取得します。visualReviewRecommendation は参考情報です。ビジュアル品質を主張する前にキャプチャを確認してください。知覚的レビューを実施していない場合、確認したという主張には自動チェックであることを明記してください。

ゲートの失敗、単独コマンド、来歴／復旧、再配信、エクスポート、または開き方については、配信契約を参照してください。ネイティブ図の復旧では、deliver → 厳密な来歴チェック check → browser-check の順に実行します。キャプチャには厳密な来歴が必要です。解説の配信では、作成ガイドに記載されているとおり、validate、deliver、check を使用します。

Workflow のビューポートからのはみ出しを修正する場合は、次のレイアウト編集の前にWorkflow のビューポート修正を参照してください。

検証の詳細を報告する際は、アーティファクトのチェック、ブラウザーの証拠、キャプチャ、実際の知覚的レビューを区別してください。即時プレビューを明示的に求められた場合や、デスクトップでの操作を継続中の場合は、任意の表示を参照してください。

任意の Viewer 機能

レンダリングされた図では、デフォルトですべてライブモーションが有効になっています。meta.animation は省略してください。Viewer の Live／Still ボタンで再生を操作できます。

ユーザーから Share Cards、Route/Reach cards、モーション、ディープリンク、プレゼンテーション、検索／フォーカス、またはその他の Viewer Runtime 機能を明示的に求められた場合に限り、references/viewer-runtime.md を参照してください。

セットアップと代替手段

スキルパッケージ内でインストールする必要はありません。セットアップの問題を診断するには、次のコマンドで確認してください。

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

ネイティブ図の場合、シェルにアクセスできないときは、architecture SVG を assets/template.html に手動で配置し、インラインカラーではなく CSS のセマンティッククラスを使用して、references/delivery-contract.md のビジュアルレビュー契約に従ってください。解説にはレンダラーと実際の配信ゲートが必要です。それらを利用できない場合は、その制約を報告し、有用であればテキストで回答してください。HTML を配信したと主張してはいけません。

出力

ユーザーの言語で、結果に必要な範囲で簡潔に返信します。図が内容を伝えるため、通常は図へのリンクを含む1行で十分です。

• 先頭に、HTMLへのクリック可能なMarkdownリンクを置きます。タイトルは内容が伝わるものにし、ファイル名は使わず、絶対パスを指定します。パスにスペースが含まれる場合は <...> で囲みます。
• ユーザーが説明された対象を図にするのではなく、システムやコードベースを理解しようとしている場合は、要点を1〜2文で補足します。図から明らかなことを言い換えるだけの文は省きます。
• 図の読み取り方に影響する事項を明記します。たとえば、読者が予想しそうな抽象度や意図的に省略した部分、測定値ではなく説明用の値であること、根拠となる情報源がないこと、修正時に依頼された内容を削除または統合したことなどです。
• 図が複数ある場合は、既存の概要ページへのリンク、または図ごとの簡潔なリンクを添えて、完了を一度だけ報告します。ディレクトリパスは記載しません。

コマンド、修正ラウンド、ハッシュ、品質プロファイル、チェックリストを繰り返し説明しないでください。それらはレシートに記載します。図が検証済みかどうかを尋ねられた場合は、「自動チェックに合格しました。目視確認はしていません。」のように1行で答えます。再現やトラブルシューティングが必要な場合に限り、レシートへのリンクや詳細を記載します。依頼された目視確認を実行できなかった場合は、その旨を明記します。実際に目視確認した場合に限り、目視確認を行ったと述べます。必須の更新通知は「Update awareness」内で簡潔に記載します。

例：[チェックアウトリクエストのタイミング](/abs/path/checkout-timing.html)を作成しました。所要時間は説明用であり、測定値ではありません。

解説ページへの返信は2〜3行にします。結論とページへのリンクを記載します。失敗したゲートがある場合、または文章に警告が残っている場合に限り、ゲートについて触れます。下書きは貼り付けません。

依頼に応じて解説ページを作成した後、会話内に [archify explainer: ...] の行がない場合は、返信の末尾に、プロアクティブモードを一度だけ任意で提案する1行を付けます。例：「必要であれば、今後、説明・比較・トラブルシューティングなどの際に、このようなページを自動で作成できます。有効にしますか？」ユーザーが同意した場合は、現在のエージェントのグローバルルールファイル（例：~/.claude/CLAUDE.md、~/.codex/AGENTS.md、~/.config/devin/AGENTS.md）に [archify explainer: proactive] Make an Archify explainer page, unasked, for explanations, comparisons, decisions, diagnoses, reviews and plans that need a table, steps or several sections. を追加し、ファイル名を伝えます。この行を削除すれば無効になります。ユーザーが希望しない場合は、質問が再び表示されないように [archify explainer: on-demand] を追加することを提案します。