openfga

OpenFGA のベストプラクティス

このスキルを使用して、OpenFGA モデルの設計とレビューを最初から最後まで行います。型とリレーションの定義、タプルの記述、can_* 権限の導出、userset と継承パターンの選択、.fga.yaml テストと CLI チェックによる動作の検証ができます。

クイックスタートの例

最小限のモデル：

model
  schema 1.1

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type document
  relations
    define organization: [organization]
    define owner: [user]
    define can_edit: owner or admin from organization
    define can_view: can_edit or member from organization

タプルの例：

organization:acme#admin@user:alice
document:roadmap#organization@organization:acme
document:roadmap#owner@user:bob

テスト対象の例：

• user:alice が document:roadmap を表示および編集できることを check する
• user:bob が自分のドキュメントを編集できることを check する
• document:roadmap#can_view に対する list_users
• user:alice が編集できるドキュメントに対する list_objects

使い方

ワークフローのステップでルール ID が示された場合は、references/ 内の該当ファイルを開き、詳しいガイダンスと例を確認してください。

注： SDK のリファレンス（sdk-*.md）が必要なのは統合作業の場合のみです。モデルの作成とテストのみを行う場合は、参照しないでください。

ルール一覧

コア

ファイル	説明
references/core-types.md	エンティティクラスの型を定義する
references/core-relations.md	リレーションはオブジェクト型に定義する
references/core-tuples.md	事実を表すリレーションシップタプル
references/core-separation.md	モデルとデータの分離
references/core-schema-version.md	スキーマのバージョン

リレーション

ファイル	説明
references/relation-direct.md	直接リレーションシップ
references/relation-indirect.md	Y から X を使用する間接リレーションシップ
references/relation-concentric.md	同心円状のリレーションシップ
references/relation-usersets.md	グループベースのアクセスに使用する userset
references/relation-conditions.md	条件付きリレーションシップ
references/relation-wildcards.md	パブリックアクセスに使用するワイルドカード
references/relation-wildcards-as-booleans.md	ブール属性に使用するワイルドカード

設計

ファイル	説明
references/design-permissions.md	can_ リレーションで権限を定義する
references/design-hierarchy.md	階層構造
references/design-organization.md	組織レベルのアクセス
references/design-create-on-parent.md	親オブジェクトに対する作成権限を確認する
references/design-naming.md	命名規則
references/design-modules.md	モデルをモジュール化する（依頼された場合のみ）

ロール

ファイル	説明
references/roles-simple.md	シンプルな静的ロール
references/roles-static-combo.md	静的ロールとカスタムロールの組み合わせ
references/roles-assignments.md	リソース固有のロールに対するロール割り当て
references/roles-when-to-use.md	各ロールパターンを使用するタイミング

最適化

ファイル	説明
references/optimize-simplify.md	モデルを簡素化する
references/optimize-tuples.md	タプル数を最小限に抑える
references/optimize-type-restrictions.md	型制約

テスト

ファイル	説明
references/test-fga-yaml.md	.fga.yaml でテストを構成する
references/test-check-assertions.md	check アサーション
references/test-list-objects.md	オブジェクト一覧のテスト
references/test-list-users.md	ユーザー一覧のテスト
references/test-conditions.md	条件のテスト
references/test-cli.md	OpenFGA CLI の使用
references/workflow-validate.md	モデルを必ず検証する

SDK（統合作業のみ）

ファイル	説明
references/sdk-javascript.md	JavaScript/TypeScript SDK
references/sdk-go.md	Go SDK
references/sdk-python.md	Python SDK
references/sdk-java.md	Java SDK
references/sdk-dotnet.md	.NET SDK

推奨ワークフロー

1. リソースグラフをモデル化します。 型、直接の関係、継承エッジ、can_* 権限を定義します。 最初に確認するルール：core-*、relation-*、design-permissions、design-hierarchy。

2. タプルを追加し、意図した動作をテストします。 代表的なタプルを追加し、check、list_objects、list_users のテストで期待される動作を網羅します。 次に確認するルール：core-tuples、test-fga-yaml、test-check-assertions、test-list-objects、test-list-users。

3. 親子の作成・削除パスを確認します。 各親 -> 子エッジについて、親に作成権限があること、および意図した場合を除いて子の権限を直接付与できないことを確認します。 確認するルール：design-create-on-parent、relation-direct、design-permissions。

4. スキーマを削除する前に簡素化します。 型または関係を削除する前に、権限、タプル、テストから参照されていないことを確認します。 簡素化によって参照が壊れた場合：関係を復元するか、モデル／テストを更新してから、この手順を再実行します。 確認するルール：optimize-simplify、optimize-tuples、optimize-type-restrictions。

5. モデルを検証します。 次を実行します。

fga model validate --file stores/<store>/model.fga

検証に失敗した場合：報告された関係または型のエラーを読み、モデルを修正してから、次に進む前に検証を再実行します。

6. ストアのテストを実行します。 次を実行します。

fga model test --tests stores/<store>/store.fga.yaml

テストに失敗した場合：タプル、アサーション、または権限定義を更新し、すべてのチェックとリストクエリが通るまでテストを再実行します。

7. その後にのみ、納品を完了します。 変更したストアについては、検証とテストが成功してから作業を完了します。 最後に確認するルール：workflow-validate。

コンパイル済みドキュメント全文

すべてのルールを詳しく説明した完全なガイド：AGENTS.md