atlas-onboard

Atlas のオンボーディング

Evaluating Atlas ガイド（https://atlasgo.io/guides/evaluation/intro）と同じ手順で、リポジトリを Atlas のセットアップがない状態から本番環境まで、6 つのステージで進めます。各ステージの最後に、エージェントが実行してユーザーに提示する確認項目があります。このスキルでは、順序、判断事項、確認項目を定めます。コマンドのリファレンスは atlas スキルにあります。

ファイル

このスキルは SKILL.md と 7 つのファイルで構成され、各ファイルは https://atlasgo.io/skills/atlas-onboard/<path> で提供されます。 agents/openai.yaml、references/stage-0-plan.md、references/stage-1-schema.md、 references/stage-2-workflow.md、references/stage-3-ci.md、references/stage-4-deploy.md、および references/stage-5-promote.md です。各ステージの開始時に、そのステージのリファレンスを読みます。

必要なもの

このスキルと同じ場所にインストールされた atlas スキル（../atlas/SKILL.md）が必要です。見つからない場合は、開始前に https://atlasgo.io/skills/atlas/SKILL.md を ../atlas/SKILL.md にダウンロードし、その「Files」セクションに記載された各リファレンスファイルを ../atlas/references/<name> にダウンロードしてください。以下で atlas/ から始まるパスは、そのスキル内を指します。

PostgreSQL、MySQL、または MariaDB の場合は、このスキルと同じ場所にインストールされたデータベーススキルも必要です。PostgreSQL の場合は atlas-postgres（../atlas-postgres/SKILL.md）、MySQL と MariaDB の場合は atlas-mysql（../atlas-mysql/SKILL.md）を使用します。このスキルには、開発用データベース、URL のスコープ、確認する lint の検出事項など、各エンジンのルールが記載されています。ステージ 0 でエンジンが判明したら一度読み、すべてのステージでその内容に従ってください。見つからない場合は、ユーザーにインストールを勧めてください。Claude Code では claude plugin update atlas@ariga を、ほかのエージェントでは npx skills add ariga/atlas -a <agent> -y コマンドを再度実行します。それまでは、 https://atlasgo.io/skills/atlas-postgres/SKILL.md または https://atlasgo.io/skills/atlas-mysql/SKILL.md から読み込んでください。

ステージ 4 で Atlas Kubernetes Operator（4.6、4.7）を使用してデプロイする場合は、atlas-operator スキル（../atlas-operator/SKILL.md）も読みます。見つからない場合は、同じ方法でインストールして読み込んでください。 https://atlasgo.io/skills/atlas-operator/SKILL.md から入手できます。このスキルでは、オペレーターのインストール、トークン、リソースポリシー、トラブルシューティングについて説明しています。

ステージ 3 とステージ 4 の CI デプロイジョブでは、atlas-action スキル（../atlas-action/SKILL.md）も読みます。見つからない場合は、同じ方法でインストールして読み込んでください。 https://atlasgo.io/skills/atlas-action/SKILL.md から入手できます。このスキルでは、各プラットフォームでの Atlas CI の手順、トークンと権限、および各手順が失敗した場合の修正方法について説明しています。

ステージ

ステージ	セットアップする内容	読むファイル	完了条件
0 計画	ログイン、データベースの棚卸し、ユニット、パイロット、ワークフロー	references/stage-0-plan.md	ユーザーがユニット、パイロット、ワークフローを承認した
1 スキーマをコード化	atlas.hcl と望ましい状態：SQL または HCL にエクスポートしたデータベース、または ORM モデル	references/stage-1-schema.md	atlas schema apply --env local --dry-run が変更なしを報告する
2 マイグレーションワークフロー	バージョン管理方式：ベースラインマイグレーションと migrate diff ループ。宣言的方式：schema apply ループ	references/stage-2-workflow.md	バージョン管理方式：atlas migrate diff がディレクトリの同期済みを報告し、プロジェクトの PR が作成されている
3 CI	プルリクエストでの lint（バージョン管理方式）または plan（宣言的方式）、マージ時の Atlas Registry へのプッシュ	references/stage-3-ci.md	マージ時に CI が成功し、Atlas Registry にそのバージョンがある
4 ステージング環境にデプロイ	Atlas Registry からのステージング環境へのデプロイと、ステージング環境へのデプロイに使っていた旧ツールの停止	references/stage-4-deploy.md	Atlas Cloud にステージング環境へのデプロイが記録されている
5 本番環境に昇格	ステージング環境で実行したバージョンのみを本番環境に適用（環境間の昇格）	references/stage-5-promote.md	ユーザーがステージング環境のバージョンを使って、最初の本番デプロイを実行した

