コーディングエージェントガイド

pnpm 11/12 と npm の使い分けはコマンドとトラブルシューティングを参照してください。

SwallowKit はコーディングエージェントの開発プロセスを置き換えません。要件整理、仕様化、計画、TDD、実装、レビューと合成できる、プロジェクト検査、決定論的な変更操作、責務境界、検証ガードレールを提供します。

machine/MCP のコマンドとレスポンス契約の詳細は AI / MCP 統合を参照してください。

目的

開発プロセス Skill は、作業をどのように進めるかを決定します。 SwallowKit は、現在のプロジェクトをどのように安全かつ再現可能に検査・変更するかを決定する、プロジェクト固有の authoritative layer です。

text

開発プロセス / エンジニアリングプラクティス
  例: process Skill、Spec Kit、GSD、BMAD、
      独自 Skill、通常の Agent interaction
                    │
                    │ intent / specification / task
                    ▼
             SwallowKit contract
                    │
        ┌───────────┼────────────┐
        │           │            │
     inspect     plan/apply     verify
        │           │            │
        └───────────┼────────────┘
                    ▼
       deterministic Azure application

SwallowKit は current-project inspection、deterministic artifact generation、 drift detection、structural verification、failure explanation、infrastructure guardrail を担います。独自の要件、仕様、チケット、semantic review framework は導入しません。

生成される Agent integration files

swallowkit init は、同じ大きな規約を Agent ごとに繰り返すのではなく、階層化された integration を生成します。

ファイル	役割
`AGENTS.md`	canonical always-on project contract
`CLAUDE.md`	`AGENTS.md` を参照する Claude Code adapter
`.github/copilot-instructions.md`	`AGENTS.md` を参照する GitHub Copilot adapter
`.github/instructions/*.instructions.md`	path/layer-specific rules
`.mcp.json`	project-scoped SwallowKit MCP bootstrap
`.github/skills/*/SKILL.md`	task-specific Agent Skills
`.swallowkit/workflows/*.md`	Agent-neutral fallback runbooks

adapter 自身にも、AGENTS.md を読む前から SwallowKit を認識できる最低限の always-on rule が含まれます。task-specific な詳細は Skills/runbooks に置き、 canonical contract を百科事典ではなく operational contract に保ちます。

開発ライフサイクル全体での SwallowKit

Discovery と requirements clarification

実装詳細を人間に質問する前に、現在のプロジェクト、関連する entity、route、infra、 ownership boundary を検査します。repository や SwallowKit から判明する事実は Agent が回答し、人間への質問は本物の product/domain decision に限定します。

Specification

user intent、observable behavior、acceptance criteria、重要な test seam を記述します。 SwallowKit architecture と ownership は implementation constraint として扱い、生成される各 layer を独立した手動実装 component として記述しません。

Planning

capability や ownership が設計判断を変える場合は current interface を検査します。学習時のモデル知識から SwallowKit capability を推測してはなりません。

Ticket decomposition

独立して価値があり検証可能な vertical slice を優先します。1つのモデル変更から schema contract、Functions、BFF、UI、infra が決定論的に導出される場合、それらは同じ behavioral slice に含めます。

text

Todo に priority support を追加
  ├─ source-of-truth model を変更
  ├─ managed artifact を plan/apply
  ├─ custom behavior と test を追加
  └─ project を verify

生成ファイルが horizontal layer に分かれているという理由だけで、schema、backend、 BFF、UI、infra の別チケットを作成しません。

Implementation

ファイルを選ぶ前に responsibility boundary を検査します。ai-authored は通常どおり編集し、 deterministic は source of truth と plan/apply だけで変更し、shared は managed marker の外側だけを編集します。

Verification

実装後に SwallowKit verification を実行し、明示的な人間の判断が必要になるか収束するまで、構造化された failure evidence に従います。

Review

mechanical な SwallowKit verification の後に semantic/specification/engineering review を実施します。この2つの gate は異なる問いに答えるため、相互に代替できません。

質問・設計の前に inspect する

タスクに関係する inspection だけを利用します。

npmpnpm

bash

npx swallowkit machine inspect project
npx swallowkit machine inspect entities
npx swallowkit machine inspect routes
npx swallowkit machine inspect boundaries
npx swallowkit machine inspect drift
npx swallowkit machine inspect infra

bash

pnpm exec swallowkit machine inspect project
pnpm exec swallowkit machine inspect entities
pnpm exec swallowkit machine inspect routes
pnpm exec swallowkit machine inspect boundaries
pnpm exec swallowkit machine inspect drift
pnpm exec swallowkit machine inspect infra

利用可能なら同等の swallowkit_* MCP tools を優先し、利用できない場合は Agent-facing fallback として machine interface を使います。

これにより、generated CRUD layer の wiring、managed route の編集可否、infra operation の有無など、current inspection で回答できる質問を人間へ転嫁しません。一方、曖昧な product behavior、business rule、risk choice は適切に人間へ確認します。

Responsibility boundary

machine inspect boundaries（または swallowkit_inspect_boundaries）が現在の project の machine-readable authority です。

zone	編集ポリシー	典型例
`ai-authored`	直接編集する	source-of-truth model、custom logic/UI、test
`deterministic`	決して手編集せず source/config と plan/apply で変更する	generated CRUD、BFF、UI、schema、infra artifacts
`shared`	managed marker の外側だけ編集する	SwallowKit section を含む集約・infra files

例は inspection の代わりにはなりません。ownership は backend、feature、SwallowKit version によって変わり得ます。

Planning と ticketing

仕様は generated-file mechanics ではなく desired behavior を中心にします。計画には SwallowKit constraint と plan/apply/verify loop を記録できますが、deterministic output を独立した manual work として扱いません。

ticket boundary は、独立して実装・検証できる vertical/tracer-bullet slice とします。 horizontal ticket は、generated directory が別という理由ではなく、独立した価値やリスクが本当に存在する場合だけにします。

Implementation workflow

Agent の標準 workflow は次のとおりです。

text

inspect → plan → conflict/approval の評価 → apply → verify

runtime が公開している場合は MCP tools を優先し、それ以外では structured machine operations を使用します。

npmpnpm

bash

