> ## Documentation Index
> Fetch the complete documentation index at: https://arkor-92aeef0e-eng-615.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# プロジェクト構成

> Arkor がコードを置く場所、そして .arkor/ と ~/.arkor/ に何が入っているか。

生成された Arkor プロジェクトはこんな形をしています:

```
my-arkor-app/
├── src/arkor/
│   ├── index.ts        # createArkor({ trainer })
│   └── trainer.ts      # createTrainer({ ... })
├── arkor.config.ts
├── AGENTS.md           # AI コーディングエージェント向けの指示（create-arkor / arkor init の --no-agents-md で無効化）
├── CLAUDE.md           # 生成時のデフォルト内容: @AGENTS.md の 1 行再エクスポート
├── .arkor/             # プロジェクトごとの状態（gitignore 済み）
└── package.json        # dev / build / start
```

AI エージェント向け指示の正本は `AGENTS.md` です。`CLAUDE.md` を別に置いているのは、Claude Code がプロジェクトルートの `CLAUDE.md` を自動的に読み込む仕様で、かつ `@<path>` というディレクティブで他ファイルを取り込めるためです。**scaffolder が `CLAUDE.md` を新規生成する場合の**デフォルト内容は `@AGENTS.md` の 1 行のみで、Claude Code が AGENTS.md の中身を自動的に context に展開してくれるため、2 ファイルを二重管理せずに済みます。プロジェクト固有の `CLAUDE.md` が既に存在する場合、scaffolder はそれを上書きせず、既存の内容が引き続き有効です。

ソース以外に重要なのは 2 層の状態です: `.arkor/`（プロジェクトごと、リポジトリ内）と `~/.arkor/`（ユーザーごと、ホームディレクトリー）。

## `src/arkor/`

Arkor は `src/arkor/index.ts` を見てプロジェクトを認識します。このファイルから `createArkor()` の結果をエクスポートしてください。CLI は次の 3 つのエクスポート形を優先順位順に受け付けます:

1. **`export const arkor = createArkor({ trainer })`**（推奨。テンプレートが生成する形）。
2. **`export const trainer = createTrainer({ ... })`**（パワーユーザー向けショートカット。ラッパーが不要な場合）。
3. **デフォルトエクスポート**（`Arkor` マニフェスト or `Trainer` のいずれか）。

```ts theme={null}
// src/arkor/index.ts（推奨形）
import { createArkor } from "arkor";
import { trainer } from "./trainer";

export const arkor = createArkor({ trainer });
```

トレーナー本体は慣例で兄弟ファイルに置き、`index.ts` を薄く保ちます:

```ts theme={null}
// src/arkor/trainer.ts
import { createTrainer } from "arkor";

export const trainer = createTrainer({
  name: "support-bot-v1",
  model: "unsloth/gemma-4-E4B-it",
  dataset: { type: "huggingface", name: "arkorlab/triage-demo" },
  lora: { r: 16, alpha: 16 },
  maxSteps: 100,
});
```

トレーナーをさらに分割しても構いません（ヘルパー、プロンプトビルダーなど）。正規パスにあるべきなのは `index.ts` だけです。

将来的に複数トレーナーを登録する場合は、ファイルを増やして `createArkor` に渡すことになります。今のところ API は単一の `trainer` だけを受け付けます。`deploy` と `eval` のスロットは型上で予約されていますが未実装です。

## `arkor.config.ts`

プロジェクト生成ツールはデフォルトで次の `arkor.config.ts` を生成します:

```ts theme={null}
// arkor.config.ts
export default {};
```

現状はプレイスホルダーです。ランタイムはまだここからフィールドを読み取りません。学習のデフォルト値（`maxSteps`、`learningRate`、`lora` など）はすべて `Trainer` 自体に持たせるので、プロジェクトレベルではなくトレーナーごとにコントロールできます。削除する理由がない限り、ファイルはそのままにしておいてください。

## `.arkor/`（プロジェクトごと、gitignore 済み）

このディレクトリーはコミットしないでください。