まずパイロットのユニットで各ステージを実行します。そのほかのすべてのユニットでは、記録済みの判断事項を使ってステージ 1 から 5 を繰り返します。パイロットの完了後、引き継ぎます。

ルール

1. 推測せず、検出してください。各セッションの開始時に、「ステージを検出」を実行してください。進捗は会話の中ではなく、デフォルトブランチ、オープンプルリクエスト、Atlas Cloud にあります。
2. データベースを読み取る前にログインしてください。ログアウト状態では、atlas schema inspect と atlas schema diff はビュー、関数、プロシージャ、トリガーなどのオブジェクトをスキップしても、終了コード 0 を返します。その状態でエクスポートしたスキーマには、これらのオブジェクトが含まれません。スキップの通知はマシンごとに一度だけ表示されるため、通知が表示されないことは何の証明にもなりません。最初に atlas whoami を実行してください。
3. 各ステージに記載された判断が必要な箇所でのみ質問してください。それ以外では、指定されたデフォルトを選び、どれを選んだか伝えてください。
4. プルリクエストのために最初のファイルを書き込む前に、最新のデフォルトブランチから、作業ツリーがクリーンな状態で atlas-onboard/<unit>-<stage> ブランチを作成してください。ステージ 2 はステージ 1 のブランチで続けてください。どちらもプロジェクトのプルリクエストに含まれるためです。それ以降の各ステージでは、それぞれ独自のブランチを開始してください。ファイルはパスを指定してステージし、git add -A は使わないでください。すべての変更はプルリクエストとして反映し、プルリクエストをレビューのゲートとします。別の GitOps リポジトリには、独自のプルリクエストを作成してください。
5. 共有環境の認証情報を会話に入力してはいけません。ユーザーはエージェントを起動するシェルで URL 変数をエクスポートします。! コマンドを使うと値が会話に入力されてしまいます。test -n "$STAGING_DATABASE_URL" && echo set を使って変数を確認してください。そのような URL を表示、解析、エコーしてはいけません。また、.env、*.tfvars、その他のシークレットファイルを開いてはいけません。リポジトリで定義されているローカル開発用の認証情報、たとえば compose サービスのパスワードはシークレットではありません。
6. 各ステージの最後に、そのステージの確認を行ってください。コマンドとその出力を示してください。確認を実行できない場合（変数が設定されていない、Docker が実行されていない、ネットワークがないなど）は、ステージの失敗ではありません。前提条件を満たしてから、再実行してください。
7. 作業を進めながら説明してください。「用語集」にある各用語は、初めて使うときに一文で定義してください。各ステージの後に、何ができたのか、なぜそれが必要なのかを 2～3 文で説明し、「ドキュメントマップ」から該当ページへのリンクを示してください。
8. スキーマはローカルまたは開発用データベースから読み取ってください。エージェントは自分でデータベースを見つけて接続できます。リモート環境を読み取るのは、ユーザーが依頼し、接続情報を提供した場合のみです。リモート URL や認証情報を探してはいけません。エージェントを本番データベースに接続することは推奨されません。リモート環境では、読み取り専用ロールを推奨してください。また、データベースが対応している場合は、クラウドサインインも推奨してください（ステージ 1、「リモートデータベース」）。

権限

操作	ルール
リポジトリのスキャン、schema inspect、migrate lint、atlas cloud の読み取り、--dry-run（計画のみで、変更なし）	実行する
リポジトリ内のファイルの書き込み、ブランチ、プルリクエスト	実行する。プルリクエストがゲートです
Atlas Cloud リポジトリ、ボットトークン、CI シークレットの作成（最初の migrate push または schema push、あるいは create-repo アクション）	事前に確認する
ローカルまたは docker:// の開発用データベース以外に対する migrate apply または schema apply	事前に明示的な承認、対象の指定、ドライランが必要
本番環境のデプロイ設定	ユーザーから依頼された場合に限り、別のプルリクエストで行う
計画、レビュー、デプロイ、ワークフロー実行、プルリクエストの承認	決して行わない。保留中の項目とその場所をユーザーに伝える

プロジェクトの構成