npx swallowkit machine inspect drift
npx swallowkit machine plan scaffold todo
npx swallowkit machine apply scaffold --plan <planId>
npx swallowkit machine verify project

bash

pnpm exec swallowkit machine inspect drift
pnpm exec swallowkit machine plan scaffold todo
pnpm exec swallowkit machine apply scaffold --plan <planId>
pnpm exec swallowkit machine verify project

Agent Skills 対応 runtime では swallowkit-add-model、swallowkit-modify-model、 swallowkit-verify-repair を利用します。それ以外では対応する .swallowkit/workflows/ runbook を読みます。これらは上位の implementation process から呼び出せる task-level capability です。

エージェントへの依頼例

モデル変更は、生成ファイルごとの修正ではなく、実現したい振る舞いとして依頼します。

Todo に優先度を追加してください。このプロジェクトの AGENTS.md と関連する Skill／workflow を読み、選択済みのパッケージマネージャーを維持してください。編集前に ownership と drift を確認し、モデルを変更したら scaffold の Plan を作成してください。変更対象と競合を確認して Apply し、 verify と優先度の振る舞いを確認するテストまで実施してください。手編集の上書きなど判断が必要な場合は、対象の差分と選択肢を示してください。

ここでの Plan は SwallowKit が返す変更計画です。エージェントの文章による作業計画や Plan モードとは別で、生成対象・競合・planId を持ちます。Plan は生成対象を変更しませんが、計画自体は .swallowkit/state/plans/ に保存します。内容を確認した Plan の planId を Apply に渡してください。

stale-plan が返ったら、計画時に記録したファイルが変更されています。現在の差分を調べ、 Plan を作り直して再確認します。--approve は古い Plan を有効にするオプションではありません。 requires-human の場合は、求められた判断を確認してから進めます。競合のない通常の変更に、一律の追加承認手順を設ける必要はありません。

ドリフトが見つかったとき

ドリフトは、モデル・生成時の記録・現在のファイルなどの間のずれです。 machine inspect drift の finding にある種類、重要度、repairAction と、 machine inspect boundaries の編集ポリシーを合わせて確認します。 finding があるだけで、すべてを上書きする必要があるとは限りません。

finding	エージェントが確認すること
`schema-drift`	意図したモデル変更か確認し、対象モデルの scaffold を Plan → Apply します。
`artifact-modified`	生成後の差分と ownership を確認します。ユーザー編集が認められる領域の変更は正常な場合があります。必要なカスタマイズを消さないでください。
`artifact-missing`	削除が意図したものか確認し、必要な生成物を再生成します。
`generator-drift`	生成時と実行中の SwallowKit のバージョンを確認し、更新を採用する場合は再生成の差分をレビューします。
`manifest-drift`	実際のプロジェクト構造と記録のずれを調べ、提示された `repairAction` に従います。

MCP は既定で latest、通常の CLI はプロジェクトに固定されたバージョンを使います。バージョン差がある場合は同じ環境だと決めつけず、各インターフェースの現在の機能を確認してください。 Plan と Apply は同じプロジェクト・同じバージョンの実行経路で行います。 MCP のバージョン指定はパッケージマネージャーガイドを参照してください。

修復後は machine verify project を実行し、失敗時は machine explain failure の証拠を確認します。ドリフトが解消しても、依頼した機能の振る舞いや Azure デプロイの成功まで証明されたわけではありません。それぞれのテスト・実行結果で確認してください。

Verification と semantic review の違い

SwallowKit verification が問うこと:

project は mechanically/structurally correct で、managed artifact drift がなく、 configured check に成功しているか？

Semantic review が問うこと:

design と behavior は正しいか？ specification と user intent を満たすか？

推奨順序:

text

implementation → SwallowKit verify → semantic code review

verification が失敗した場合は machine explain failure または MCP equivalent を使い、正しい source を修復して再度 verify します。

Human approval

machine operation は terminal state と nextActions を返します。requires-human は意図的な停止であり、回避すべき error ではありません。Agent は指定された判断を人間に求め、 approval を捏造してはなりません。

Azure provisioning は常に swallowkit-provision Skill/runbook と明示的 approval gate を利用します。deployment 完了までという広い依頼であっても、plan 提示後に必要となる approval が暗黙に付与されたことにはなりません。

外部 development process との composition

任意の process framework が discovery、specification、ticketing、TDD、implementation orchestration、semantic review を提供し、current-project facts と deterministic operation に SwallowKit を呼び出せます。この関係は custom Skills、Spec Kit、GSD、BMAD、通常の Codex、 Claude Code、GitHub Copilot interaction に共通です。

例: Matt Pocock Skills

以下は推奨 composition の例であり、互換性保証や dependency ではありません。

text

grill-with-docs
    ├─ 必要に応じて project/entities/routes/boundaries を inspect
    ├─ repository/SwallowKit で回答可能な質問は自律的に回答
    └─ 本物の product/domain decision だけを人間に質問
    ↓
to-spec
    ├─ intent と observable behavior を記述
    ├─ SwallowKit architecture/ownership を constraint に含める
    └─ generated layer を独立した manual implementation として扱わない
    ↓
to-tickets
    ├─ vertical / tracer-bullet slice を維持
    └─ generated schema/API/BFF/UI/infra work は slice 内に含める
    ↓
implement
    ├─ boundaries を inspect
    ├─ ai-authored → 通常の implementation/TDD
    ├─ deterministic → SwallowKit plan/apply
    ├─ shared → managed marker の外側を編集
    └─ SwallowKit verify
    ↓
code-review
    └─ mechanical verification 後に semantic/spec/engineering review

SwallowKit は hard dependency ではなく composition によって Matt Pocock Skills をサポートします。 SwallowKit はこれらの Skills を install、vendor、fork、rewrite しません。

完全な生成 Agent documents

以下は swallowkit init が利用する完全な英語 template であり、抜粋ではありません。、、、、、は選択した project に合わせて展開されます。 docs は canonical template を直接 import するため、generator wording と English original は同じ source を共有します。

生成される AGENTS.md

English original

# AGENTS.md

This project was generated by **SwallowKit**.

SwallowKit is part of this project's architecture and development workflow.
Treat it as a standing constraint during discovery, requirements clarification,
specification, planning, ticket decomposition, implementation, verification,
and review — not only during code generation.

