flow-atlas は何をしますか？
リポジトリ自身のAGENTS.md、設計文書、ガバナンステストがこのスキルよりも優先されます。
3つの部分
atlasはコードが確定するものを生成します。あなたは意図が必要なものを記述し、atlasはそれをチェックします。両者の間で、あなたはどの作業がどのコンポーネントに属するかを、references/boundaries.mdの基準に従って解釈します。あなたが決定したすべては、atlasが読み取るファイル（フローファイル、例外ファイル、設定、フィードバック）に保存され、次回の実行や次のエージェントがそれを参照できるようになります。
atlasが生成するもの：これらは手動で記述しないでください
| 事実 | コマンド |
|---|---|
| サーフェス、呼び出し、エッジ、操作ID、レジストリ、コントラクトバージョン | scan |
| パス、メソッド、またはコンポーネントごとのサーフェスと呼び出し | query |
| 上流の呼び出し元と下流のサービスに到達するサーフェス | trace |
| フローのドラフト：名前、コードのパスに沿ったステップ、あるコンポーネントが呼び出すときのエントリ、分岐する候補 | draft flow |
| フローがコード内で成立しているか、およびその作成者フィールドが記述されているか | flows (conditions) |
| 場所と近くのパスを含む検出結果 | check, explain |
| リビジョン間の変更点 | diff |
| 設定の候補と設定のカバレッジ | inventory, scan |
| 各コンポーネントのOpenAPI記述、コミットされたものがコードとどの程度一致しているか、コードが決定する場合にどのコンポーネントのものか | scan, inventory |
graph.jsonをgrepしたり、テキスト検索から呼び出し元を推測したり、サーフェスIDを記憶からタイプ入力したりしないでください。atlasの出力からコピーしてください。
あなたが記述するもの：atlasがチェックします
| 内容 | チェック方法 |
|---|---|
フローのtitleと各ステップのrole | Documented |
owner、labels、sources、lifecycle（ステップが未構築の場合はplanned） | スキーマ; Resolvedはplannedステップを別途カウント |
フローの意図を記述した後のgenerated: { by: <tool>/<model>, at }; レビューが必要な場合のstale_after (OKF) | スキーマ; Fresh |
| 最初のステップを複数のコンポーネントが呼び出す場合のエントリコンポーネント; ハンドラが分岐する次のステップ | EntryCalled, Connected |
produces | ProducesListed |
例外: 理由、decidedBy、reviewBy | 期限切れになると検出結果が再表示される |
| 誤検知、その理由 | stats |
| 設定 | scanのカバレッジ |
フレームワークが生成するOpenAPIドキュメント（atlasが解析できないコンポーネントの場合）(routes[].openapi, references/openapi.md) | scanのカバレッジとlimit:行 |
origins: 各コンポーネントが環境で実行されるベースURL（デプロイメントファイルから） | export arazzoが欠落を通知 |
atlasが記述をambiguousと報告した場合のopenapi.<component> | export arazzoが設定されるまで拒否 |
あなたの担当部分をツールに委ねないでください：人が受け入れられる理由なしに、publicSurfaces、例外、ベースラインの更新は行わないでください。human:アクターでverifiedエントリを決して記述しないでください：それは人のレビューを記録するものであり、フローの信頼レベル（unverified、machine-confirmed、human-reviewed）はそれに依存します。
あなたが解釈するもの：境界
ホップが属するコンポーネント、類似のサーフェスがすでに機能を果たしているかどうか、ギャップが欠陥、計画、誤検知のいずれか、エッジをどの程度信頼するか、フローがどこで開始し終了するか。references/boundaries.mdに従ってください。これは情報源（リポジトリルール、次にフローロール、次にコード）の順序を定め、その基準を示します。
セットアップ
atlas --helpを実行します。atlasがインストールされていない場合は、npx (npx github:hellices/flow-atlas --help) を使用するか、ユーザーにインストールを依頼してください。その読み取りを手動で再実装しないでください。- 設定ファイルは
<root>/atlas.config.yaml、<out>/atlas.config.yaml、または--config <file>です。存在しない場合は、以下の「セットアップ」に従ってください。 - リポジトリに書き込んではならない場合は、
--out <外部のディレクトリ>を渡します。すべての書き込みはそこに行われます。
変更の設計
atlas query --path <パスまたは断片>とatlas query --component <名前>で既存のものを確認します。atlas trace <最も近いサーフェス>でチェーンを確認します：クライアント呼び出し、BFFルート、ハンドラが到達するポートメソッド、それぞれが一致するサービスルート。- 決定します：再利用、拡張、追加。追加または変更するサーフェスキーと、各ホップを所有するコンポーネントを書き留めます。2つのコンポーネントが同じステップを実行することになる場合は、コードを書く前に解決します。
- リポジトリがフローを保持している場合（
flows/*.flow.yaml）、フローを更新するか、atlas draft flow <surface>で新しいフローを開始します（「フローを書く」を参照）。まだ存在しないステップはlifecycle: plannedとマークします。
実装中
ルートまたはクライアント呼び出しを追加した後、atlas trace <surface>を実行します。上流には意図した呼び出し元が、下流には意図した呼び出しが表示されるはずです。空の側は、まだ配線されていないか、ツールが読み取れない方法で配線されている（呼び出しから遠く離れた場所に構築されたパス、別の言語のハンドラ）ことを意味します。コードを開いて、その理由を述べてください。
生成されたOpenAPIドキュメントからルートが来るコンポーネントのルートを追加、削除、変更する場合は、同じ変更でドキュメントを再生成してください。クライアント呼び出しだけではドキュメントは変更されません。
フローを書く
atlas draft flow <最初のサーフェス>は、コードが確定するすべてを含むフローを出力します。--to <surface>を追加して、指定された終点までコードを追跡します。flows/<名前>.flow.yaml（または変更してはならないリポジトリの場合は<out>/flows/）に保存します。- すべての
agent:コメントを埋めます：title、各ステップのrole（コンポーネントが行うことと他に委ねること）、owner、lifecycle、produces。ドラフトが候補をリストする場合は、エントリと次のステップを選択します。マーカーのない値はそのままにします。これらはコードから来ています。 - フローが
Ready=Trueになるまでatlas flowsを実行します。Resolved、Connected、またはEntryCalledがFalseの場合、コードまたはフローが間違っています。references/boundaries.mdを使用してどちらかを判断します。DocumentedがFalseの場合、作成者フィールドが空です。
1つのファイルに---で区切られた複数のフローを含めることができます。サーフェスIDはパスパラメータをOpenAPIテンプレート（{id}）として記述します。場所、エッジ、条件をファイルにコピーしないでください。atlasは実行ごとにそれらを計算します。フォーマットはflow-atlasパッケージのschema/flow.schema.jsonで、docs/schema.mdとdocs/responsibilities.mdで説明されています。
完了前
atlas check --since <開始リビジョン>を実行します。変更によって導入された検出結果のみが表示されます。- 各結果について：
atlas explain <キー>で場所と類似パスを表示します。その後、修正するか、例外を記録するか、誤検知を記録します。「検出結果の処理」を参照してください。 atlas diff <ベース>..WORKTREE --format markdown（または<ベース>..HEAD）と、新しい各サーフェスのtraceをPR説明または引き継ぎノートに記載します。
設定が遅れている場合
兆候：stderrのlimit:行（設定されたファイルが何も一致しない、ソースがベースラインの半分未満を生成する）、または既知の呼び出されるルートでのFA001。atlas inventoryを実行し、設定と比較して修正し（references/config.md）、atlas scanのカバレッジを再度確認します。atlas baseline updateの前に人に確認してください。
セットアップ
atlas inventoryは何も決定せずに候補をリストします。それから設定を記述し（references/config.md）、atlasが解析しないサーバーフレームワーク（Spring、Django、Flaskなど）の場合は、そのOpenAPIドキュメントを生成してルートをそこに向け（references/openapi.md）、すべてのソースが期待通り出力されるまでatlas scanを実行し、atlas checkを実行し、人と一緒に検出結果のサンプルを確認します。その後にのみベースラインを記録します。
検出結果の処理
最初にそれが欠陥、計画、誤検知のいずれかを判断します（references/boundaries.md）。その後：
-
検出結果がバグである場合は修正します。欠落している呼び出し元を配線し、デッドルートを削除し、プロデューサーを追加し、呼び出しを提供パスに向けます。
references/rules.mdにルールごとの一般的な原因がリストされています。 -
コードが意図的に正しい場合は、決定を命名した例外を追加します：
# flows/atlas-exceptions.yaml (または <out>/exceptions.yaml) - rule: FA001 key: FA001|orders|GET /orders/{id}/history reason: サービスが先に出荷されます。アプリ画面は次のリリースで追従します。 decidedBy: docs/orders.md#history reviewBy: 2026-12-31リポジトリ外のクライアントに提供されるサーフェスは、設定の
publicSurfacesに移動します。 -
検出結果が間違っている場合：`atlas feedback <キー> false-positive --note