各ユニットは、それを管理するコードの隣にある独自のディレクトリ内に配置された Atlas プロジェクトです（例：services/billing/db/）。 ユニットが 1 つだけのリポジトリでは、ルートを使用できます。ユニットのディレクトリには、atlas.hcl、期待される状態（ソースが ORM でない場合は schema/）、バージョン管理するユニットの場合はマイグレーションディレクトリ（migrations/）を配置します。すべての atlas.hcl で同じ環境名を使用することで、Atlas Cloud に実際の環境名が表示されます。

Env	用途	記述場所
local	スキーマの読み取り元となるローカルまたは開発用データベース。開発者が変更を適用する場所であり、マイグレーションの生成とリントにも使用します	ステージ 1
staging	ステージングへのデプロイ。初回デプロイ前の読み取り専用チェック	ステージ 4（スキーマをステージングから読み取る場合のみステージ 1）
ci	CI でのリントとレジストリへのプッシュ	ステージ 3
prod	ステージングから昇格する本番環境へのデプロイ	ステージ 5

Atlas コマンドはすべて、ユニットのディレクトリから実行してください。

ステージの判定

1. atlas whoami を実行します。失敗した場合はユーザーにログインを依頼してから、続行します。
2. git fetch origin を実行します。以下のファイルは作業ツリーではなく、デフォルトブランチから読み取ります（git show origin/<default>:<path>）。
3. 以前のセッションで未完了の作業が残っていないか確認します。git branch -r --list 'origin/atlas-onboard/*' と、オープン中の PR を確認します（インストール済みの場合は gh pr list または glab mr list、それ以外の場合はユーザーに確認します）。新しいブランチを作成するのではなく、オープン中のブランチで続行します。
4. ステージ 0 のスキャン項目（0.1）を CI システムとデプロイツールについて再実行します。データベースは必要ありません。
5. .atlas-onboarding.json にある各ユニットについて、まずパイロットを行い、最後に完了したステージを特定します。ステージ 5 から順に確認し、最初に条件を満たしたステージを最後に完了したステージとします。ユニットの deferred に記載されたステージは完了済みとして扱います。

ステージ	完了条件
5	prod 環境がステージングから昇格し（to_version、src 内の version、または deny チェックによって）、atlas cloud migration list --repo <repo> --env-name prod --status PASSED にデプロイが表示される
4	atlas cloud migration list --repo <repo> --env-name staging に、atlas migrate ls --dir atlas://<repo> --latest --short が出力するバージョンの PASSED または NO_ACTION が表示される
3	デフォルトブランチ上のワークフローで、ユニットの Atlas lint（バージョン管理方式）または plan（宣言方式）が実行され、デフォルトブランチ上の最後のプッシュ実行が成功している
2	プロジェクトの PR がマージ済みである。atlas.hcl とソースがデフォルトブランチにあり、バージョン管理するユニットでは migrations/atlas.sum も存在する
1	ユニットの atlas.hcl とソースがオンボーディング用ブランチに存在し、atlas schema apply --env local --dry-run で変更なしと報告される
0	ユニットが .atlas-onboarding.json に含まれている

チェックリスト

これを会話にコピーし、完了した項目にチェックを付けてください。

Stage 0  [ ] scan  [ ] atlas login  [ ] inventory  [ ] units + pilot (user)  [ ] workflow (user)
Stage 1  [ ] atlas.hcl  [ ] desired state (export or ORM)  [ ] dry run: no changes
Stage 2  [ ] baseline (versioned)  [ ] new local database from the directory (versioned)  [ ] change loop shown  [ ] lint shown (versioned)  [ ] project PR
Stage 3  [ ] bot token + secret (user)  [ ] first push (ask)  [ ] CI PR  [ ] green run  [ ] CI pushed the merge
Stage 4  [ ] cutover plan  [ ] deploy config PR  [ ] staging dry run  [ ] staging deployment recorded
Stage 5  [ ] prod env with promotion (when asked)  [ ] prod deploy behind approval  [ ] first prod deploy (user)
Hand off [ ] AGENTS.md  [ ] skill in repo  [ ] next steps  [ ] summary + next unit

決定事項ファイル

リポジトリのルートにある .atlas-onboarding.json には、リポジトリから確認できない情報だけを記録します。ファイルを直接更新し、その変更を行ったステージの PR とともに、変更をコミットします。

{
  "workflow": "versioned",
  "units": [
    { "name": "identity", "dir": "services/identity/db", "repo": "identity", "schemas": ["identity"], "pilot": true },
    { "name": "billing", "dir": "services/billing/db", "repo": "billing", "schemas": ["billing"] }
  ],
  "deploy": { "target": "argocd", "gitops_repo": "github.com/acme/gitops" },
  "deferred": [{ "unit": "billing", "stage": 4, "reason": "deployments are owned by the platform team" }]
}