## How SwallowKit Fits Into the Development Process

SwallowKit does **not** own the overall software development process.

If the user or another Agent Skill or framework defines a process for
requirements discovery, specification, planning, ticketing, TDD,
implementation, or review, continue to follow that process.

Use SwallowKit as the authoritative project-specific layer for:

- inspecting the current project
- understanding entities, routes, infrastructure, and responsibility boundaries
- determining which artifacts may be edited directly
- performing deterministic generation through plan/apply
- detecting drift
- verifying the resulting project
- enforcing human approval gates for sensitive operations

External development-process skills and SwallowKit are intended to compose.

A process skill decides **how to proceed**.
SwallowKit determines **how this SwallowKit project can be changed safely and reproducibly**.

## Do Not Assume SwallowKit Capabilities From Memory

SwallowKit evolves over time.

Do not rely on model knowledge or assumptions about what SwallowKit can or
cannot generate.

When a SwallowKit capability, project structure, or ownership boundary affects
a design decision, inspect the current project and the currently available
SwallowKit interfaces before deciding.

Prefer the `swallowkit_*` MCP tools when available.

If MCP is unavailable, use the machine interface:

```bash
{{runCmd}} swallowkit machine ...
```

The machine interface is the fallback Agent-facing interface and returns
structured `status` / `nextActions` suitable for autonomous workflows.

## Inspect Before Asking or Designing

When a task may affect SwallowKit-managed application structure, inspect the
project before asking the human questions or committing to an implementation
design.

Use only the inspections relevant to the task. Typical inspections include:

```bash
{{runCmd}} swallowkit machine inspect project
{{runCmd}} swallowkit machine inspect entities
{{runCmd}} swallowkit machine inspect routes
{{runCmd}} swallowkit machine inspect boundaries
{{runCmd}} swallowkit machine inspect drift
{{runCmd}} swallowkit machine inspect infra
{{runCmd}} swallowkit machine inspect capabilities
```

`inspect capabilities` answers "what can SwallowKit do" (supported model
declarations with exact formats, the correct auth-introduction workflow, what
generated CRUD does and does not guarantee, how seeds are applied). Use it
instead of guessing or grepping SwallowKit internals.

Use the equivalent `swallowkit_*` MCP tools when available.

Questions that can be answered from the repository or SwallowKit inspection
should be answered by the agent instead of being delegated to the human.

Examples:

- Do not ask how generated CRUD layers should be wired if SwallowKit already
  defines and generates them.
- Do not propose editing a generated file until responsibility boundaries have
  been checked.
- Do not assume an infrastructure capability is unavailable before inspecting
  the current SwallowKit project and available operations.

## Specification and Planning Guidance

When producing or refining a specification:

- describe user-visible behavior and domain intent
- define acceptance criteria and important test seams
- treat SwallowKit's architecture and responsibility boundaries as
  implementation constraints
- avoid prematurely describing generated artifacts as manually implemented
  components
- do not duplicate work that SwallowKit can deterministically derive from its
  source of truth

For example, if adding a model field causes SwallowKit to regenerate backend,
BFF, UI, and infrastructure artifacts, the specification should primarily
describe the desired end-to-end behavior and the SwallowKit constraint.

It should not imply that every generated layer is an independent manual
implementation decision.

If whether SwallowKit supports the desired behavior affects the specification,
inspect the current capabilities before finalizing the spec.

## Ticket Decomposition Guidance

Prefer independently verifiable **vertical slices** of user or system behavior.

Do not split work into horizontal tickets such as:

- schema ticket
- backend ticket
- BFF ticket
- UI ticket
- infrastructure ticket

merely because those artifacts exist in separate layers.

When SwallowKit deterministically produces those layers, keep them inside the
same vertical slice whenever they represent one end-to-end behavior.

Example:

```text
Add priority support to Todo
  ├─ update the source-of-truth model
  ├─ use SwallowKit plan/apply to realign managed artifacts
  ├─ add any required ai-authored business logic
  ├─ add/update tests
  └─ verify the project
```

Ticket boundaries should reflect independently valuable and verifiable
behavior, not SwallowKit's generated file structure.

## Responsibility Boundary

Before making file-level implementation decisions, inspect the current
machine-readable boundary contract:

```bash
{{runCmd}} swallowkit machine inspect boundaries
```

Treat its current result as authoritative.

The general ownership model is:

### ai-authored

The agent may edit these directly.

Typical examples include:

- source-of-truth models
- custom business logic
- custom pages/components
- tests

### deterministic

Do not hand-edit these artifacts.

They are generated and owned by SwallowKit. Change the appropriate source of
truth or configuration, then use SwallowKit plan/apply to regenerate them.

Managed artifacts are tracked by SwallowKit metadata such as
`.swallowkit/artifacts.json`.

### shared

Edit only outside SwallowKit-managed markers.

Always inspect the current boundary contract instead of relying solely on the
examples in this document.

## Deterministic Changes: Plan → Apply → Verify

For autonomous or agent-driven generation, prefer the SwallowKit two-phase
workflow.

```text
inspect
   ↓
plan
   ↓
evaluate conflicts / approval requirements
   ↓
apply
   ↓
verify
```

Example:

```bash
{{runCmd}} swallowkit machine plan scaffold <model>
{{runCmd}} swallowkit machine apply scaffold --plan <planId>
{{runCmd}} swallowkit machine verify project
```

Do not bypass plan/apply by manually editing deterministic artifacts.

If a plan reports conflicts, determine whether existing hand-written behavior
must be moved to an ai-authored location or whether overwrite approval is
required.

Never invent or implicitly grant human approval.

## Model Changes

For an existing model change, the normal pattern is:

```text
edit source-of-truth model
        ↓
inspect drift
        ↓
plan scaffold
        ↓
resolve conflicts / approvals if any
        ↓
apply
        ↓
verify
```

Use the `swallowkit-modify-model` Agent Skill when available.

Otherwise read and follow the equivalent runbook under
`.swallowkit/workflows/`.

Never repair schema drift by directly patching SwallowKit-managed artifacts.

Additional model-change facts:

- The shared package is consumed through its built `dist/`. `verify project`
  rebuilds it automatically before typecheck; when typechecking manually,
  build the shared package first (stale `dist/` shows up as
  "no exported member" errors).