* **`.arkor/state.json`**。プロジェクトのルーティング: `orgSlug`、`projectSlug`、`projectId`。これによってランタイムはローカルリポジトリをマネージドバックエンドのワークスペースにマップします。ファイルは `ensureProjectState()` が作成し、CLI や Studio がスコープを必要とする最初のアクション（学習の開始、ベースモデル推論、Studio の [Endpoints](/ja/studio/endpoints) ページからの初回 deployment 作成など）で走ります。純粋な read 経路（Endpoints / Jobs の一覧表示など）は意図的に初期化を起こさないので、新規チェックアウト直後に Studio を開いてもリモートにプロジェクトを副作用で作ったりせず、空一覧が表示されるだけです。**匿名**ワークスペースではこの初回 write 呼び出しで自動作成されます。**OAuth** ワークスペースの場合はランタイムがエラーを返します。今のところ `arkor login` も `arkor init` もこのファイルに値を書き込まないので、`{ orgSlug, projectSlug, projectId }` を手動で書いて作るのが現実的な方法です。一度作られた後は手で編集しないでください。

  `arkor logout` 後の注意点: logout は `credentials.json` だけを削除するため、前の匿名 ID が残した `.arkor/state.json` はそのまま残ります。次の匿名セッションは新しい組織になり、read 経路ではこの古いファイルを**無視**します（一覧は空のまま、Studio も開けます）が、上記の write 経路は（手動管理された OAuth スコープの可能性があるため）それを再利用も上書きもせず、409／エラーで「`.arkor/state.json` を削除して新しい匿名プロジェクトを開始するか、そのプロジェクトを所有するアカウントで `arkor login` してください」と案内して失敗します。
* **`.arkor/build/index.mjs`**。`arkor build` の出力。`src/arkor/index.ts` を Node 22.22 ターゲットで esbuild した単一バンドルで、bare specifier は外部のままにしてあります。`arkor start` がこれを実行します。

## `~/.arkor/`（ユーザーごと）

ホームディレクトリーにあり、そのユーザーのすべての Arkor プロジェクト間で共有されます。

* **`~/.arkor/credentials.json`**。認証状態。`arkor login --oauth` または対話的な `arkor login` のピッカーで `OAuth (browser)` を選んだ場合に書かれる Arkor Cloud OAuth トークンか、未ログインで初使用時に作られる匿名トークンのいずれか。ファイルは `mode` フィールドが `"oauth"` か `"anon"` でタグ付けされており、CLI はどのモードにいるかを把握します。`arkor login` はこのファイルだけを書きます。`.arkor/state.json` は **作成しません**。
* **`~/.arkor/studio-token`**（一時的）。`arkor dev` が起動ごとに書く CSRF トークン（モード `0600`）。Studio が CLI のローカルサーバーへの呼び出しを認可するのに使います。`arkor dev` 起動のたびにローテートされます。

`arkor logout` は確認後（または `--force` 指定時）に `credentials.json` を削除します。匿名認証情報が入っている場合、そのファイルを削除すると、バックアップしていない限り同じ匿名 ID には戻れません。プロジェクトローカルの `.arkor/state.json` には**触れません**。そのまま新しい匿名セッションを始めると、残ったファイルが write 経路をブロックするので、削除するかサインインが必要です（上の `.arkor/state.json` の注記を参照）。Studio トークンはプロセス終了時にベストエフォートで削除され（`arkor dev` がクラッシュすると残る場合あり）、次回起動時にローテートされます。

## CLI が探すもの

* `arkor dev` は Studio の Web サーバーを `127.0.0.1:4000` で起動し、`~/.arkor/studio-token` を書きます。`src/arkor/` をファイル監視はしません。Studio の `/api/manifest` エンドポイントは確かに `runBuild` を呼び、bundle の content-addressed コピー経由で再 import します（無編集の再読込は Node のモジュールキャッシュを再利用し、編集はキャッシュをバストします）が、それは Studio UI が fetch したときだけです（現状は Run training ページのマウント時）。同じページに留まったまま学習を複数回実行すると、ビルド成果物は再利用されます。編集した後は Run training ページをリロード（あるいはターミナルから `arkor build`）して変更を取り込んでください。`arkor dev` は単独で `.arkor/state.json` を書きません。
* `arkor build` は `src/arkor/index.ts`（または渡したエントリー）を読んで `.arkor/build/index.mjs` を書きます。Studio の dev ループの外側で直接呼ぶ必要があるのは CI や、スクリプトから `arkor start` の直前に走らせる場合などです。
* `arkor start` はランナー経由でエントリーを解決し、`.arkor/build/index.mjs` がない、もしくは明示的なエントリーを渡したときはリビルドして実行します（これが `trainer.start()` と `trainer.wait()` を呼びます）。Studio から学習をトリガーすると内部的に `arkor start` がサブプロセスとして起動されます。

状態がどこに置かれているかを把握しておくと CLI の挙動が予測しやすくなります。何かおかしいと感じたら、サポートに頼る前に `.arkor/state.json` と `~/.arkor/credentials.json` を覗いてみてください。