workflow は versioned または declarative です。repo はレジストリのリポジトリスラッグです。このファイルにはデータベース URL、トークン、ステータスを保存しないでください。ステータスは上記のチェックから確認できます。

用語

• 望ましい状態：SQL、HCL、または ORM モデルで記述された、あるべきスキーマです。どちらのワークフローもここから始まります。
• バージョン管理ワークフロー：atlas migrate diff が望ましい状態への各変更をマイグレーションファイルとして書き出し、レビュー後、順番に適用します。宣言的ワークフロー：マイグレーションファイルはありません。atlas schema plan と atlas schema apply が対象データベースに対する各変更を計画し、その計画をレビューします。
• 開発用データベース：Atlas が変更の計画と確認を行うためのサンドボックスとして使う、一時的で分離されたデータベースです。通常は一時的な Docker コンテナです（https://atlasgo.io/concepts/dev-database#introduction）。データが保存されることはなく、アプリケーションの開発用データベースでもありません。
• ベースライン：バージョン管理された単位の最初のマイグレーションファイルで、既存のスキーマのスナップショットです。既存のデータベースでは、実行せずに適用済みとして記録します。
• 単位：1 つの Atlas プロジェクト、スキーマ、または 1 つのチームが所有するテーブルの集合です。パイロット：他の単位に着手する前に、すべてのステージを完了する最初の単位です。
• Atlas Registry：CI がプッシュし、デプロイ時に読み取る、Atlas Cloud 上のマイグレーションディレクトリまたはスキーマのコピーです。
• ボットトークン：CI 用の Atlas Cloud 認証情報で、個人には紐づきません。
• 環境の昇格：本番環境では、ステージングにすでにデプロイされたバージョンのみを適用します。

引き継ぎ

パイロットがステージ 5（またはユーザーが希望する最後のステージ）を完了したら：

1. AGENTS.md に Atlas のセクションを追加します。必要に応じてファイルを作成します。リポジトリに CLAUDE.md がある場合は、@AGENTS.md の行を追加します。

   ## Database schema (Atlas)
   
   - Unit `<unit>` in `<dir>`: `atlas.hcl`, desired state in `schema/` (or the ORM models), migrations in
     `migrations/`. Run Atlas from `<dir>`.
   - Change the desired state, then run `atlas migrate diff --env local <name>`. A new file in `schema/`
     needs an `-- atlas:import` line at the top of `schema/main.sql`.
   - Never edit an applied migration. After editing an unapplied one, run `atlas migrate hash --env local`.
   - Before opening a PR: `atlas migrate lint --env local --latest 1`.
   - Deployments run from <CI workflow or GitOps target>, staging first, then production promoted from
     staging. Never run `migrate apply` or `schema apply` against a shared database from a laptop.
   - Use the `atlas` skill for schema work.
   

   宣言的な単位の場合、変更の手順は次のとおりです。望ましい状態を変更し、ローカルデータベースに対して atlas schema apply --env local を実行します。CI が PR 上でレビュー用に変更を計画します。PostgreSQL の場合、最後の行で両方のスキルを指定します。スキーマ作業には atlas と atlas-postgres のスキルを使用します。MySQL と MariaDB の場合は、代わりに atlas-mysql を指定します。

2. すべてのチームメンバーのエージェントが使えるよう、スキルのコミットを提案します。

   • Claude Code：これらのキーを .claude/settings.json に統合します。Claude Code は、リポジトリフォルダーを信頼する各チームメンバーに対して Atlas プラグインをインストールします。

     {
       "extraKnownMarketplaces": {
         "ariga": { "source": { "source": "github", "repo": "ariga/atlas" } }
       },
       "enabledPlugins": { "atlas@ariga": true }
     }
     

   • Codex、Cursor、GitHub Copilot：リポジトリのルートから npx skills add ariga/atlas -a <agent> -y を実行し、codex、cursor、または github-copilot を指定して、.agents/skills/ と skills-lock.json をコミットします。インストール時にすでにこれらのファイルが配置されている場合は、変更せずにコミットします。