- Seed JSON under `dev-seeds/` is only applied by
  `{{runCmd}} swallowkit dev --seed-env <environment>`; editing the files
  alone does nothing.

## New Models / CRUD Features

Use the `swallowkit-add-model` Agent Skill when available.

Otherwise follow the equivalent runbook under `.swallowkit/workflows/`.

The agent may author domain-specific schema fields and custom behavior, but
SwallowKit should generate framework-owned CRUD artifacts.

Do not manually recreate boilerplate that SwallowKit owns.

## Authentication

Authentication is a **plan/apply operation**, not a free-form config edit.
Ownership of `swallowkit.config` is split:

- `auth.schemes` — owned by SwallowKit. **Always start with
  `{{runCmd}} swallowkit machine plan auth --provider <p> [--scheme <name>]`.
  Never hand-write `auth.schemes` entries**; apply auth appends them, and a
  hand-written scheme makes the plan fail with "already exists".
- `auth.authorization.policies` and `swa.allowedProviders` — hand-edited
  **after** apply (the config is an extension point; this edit is expected).
  `swa.allowedProviders` can also be set at plan time with
  `--allowed-providers github,aad`.

After `apply auth`, follow the returned `nextActions`:

1. Define `auth.authorization.policies` referencing the new scheme.
2. For `swa`: confirm `swa.allowedProviders`; generated login URLs use it.
3. For `external-token`: implement the generated verifier stub. It fails
   closed, and **verify passes with the stub in place** — a green verify does
   not mean external-token auth works end-to-end (`verify project` surfaces a
   `auth-verifier-stub` warning while the stub is unmodified).
4. Re-run plan/apply scaffold for models that need auth guards, then verify.

Use the `swallowkit-add-auth` Agent Skill or the
`.swallowkit/workflows/add-auth.md` runbook when available.

### Generated CRUD scope

Generated CRUD endpoints enforce the model's `authPolicy`
(authentication + roles) — **they do NOT scope data to the authenticated
user**. Any caller passing the policy can read or write any document. For
multi-user data where users may only touch their own records, add ai-authored
custom endpoints that derive the scoping key (e.g. `learnerId`) from the
verified principal — never from the request body — and restrict the generated
write endpoints to admin roles.

## Verification Is a Completion Gate

Before treating an agent-driven implementation as complete, run SwallowKit
verification:

```bash
{{runCmd}} swallowkit machine verify project
```

or the equivalent MCP operation.

Verification covers SwallowKit structural correctness, drift, type correctness,
and configured project checks.

When verification fails, use the structured failure explanation:

```bash
{{runCmd}} swallowkit machine explain failure
```

or its MCP equivalent, then repair the appropriate source and verify again.

Use the `swallowkit-verify-repair` Agent Skill or runbook when applicable.

SwallowKit verification answers:

> Is the SwallowKit project mechanically and structurally valid?

A semantic code review answers different questions:

> Is this implementation well designed?
> Does it satisfy the specification and user intent?

Therefore, perform SwallowKit verification before treating semantic code review
as the final quality gate.

## Human Approval Gates

A machine operation may return terminal states such as:

- `complete`
- `in-progress`
- `blocked`
- `requires-human`
- `failed`

Follow `nextActions`.

When the status is `requires-human`, stop and request the required human
decision.

Do not reinterpret `requires-human` as an error to work around.

Azure provisioning is a human-approved operation.

Use the `swallowkit-provision` Agent Skill or runbook and never bypass its
approval gate. A broad request to deploy does not itself grant the explicit
approval required by that workflow.

## SwallowKit Agent Skills and Runbooks

SwallowKit installs task-specific Agent Skills under:

```text
.github/skills/
```

Current workflows include:

- `swallowkit-add-model`
- `swallowkit-modify-model`
- `swallowkit-add-auth`
- `swallowkit-verify-repair`
- `swallowkit-provision`

Equivalent agent-agnostic runbooks are available under:

```text
.swallowkit/workflows/
```

If the runtime supports Agent Skills, use the relevant Skill when the task
matches. If it does not, read the corresponding runbook.

These task-specific instructions supplement this `AGENTS.md`; they do not
replace the always-on project contract.

## Architecture

This is a full-stack application deployed on Azure with a TypeScript
frontend/BFF and an Azure Functions backend in {{backendLanguageLabel}}.

```text
Frontend (React / Next.js App Router)
  ↓
BFF (Next.js API Routes)
  ↓
Azure Functions
  ↓
Azure Cosmos DB
```

### Core architecture rules

1. Next.js API routes are a BFF/proxy layer. Do not place application business
   logic or direct database access there.
2. Zod schemas under `shared/models/` are the application model source of truth.
3. Do not duplicate model definitions across layers.
4. Azure Functions own backend business logic and data access.
5. SwallowKit-generated artifacts must be changed through their source of truth
   and deterministic generation workflow, not by hand.
6. Infrastructure is managed as code with Bicep. Respect SwallowKit ownership
   markers and boundaries.
7. Production access to Azure resources must follow the generated security
   architecture; do not introduce hard-coded credentials or connection strings.

### Backend-specific rules

{{backendRules}}

The backend owns `id`, `createdAt`, and `updatedAt`; never trust client-sent
values for these fields.

## Project Structure

```text
{{projectName}}/
├── app/                    # Next.js App Router
│   ├── api/                # BFF routes
│   └── {model}/            # generated/custom UI
├── functions/              # Azure Functions backend
{{functionsStructureLine}}
├── shared/
│   ├── models/             # Zod source-of-truth models
│   └── index.ts
├── lib/
│   └── api/
├── components/
├── infra/                  # Bicep infrastructure
├── .swallowkit/            # SwallowKit project metadata and runbooks
├── .github/skills/         # SwallowKit Agent Skills
├── .mcp.json               # project-scoped SwallowKit MCP bootstrap
└── AGENTS.md
```

Inspect the current project rather than assuming every project has exactly the
same generated structure.

## Naming and Model Conventions

- Model schema files use `shared/models/{kebab-case}.ts`.
- The Zod schema constant and inferred TypeScript type use the same PascalCase
  name: `export const Todo = z.object(...); export type Todo = z.infer<typeof Todo>`.
- Re-export models from `shared/index.ts`.
- `id` is a required `z.string()`; only `createdAt` / `updatedAt` are optional
  backend-managed fields.
- Models may declare `partitionKey`, `authPolicy`, `displayName`, and
  `connectorConfig` as exported constants. Exact formats:
  `{{runCmd}} swallowkit machine inspect capabilities` (modelDeclarations).
- Cosmos DB containers use PascalCase plural names and default to `/id` as the
  partition key unless the model declares another key, e.g.
  `export const partitionKey = '/learnerId';` (the field must exist in the
  schema).

## Everyday Commands

```bash
{{pm}} install
{{runCmd}} swallowkit dev
{{pm}} run build
{{pm}} run lint
{{runCmd}} swallowkit machine verify project
```

Always invoke SwallowKit using the package-runner convention generated for this
project. Do not arbitrarily mix package-manager invocation styles.

## Final Rules

Do not:

- rely on remembered SwallowKit capabilities when current inspection can answer
  the question
- hand-edit deterministic SwallowKit-managed artifacts
- bypass plan/apply safety checks
- bypass human approval gates
- duplicate model definitions across generated layers
- move backend business logic into the BFF
- decompose one end-to-end SwallowKit-generated feature into artificial
  horizontal tickets solely because multiple generated layers exist
- consider an implementation complete before SwallowKit verification succeeds

Do:

- inspect before making SwallowKit-dependent design assumptions
- preserve external development-process workflows
- use SwallowKit as the deterministic execution and verification layer
- keep specifications focused on intent and observable behavior
- prefer vertical, independently verifiable slices
- verify before final semantic review

Use `{{pm}}`, the package manager selected for this project. Do not introduce another package manager or lockfile. Use `{{runCmd}} swallowkit` for the project-local CLI. The MCP launcher intentionally resolves `latest` independently.

日本語対訳

# AGENTS.md

このプロジェクトは **SwallowKit** によって生成されました。

SwallowKit は、このプロジェクトのアーキテクチャおよび開発ワークフローの一部です。
コード生成時だけでなく、discovery、requirements clarification、specification、planning、
ticket decomposition、implementation、verification、review の間、常に適用される制約として
扱わなければなりません。

<!-- source-section: How SwallowKit Fits Into the Development Process -->
## SwallowKit と開発プロセスの関係

SwallowKit はソフトウェア開発プロセス全体を所有**しません**。

ユーザー、別の Agent Skill、または framework が requirements discovery、specification、
planning、ticketing、TDD、implementation、review のプロセスを定義している場合は、
そのプロセスに引き続き従ってください。

以下については、SwallowKit を authoritative な project-specific layer として使用してください。

- 現在のプロジェクトの検査
- entity、route、infrastructure、responsibility boundary の理解
- 直接編集できる artifact の判定
- plan/apply による deterministic generation
- drift の検出
- 生成後のプロジェクトの検証
- sensitive operation に対する human approval gate の強制

外部の development-process Skill と SwallowKit は合成して使用することを意図しています。

process Skill は**どのように進めるか**を決定します。
SwallowKit は**この SwallowKit project をどのように安全かつ再現可能に変更できるか**を決定します。

<!-- source-section: Do Not Assume SwallowKit Capabilities From Memory -->
## 記憶から SwallowKit capability を推測してはならない

SwallowKit は時間とともに進化します。

SwallowKit が生成できるもの・できないものについて、モデルが保持する知識や仮定に
依存してはなりません。

SwallowKit capability、project structure、ownership boundary が設計判断に影響する場合、
判断前に現在のプロジェクトと現在利用可能な SwallowKit interface を検査してください。

利用可能な場合は `swallowkit_*` MCP tools を優先してください。

MCP を利用できない場合は machine interface を使用します。

```bash
{{runCmd}} swallowkit machine ...
```

machine interface は Agent-facing fallback であり、自律 workflow に適した構造化済みの
`status` / `nextActions` を返します。

<!-- source-section: Inspect Before Asking or Designing -->
## 質問または設計の前に検査する

タスクが SwallowKit-managed application structure に影響する可能性がある場合、
人間に質問したり実装設計を確定したりする前にプロジェクトを検査してください。

タスクに関係する inspection だけを使用してください。典型的な inspection は次のとおりです。

```bash
{{runCmd}} swallowkit machine inspect project
{{runCmd}} swallowkit machine inspect entities
{{runCmd}} swallowkit machine inspect routes
{{runCmd}} swallowkit machine inspect boundaries
{{runCmd}} swallowkit machine inspect drift
{{runCmd}} swallowkit machine inspect infra
{{runCmd}} swallowkit machine inspect capabilities
```

`inspect capabilities` は「SwallowKit に何ができるか」(サポートされる model 宣言と
正確な書式、認証導入の正しい workflow、generated CRUD が保証すること・しないこと、
seed の適用方法) に答えます。推測したり SwallowKit 内部を grep したりする代わりに
これを使用してください。

利用可能な場合は同等の `swallowkit_*` MCP tools を使用してください。

repository または SwallowKit inspection から回答できる質問は、人間に委ねず Agent が
回答しなければなりません。

例:

- SwallowKit が generated CRUD layer を定義・生成している場合、その wiring 方法を質問しない。
- responsibility boundary を確認する前に generated file の編集を提案しない。
- current SwallowKit project と available operation を検査する前に、infrastructure capability が
  利用できないと仮定しない。

<!-- source-section: Specification and Planning Guidance -->
## Specification と planning のガイダンス

specification を作成または改善する場合:

- user-visible behavior と domain intent を記述する
- acceptance criteria と重要な test seam を定義する
- SwallowKit architecture と responsibility boundary を implementation constraint として扱う
- generated artifact を手動実装 component として早計に記述しない
- SwallowKit が source of truth から決定論的に導出できる作業を重複させない

例えば、model field の追加により SwallowKit が backend、BFF、UI、infrastructure artifact を
再生成する場合、specification は主に期待する end-to-end behavior と SwallowKit constraint を
記述すべきです。

各 generated layer が独立した manual implementation decision であると示唆すべきではありません。

SwallowKit が望む behavior をサポートするかどうかが specification に影響する場合、
spec を確定する前に current capability を検査してください。

<!-- source-section: Ticket Decomposition Guidance -->
## Ticket decomposition のガイダンス