3. 次のステップ：スキャン結果に合ったガイドのプラクティスを、一度に 1 つ提案します。全リストは https://atlasgo.io/guides/evaluation/advanced-topics を参照してください。

   プラクティス	ガイド
   本番環境ではレビューと承認を受けたマイグレーションのみを適用する	https://atlasgo.io/guides/reviewed-approved-migrations
   廃止ワークフローを使って、CI で誤った削除をブロックする	https://atlasgo.io/guides/destructive-change-policy
   デプロイ時およびデプロイ間のドリフトを検出する	https://atlasgo.io/guides/drift-detection
   関数、ビュー、トリガー、データマイグレーションをテストする	https://atlasgo.io/testing/schema
   PostgreSQL でロックに安全な NOT NULL 変更を行う	https://atlasgo.io/guides/lock-safe-not-null
   各チームが所有するオブジェクトのみを変更する	https://atlasgo.io/guides/schema-ownership
   ロール、権限、行レベルセキュリティをコードとして管理する	https://atlasgo.io/guides/security-as-code
   テナントごとにデータベースを分けた構成で、段階的にロールアウトする	https://atlasgo.io/guides/database-per-tenant/rollout

4. ステージごとに、現在あるもの、そのドキュメントページ、保留にした内容とその理由、残っている単位をまとめます。次の単位では、ユーザーがこのスキルを再度実行します。Detect the Stage がステージ 1 から開始します。

ドキュメントマップ

ステージ	読む項目
0	接続, ワークフローを選ぶ, 宣言型とバージョン管理型の比較
1	Atlas を検証してスキーマをエクスポートする, コードとしてのスキーマ, 開発用データベース, ORM ガイド
2	マイグレーションのワークフローを設定する, スキーマ変更のワークフロー, マイグレーションのリント
3	データベースの CI/CD, バージョン管理型の CI/CD, 宣言型の CI/CD
4	Atlas Cloud でのデプロイ, デプロイガイド, 既存のデータベース
5	環境の昇格, 宣言型の環境昇格

注意点

• atlas.hcl の組織ピンが保護するのは、これを読み込む（--env を指定する）コマンドだけです。--url を直接指定するコマンドはログアウト状態で実行されるため、実行前に atlas whoami を実行してください。
• コマンドラインの --exclude は、環境の exclude リストに追加されるのではなく、リストを置き換えます。除外設定は 環境に記述し、--env と一緒に --exclude を指定しないでください。
• 除外パターンは URL のスコープに従います。スキーマスコープの URL では、パターンはそのスキーマ内のオブジェクトを指定します。 テーブルには audit_*、すべての関数には *[type=function] を指定します。データベーススコープの URL では、 最初のセグメントでスキーマを指定します。たとえば、public.audit_*、public.*[type=function]、またはスキーマ全体を 除外する internal を指定します。
• 開発用データベースは、ターゲットのエンジンバージョンとスコープに一致している必要があります（https://atlasgo.io/concepts/dev-database）。 スコープが一致しないと、modify schema "<name>" is not allowed when migration plan is scoped to one schema というエラーが発生するか、拡張機能が 気付かないうちに削除されます。
• すべてのテーブルで同じ差異（照合順序、文字セット、所有者）がある場合は、開発用データベースのデフォルト設定がターゲットと 異なっています。開発用データベースを修正し、そのためのマイグレーションは決して作成しないでください。
• SQL ソースを分割した場合（schema/main.sql とオブジェクトごとのファイル）、読み込まれるのは main.sql がインポートする ファイルだけです。新しいファイルを追加するには、main.sql の先頭にあるディレクティブブロックに -- atlas:import <path> の行を追加してください。前に空行を入れてはいけません。そうしないと無視され、migrate diff は変更なしと報告します。
• getenv() を読み込む環境での Error: missing scheme は、エージェントのシェルで変数が設定されていないことを意味し、 ステージが失敗したという意味ではありません。
• ベースラインバージョンが設定されていないと、既存データベースに対する最初の migrate apply は connected database is not clean で中断します。baseline を設定し、--allow-dirty で回避しないでください。
• Codex はデフォルトで workspace-write サンドボックス内でコマンドを実行し、ユーザーが承認するまで外部ネットワークアクセスは無効です。 Atlas Cloud とデータベースにはネットワークが必要なため、ステージの検出を始める前に、Atlas コマンドの実行またはネットワークアクセスの有効化をユーザーに依頼してください。
• クラウドエージェントが作成したプルリクエストでは、人間が実行を承認するまで CI が実行されないことがあります。チェックが 承認待ちの場合は、その旨をユーザーに伝えてください。