独立して検証可能な user/system behavior の **vertical slice** を優先してください。

artifact が別 layer に存在するという理由だけで、作業を次のような horizontal ticket に
分割してはなりません。

- schema ticket
- backend ticket
- BFF ticket
- UI ticket
- infrastructure ticket

SwallowKit がそれらの layer を決定論的に生成し、1つの end-to-end behavior を表す場合は、
同じ vertical slice 内に保持してください。

例:

```text
Todo に priority support を追加
  ├─ source-of-truth model を更新
  ├─ SwallowKit plan/apply で managed artifact を再整合
  ├─ 必要な ai-authored business logic を追加
  ├─ test を追加/更新
  └─ project を verify
```

ticket boundary は SwallowKit の generated file structure ではなく、独立して価値があり検証可能な
behavior を反映すべきです。

<!-- source-section: Responsibility Boundary -->
## Responsibility boundary

file-level implementation decision の前に、current machine-readable boundary contract を
検査してください。

```bash
{{runCmd}} swallowkit machine inspect boundaries
```

その時点の結果を authoritative として扱ってください。

一般的な ownership model は次のとおりです。

### ai-authored

Agent はこれらを直接編集できます。

典型例:

- source-of-truth model
- custom business logic
- custom page/component
- test

### deterministic

これらの artifact を手編集してはなりません。

SwallowKit が生成・所有します。適切な source of truth または configuration を変更してから、
SwallowKit plan/apply で再生成してください。

managed artifact は `.swallowkit/artifacts.json` などの SwallowKit metadata で追跡されます。

### shared

SwallowKit-managed marker の外側だけを編集してください。

この文書の例だけに依存せず、常に current boundary contract を検査してください。

<!-- source-section: Deterministic Changes: Plan → Apply → Verify -->
## Deterministic change: Plan → Apply → Verify

自律または Agent-driven generation では SwallowKit の two-phase workflow を優先してください。

```text
inspect
   ↓
plan
   ↓
conflict / approval requirement を評価
   ↓
apply
   ↓
verify
```

例:

```bash
{{runCmd}} swallowkit machine plan scaffold <model>
{{runCmd}} swallowkit machine apply scaffold --plan <planId>
{{runCmd}} swallowkit machine verify project
```

deterministic artifact を手編集して plan/apply を迂回してはなりません。

plan が conflict を報告した場合は、既存の hand-written behavior を ai-authored location に
移す必要があるか、overwrite approval が必要かを判断してください。

human approval を捏造したり暗黙に付与したりしてはなりません。

<!-- source-section: Model Changes -->
## Model change

既存 model の変更は通常、次の pattern です。

```text
source-of-truth model を編集
        ↓
drift を inspect
        ↓
scaffold を plan
        ↓
conflict / approval を必要に応じて解決
        ↓
apply
        ↓
verify
```

利用可能なら `swallowkit-modify-model` Agent Skill を使用してください。

それ以外では `.swallowkit/workflows/` にある同等の runbook を読み、従ってください。

SwallowKit-managed artifact を直接 patch して schema drift を修復してはなりません。

model 変更に関する追加事項:

- shared package はビルド済み `dist/` 経由で参照されます。`verify project` は typecheck の前に
  自動で rebuild しますが、手動で typecheck する場合は先に shared package をビルドしてください
  (古い `dist/` は "no exported member" エラーとして現れます)。
- `dev-seeds/` の seed JSON は
  `{{runCmd}} swallowkit dev --seed-env <environment>` の実行時のみ適用されます。
  ファイルを編集するだけでは何も起きません。

<!-- source-section: New Models / CRUD Features -->
## 新しい model / CRUD feature

利用可能なら `swallowkit-add-model` Agent Skill を使用してください。

それ以外では `.swallowkit/workflows/` の同等の runbook に従ってください。

Agent は domain-specific schema field と custom behavior を記述できますが、framework-owned
CRUD artifact は SwallowKit が生成すべきです。

SwallowKit が所有する boilerplate を手作業で再作成してはなりません。

<!-- source-section: Authentication -->
## Authentication

認証の導入は **plan/apply operation** であり、自由な config 編集ではありません。
`swallowkit.config` の所有権は分割されています。

- `auth.schemes` — SwallowKit が所有します。**必ず
  `{{runCmd}} swallowkit machine plan auth --provider <p> [--scheme <name>]` から始めてください。
  `auth.schemes` を手書きしてはなりません**。apply auth が追記します。手書きされた scheme は
  plan を "already exists" で失敗させます。
- `auth.authorization.policies` と `swa.allowedProviders` — apply **後に**手で追記します
  (config は extension point であり、この編集は想定内の workflow です)。
  `swa.allowedProviders` は plan 時に `--allowed-providers github,aad` でも指定できます。

`apply auth` の後は、返される `nextActions` に従ってください。

1. 新しい scheme を参照する `auth.authorization.policies` を定義する。
2. `swa` の場合: `swa.allowedProviders` を確認する。generated login URL はこれを使用します。
3. `external-token` の場合: generated verifier stub を実装する。stub は fail closed であり、
   **stub のままでも verify は成功します** — verify が green でも external-token 認証が
   end-to-end で動くことを意味しません (`verify project` は stub が未修正の間
   `auth-verifier-stub` warning を表示します)。
4. auth guard が必要な model の plan/apply scaffold を再実行し、verify する。

利用可能なら `swallowkit-add-auth` Agent Skill または
`.swallowkit/workflows/add-auth.md` runbook を使用してください。

### Generated CRUD の守備範囲

Generated CRUD endpoint は model の `authPolicy` (認証 + role) を強制しますが、
**認証済み user へのデータのスコープはしません**。policy を通過した caller は
任意の document を読み書きできます。user が自分のレコードのみ操作できるべき
multi-user データでは、検証済み principal から scoping key (例: `learnerId`) を導出する
ai-authored custom endpoint を追加し (request body からは決して導出しない)、
generated write endpoint は admin role に制限してください。

<!-- source-section: Verification Is a Completion Gate -->
## Verification は completion gate

Agent-driven implementation を完了とみなす前に SwallowKit verification を実行してください。

```bash
{{runCmd}} swallowkit machine verify project
```

または同等の MCP operation を使用します。

verification は SwallowKit structural correctness、drift、type correctness、configured project
check を対象とします。

verification が失敗した場合は structured failure explanation を使用します。

```bash
{{runCmd}} swallowkit machine explain failure
```

または MCP equivalent を使用し、適切な source を修復して再び verify します。

該当する場合は `swallowkit-verify-repair` Agent Skill または runbook を使用してください。

SwallowKit verification が答える問い:

> SwallowKit project は mechanically/structurally valid か？

semantic code review が答える別の問い:

> この implementation は適切に設計されているか？
> specification と user intent を満たすか？

したがって、semantic code review を最後の quality gate として扱う前に SwallowKit verification を
実施してください。

<!-- source-section: Human Approval Gates -->
## Human approval gate

machine operation は次のような terminal state を返す場合があります。

- `complete`
- `in-progress`
- `blocked`
- `requires-human`
- `failed`

`nextActions` に従ってください。

status が `requires-human` の場合は停止し、必要な human decision を要求してください。

`requires-human` を回避すべき error と解釈してはなりません。

Azure provisioning は human-approved operation です。

`swallowkit-provision` Agent Skill または runbook を使用し、その approval gate を決して迂回しては
なりません。広い deployment request 自体は、その workflow が要求する明示的 approval を
付与しません。

<!-- source-section: SwallowKit Agent Skills and Runbooks -->
## SwallowKit Agent Skills と runbook

SwallowKit は task-specific Agent Skills を次の場所にインストールします。

```text
.github/skills/
```

現在の workflow:

- `swallowkit-add-model`
- `swallowkit-modify-model`
- `swallowkit-add-auth`
- `swallowkit-verify-repair`
- `swallowkit-provision`

同等の agent-agnostic runbook は次の場所にあります。

```text
.swallowkit/workflows/
```

runtime が Agent Skills をサポートする場合、タスクに合う Skill を使用してください。
それ以外では対応する runbook を読んでください。

これらの task-specific instruction は `AGENTS.md` を補足します。always-on project contract を
置き換えるものではありません。

<!-- source-section: Architecture -->
## Architecture

これは TypeScript frontend/BFF と {{backendLanguageLabel}} の Azure Functions backend を持ち、
Azure に deploy される full-stack application です。

```text
Frontend (React / Next.js App Router)
  ↓
BFF (Next.js API Routes)
  ↓
Azure Functions
  ↓
Azure Cosmos DB
```

### Core architecture rules

1. Next.js API route は BFF/proxy layer です。application business logic や direct database
   access を置いてはなりません。
2. `shared/models/` の Zod schema が application model の source of truth です。
3. model definition を layer 間で重複させてはなりません。
4. Azure Functions が backend business logic と data access を所有します。
5. SwallowKit-generated artifact は手編集せず、source of truth と deterministic generation
   workflow から変更しなければなりません。
6. infrastructure は Bicep による code として管理されます。SwallowKit ownership marker と
   boundary を尊重してください。
7. production の Azure resource access は generated security architecture に従わなければ
   なりません。hard-coded credential または connection string を導入してはなりません。

### Backend-specific rules

{{backendRules}}

backend が `id`、`createdAt`、`updatedAt` を所有します。client-sent value を決して信頼しては
なりません。

<!-- source-section: Project Structure -->
## Project structure

```text
{{projectName}}/
├── app/                    # Next.js App Router
│   ├── api/                # BFF routes
│   └── {model}/            # generated/custom UI
├── functions/              # Azure Functions backend
{{functionsStructureLine}}
├── shared/
│   ├── models/             # Zod source-of-truth models
│   └── index.ts
├── lib/
│   └── api/
├── components/
├── infra/                  # Bicep infrastructure
├── .swallowkit/            # SwallowKit project metadata and runbooks
├── .github/skills/         # SwallowKit Agent Skills
├── .mcp.json               # project-scoped SwallowKit MCP bootstrap
└── AGENTS.md
```

すべての project がまったく同じ generated structure を持つと仮定せず、current project を
検査してください。

<!-- source-section: Naming and Model Conventions -->
## Naming と model convention

- Model schema file は `shared/models/{kebab-case}.ts` を使用します。
- Zod schema constant と inferred TypeScript type は同じ PascalCase name を使用します:
  `export const Todo = z.object(...); export type Todo = z.infer<typeof Todo>`。
- model を `shared/index.ts` から re-export します。
- `id` は必須の `z.string()` です。optional な backend-managed field は
  `createdAt` / `updatedAt` のみです。
- model は `partitionKey`、`authPolicy`、`displayName`、`connectorConfig` を exported constant
  として宣言できます。正確な書式:
  `{{runCmd}} swallowkit machine inspect capabilities` (modelDeclarations)。
- Cosmos DB container は PascalCase plural name を使用し、model が別の key を宣言しない限り
  partition key の default は `/id` です。宣言例:
  `export const partitionKey = '/learnerId';` (field は schema に存在する必要があります)。

<!-- source-section: Everyday Commands -->
## 日常的な command

```bash
{{pm}} install
{{runCmd}} swallowkit dev
{{pm}} run build
{{pm}} run lint
{{runCmd}} swallowkit machine verify project
```

この project 向けに生成された package-runner convention で SwallowKit を呼び出してください。
package-manager invocation style を勝手に混在させてはなりません。

<!-- source-section: Final Rules -->
## 最終ルール

してはならないこと:

- current inspection で回答できる場合に、記憶上の SwallowKit capability に依存する
- deterministic SwallowKit-managed artifact を手編集する
- plan/apply safety check を迂回する
- human approval gate を迂回する
- generated layer 間で model definition を重複させる
- backend business logic を BFF に移す
- 複数の generated layer があるという理由だけで、1つの end-to-end SwallowKit-generated
  feature を人為的な horizontal ticket に分解する
- SwallowKit verification が成功する前に implementation を完了とみなす

行うこと:

- SwallowKit-dependent な設計仮定の前に inspect する
- 外部 development-process workflow を維持する
- SwallowKit を deterministic execution/verification layer として使用する
- specification を intent と observable behavior 中心に保つ
- vertical で独立して検証可能な slice を優先する
- final semantic review の前に verify する

生成される CLAUDE.md

English original

# CLAUDE.md

This is a **SwallowKit** project.

Before discovery, requirements clarification, specification, planning, ticket
decomposition, implementation, verification, or review, read and follow the
root `AGENTS.md`.

SwallowKit must be considered before implementation, not only when generating
code.

Always-on rules:

- Inspect the current project and SwallowKit capabilities before making
  SwallowKit-dependent assumptions or asking questions the repository can answer.
- Prefer `swallowkit_*` MCP tools.
- Fall back to `{{runCmd}} swallowkit machine ...` when MCP is unavailable.
- Inspect responsibility boundaries before editing framework-related files.
- Never hand-edit deterministic SwallowKit-managed artifacts.
- Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
  in swallowkit.config (policies and `swa.allowedProviders` are hand-edited
  after apply).
- Use plan/apply for deterministic generation.
- Respect all `requires-human` states and provisioning approval gates.
- Run SwallowKit verification before considering implementation complete.

Task-specific SwallowKit Agent Skills are available under `.github/skills/`.
Equivalent agent-agnostic runbooks are available under
`.swallowkit/workflows/`.

The root `AGENTS.md` is the canonical project contract.

日本語対訳

# CLAUDE.md

これは **SwallowKit** project です。

discovery、requirements clarification、specification、planning、ticket decomposition、
implementation、verification、review の前に、root `AGENTS.md` を読み、従ってください。

SwallowKit は code generation 時だけでなく、implementation より前から考慮しなければなりません。

always-on rule:

- SwallowKit-dependent な仮定を行ったり repository で回答可能な質問をしたりする前に、
  current project と SwallowKit capability を検査する。
- `swallowkit_*` MCP tools を優先する。
- MCP が利用できない場合は `{{runCmd}} swallowkit machine ...` にフォールバックする。
- framework-related file を編集する前に responsibility boundary を検査する。
- deterministic SwallowKit-managed artifact を決して手編集しない。
- auth scheme の追加は plan/apply auth 経由のみ。swallowkit.config の `auth.schemes` を
  手書きしない (policies と `swa.allowedProviders` は apply 後に手で追記する)。
- deterministic generation には plan/apply を使用する。
- すべての `requires-human` state と provisioning approval gate を尊重する。
- implementation を完了とみなす前に SwallowKit verification を実行する。

task-specific SwallowKit Agent Skills は `.github/skills/` にあります。
同等の agent-agnostic runbook は `.swallowkit/workflows/` にあります。

root `AGENTS.md` が canonical project contract です。

生成される .github/copilot-instructions.md

English original

# Copilot Instructions

This is a **SwallowKit** project.

Read and follow the root `AGENTS.md` as the canonical project contract.

SwallowKit applies during discovery, requirements clarification, specification,
planning, ticket decomposition, implementation, verification, and review — not
only during code generation.

Key rules:

- Inspect current SwallowKit capabilities instead of assuming them.
- Answer repository- and SwallowKit-inspectable questions before asking the human.
- Prefer `swallowkit_*` MCP tools when available.
- Otherwise use `{{runCmd}} swallowkit machine ...`.
- Inspect responsibility boundaries before editing framework-related files.
- Never hand-edit deterministic SwallowKit-managed artifacts.
- Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
  in swallowkit.config (policies and `swa.allowedProviders` are hand-edited
  after apply).
- Use plan/apply for deterministic generation.
- Respect `requires-human` states and other human approval gates.
- Run SwallowKit verification before completion.

Task-specific SwallowKit Agent Skills live under `.github/skills/`.
Agent-agnostic equivalents live under `.swallowkit/workflows/`.

日本語対訳

# Copilot Instructions

これは **SwallowKit** project です。

root `AGENTS.md` を canonical project contract として読み、従ってください。

SwallowKit は code generation 時だけでなく、discovery、requirements clarification、
specification、planning、ticket decomposition、implementation、verification、review で
適用されます。

重要なルール:

- current SwallowKit capability を仮定せず検査する。
- 人間に質問する前に repository/SwallowKit で確認可能な質問へ回答する。
- 利用可能な場合は `swallowkit_*` MCP tools を優先する。
- それ以外では `{{runCmd}} swallowkit machine ...` を使用する。
- framework-related file を編集する前に responsibility boundary を検査する。
- deterministic SwallowKit-managed artifact を決して手編集しない。
- auth scheme の追加は plan/apply auth 経由のみ。swallowkit.config の `auth.schemes` を
  手書きしない (policies と `swa.allowedProviders` は apply 後に手で追記する)。
- deterministic generation には plan/apply を使用する。
- `requires-human` state とその他の human approval gate を尊重する。
- 完了前に SwallowKit verification を実行する。

task-specific SwallowKit Agent Skills は `.github/skills/` にあります。
Agent-agnostic equivalent は `.swallowkit/workflows/` にあります。

コーディングエージェントガイド ​

目的 ​

生成される Agent integration files ​

開発ライフサイクル全体での SwallowKit ​

Discovery と requirements clarification ​

Specification ​

Planning ​

Ticket decomposition ​

Implementation ​

Verification ​

Review ​

質問・設計の前に inspect する ​

Responsibility boundary ​

Planning と ticketing ​

Implementation workflow ​

エージェントへの依頼例 ​

ドリフトが見つかったとき ​

Verification と semantic review の違い ​

Human approval ​

外部 development process との composition ​

例: Matt Pocock Skills ​

完全な生成 Agent documents ​

生成される AGENTS.md ​

English original ​

日本語対訳 ​

生成される CLAUDE.md ​

English original ​

日本語対訳 ​

生成される .github/copilot-instructions.md ​

English original ​

日本語対訳 ​

コーディングエージェントガイド

目的

生成される Agent integration files

開発ライフサイクル全体での SwallowKit

Discovery と requirements clarification

Specification

Planning

Ticket decomposition

Implementation

Verification

Review

質問・設計の前に inspect する

Responsibility boundary

Planning と ticketing

Implementation workflow

エージェントへの依頼例

ドリフトが見つかったとき

Verification と semantic review の違い

Human approval

外部 development process との composition

例: Matt Pocock Skills

完全な生成 Agent documents

生成される AGENTS.md

English original

日本語対訳

生成される CLAUDE.md

English original

日本語対訳

生成される .github/copilot-instructions.md

English original

日本語対訳