arkor init

カレントディレクトリーに Arkor プロジェクトを生成。

​

arkor init

src/arkor/index.ts、src/arkor/trainer.ts、arkor.config.ts、スターター package.json を カレントディレクトリー に生成します。既存リポジトリに Arkor を追加したいときに使います（Quickstart のプロジェクト生成フローは同じツールを 1 つ上のディレクトリーで実行します）。

​

概要

arkor init [options]

pnpm

pnpm arkor init

​

オプション

フラグ	説明
-y, --yes	プロンプトの代わりにデフォルトを採用（プロジェクト名はディレクトリー名、テンプレートは triage）。
--name <name>	プロジェクト名。デフォルトはカレントディレクトリー名（パスに basename がない場合 arkor-project、例えば /）。package.json に書く前にサニタイズされます。
--template <id>	スターターテンプレート。選択肢: triage、translate、redaction。未知の ID はファイル操作前に例外が発生します。
--skip-install	生成後のパッケージマネージャーの install をスキップ。
--use-npm	パッケージマネージャーに npm を強制。
--use-pnpm	パッケージマネージャーに pnpm を強制。
--use-yarn	パッケージマネージャーに yarn を強制。
--use-bun	パッケージマネージャーに bun を強制。Windows 既知の制約: arkor init --use-bun は node_modules までは作成されるものの bun.lock が生成されないため、初回コミットに lockfile が含まれません。bun install 直接実行および create-arkor --use-bun はこの影響を受けません。
--git	確認なしで git リポジトリを初期化し、初回コミットを作成。
--skip-git	git init を黙ってスキップ。
--allow-builds	esbuild の postinstall スクリプトを pnpm install で実行することを許可（pnpm 専用。yarn / npm / bun はワークスペース yaml を無視）。デフォルトは deny。下記 postinstall スクリプト（pnpm 11+） を参照。
--agents-md	AI コーディングエージェントに「arkor は学習データより新しい」ことを伝える AGENTS.md と CLAUDE.md を書き出す。デフォルト。
--no-agents-md	AGENTS.md / CLAUDE.md の生成をスキップ。既存のユーザー記述の AGENTS.md は常に保持され、arkor 管理の block（<!-- BEGIN:arkor-agent-rules --> / <!-- END:arkor-agent-rules --> で区切られる）は初回は末尾追記、再 scaffold 時はその場で置換されます。

--git と --skip-git は排他です。両方渡すと例外が発生します。--agents-md と --no-agents-md も同様です。

​

振る舞い

​

デフォルトの流れ

デフォルトでは部分的に対話的です。プロジェクト名、スターターテンプレート、（git リポジトリ内でなければ）git init を実行するかを先にすべて尋ねたうえで、--skip-install が指定されない限り（確認プロンプトなしで）パッケージマネージャーの install を自動実行します。git init の確認を install よりも前に出すことで、すべてのプロンプトに先に答えてしまえば、install を放置して離席できるようにしています。実際の git init と初回コミットは install の後に走り、生成されたロックファイルが初回コミットに含まれます。パッケージマネージャーが解決できない（--use-* フラグなし、npm_config_user_agent からの検出も失敗）ときは install ステップはスキップされ、最後に手動 install のヒントが表示されます。

​

postinstall スクリプト（pnpm 11+）

選んだパッケージマネージャが pnpm のとき（明示的に --use-pnpm を指定したか、npm_config_user_agent から pnpm が検出された場合、例: pnpm arkor init、あるいは --use-* フラグなしでパッケージマネージャー検出も解決せず空の新規ディレクトリーに scaffold する場合）、package.json と同階層に pnpm-workspace.yaml を出力します。

packages: []
allowBuilds:
  esbuild: false

次の場合は 書き出されません:

• --use-npm / --use-yarn / --use-bun が指定されている（これらのツールはこのファイルを読まない）。
• ターゲットディレクトリーに既存ファイルがあり、--use-* 指定がない（推測でワークスペース設定を他人のプロジェクトに置かない）。
• 祖先ディレクトリーに既に pnpm-workspace.yaml がある（親モノレポのワークスペースが支配的。ここでネストして作ると親を遮蔽し、上位の workspace:* 解決が壊れます）。

ターゲットに pnpm-workspace.yaml が既にある場合、pnpm があり得る とき（新規作成と同じく --use-pnpm / UA 検出が pnpm / 未解決のいずれか。--use-npm / --use-yarn / --use-bun の場合は既存ファイルも触りません）のみ patch します。トップレベルの allowBuilds: ブロックに esbuild: false（--allow-builds が指定されている場合は esbuild: true）を追記（無ければブロックごと作成）し、無関係なキーは触りません。esbuild が既に明示的に値（true / false）でピン留めされていたり、ファイルが allowBuilds: false / allowBuilds: true のスカラー形（global pin）を使っている場合、allowBuilds の判断については no-op で終わります。ただし allowBuilds no-op の run でも、トップレベルに packages: キーが無ければ packages: [] を補完します（pnpm 9 が packages: 欠落の pnpm-workspace.yaml に対して “packages field missing or empty” でエラーになるため）。保持されるのは allowBuilds.esbuild の判断であって、ファイル自体はこの 1 つの構造的キーが追加され得る点に注意してください。

pnpm 11 から postinstall スクリプトの既定が「明示的に承認しない限り実行しない」に変わり、未承認のスクリプトに当たると ERR_PNPM_IGNORED_BUILDS（exit code 1）で失敗するようになりました。esbuild はそうしたスクリプト（node install.js、プラットフォーム別バイナリの検証/取得）を持つため、scaffold したばかりのプロジェクトでそのまま pnpm install するとこのエラーになります。

scaffold が書く allowBuilds: { esbuild: false } は明示的な deny です。pnpm は「決定済み」と判断してスクリプトをサイレントにスキップし、エラーになりません。esbuild 自身は動作します（pnpm が @esbuild/<platform> を optionalDependency としてすでにインストールしているためです）。yarn / npm / bun は pnpm-workspace.yaml を読まないので、それらでは無効化されたファイルとして扱われます。

esbuild の postinstall を実際に走らせる必要がある場合（まれ、通常は壊れたインストーラーや特殊なプラットフォーム）は --allow-builds を渡してください。

pnpm arkor init --yes --use-pnpm --allow-builds

あるいは後から pnpm-workspace.yaml のエントリーを true に書き換えてください。このフラグは pnpm-workspace.yaml を実際に出力 / patch する run でのみ参照されるため、--use-npm / --use-yarn / --use-bun の指定下では no-op になります（それらの run はファイルに一切触れません）。後から pnpm に切り替えた場合は arkor init --use-pnpm --allow-builds を再実行してください。

​

テンプレート

テンプレート	タスク	出力の形
triage	サポートのトリアージ	{ category, urgency, summary, nextAction }
translate	9 言語の翻訳	{ translation, detectedLanguage }
redaction	個人情報のマスク	{ redactedText, redactedCount, tags }

3 つとも同じ小型のオープンウェイトベース（gemma-4-E4B-it）と HuggingFace 上の厳選公開データセットを組み合わせています。

​

パッケージマネージャー検出

--use-* フラグが渡されないとき、CLI は npm_config_user_agent を見てどのパッケージマネージャーから呼ばれたかを検出します（これは corepack が使う標準の仕組みなので、pnpm dlx、yarn dlx、bunx などすべて動きます）。

検出に失敗してフラグもなければ install ステップはスキップされ、手動 install のヒントが最後に表示されます。

​

Git ポリシー

arkor init は git init + 初回コミットを実行するかどうかを次のルールを上から評価して決めます:

1. カレントディレクトリーが既に git リポジトリ内なら、スキップ（ログを出す）。
2. --skip-git が渡されていれば、スキップ。
3. --git または -y が渡されていれば、確認なしで実行。
4. 対話的なシェルでは尋ねる（デフォルト: yes）。
5. 非対話的でフラグなしなら、スキップ。

対話的な確認は install の 前 に出します（数分かかる <pm> install の後にプロンプトを出さないため）が、git init の実行自体は install の 後 に走るので、パッケージマネージャーが生成したロックファイルが初回コミットに含まれます。コミット署名に失敗（GPG agent が動いていないなど）した場合、CLI は署名なしコミットにフォールバックして警告します。あとで git commit --amend -S で再署名できます。

​

CI / 非対話シェル

process.stdout が TTY でない、または CI が環境にあるとき arkor init は非対話的になります。プロンプトはデフォルト値でスキップされ入力待ちでブロックしません。CI から決定的に生成するには:

pnpm

pnpm arkor init --yes --template triage --use-pnpm --skip-git

--yes でプロジェクト名とテンプレートのデフォルト（ディレクトリー名と triage）を採用、--use-pnpm（または対応する --use-<pm>）でパッケージマネージャー検出を省略、--skip-git で git init をオプトアウト。node_modules/ がすでにあるイメージなら --skip-install も渡してください。

非対話シェルで --yes を忘れてもコマンドは完走します（プロンプトはデフォルトを使う）が、静かに動作するためログからは見落としやすい挙動になります。上記の明示形を推奨します。

​

Claude Code（CLAUDECODE=1）厳格モード

Claude Code は子プロセスに CLAUDECODE=1 を渡し、対話プロンプトに応答できません。エージェントが隠れたデフォルトで黙ってプロジェクトを生成してしまうのを防ぐため、この環境変数下では arkor init は厳格モードに切り替わります。下記のキュレーション済みフラグセットが必須となり、不足があれば実行ではなく、再実行用のコマンドを stderr に出して終了します。通常はプロジェクト名を必須にしていません。arkor init は basename(cwd) から派生させており、これは対話プロンプトでのデフォルト提案値と同じだからです。ただし、generic な arkor-project フォールバックに silent collapse してしまう次の 2 ケースは厳格モードでも --name <name> を要求します: (a) --name が渡されていてその値に ASCII 英数字が 1 つも含まれない (例: --name "!!!")、(b) --name 省略時のカレントディレクトリ basename にも ASCII 英数字が含まれない (例: /tmp/!!!/ から arkor init を実行)。パッケージマネージャーは厳密にはプロンプトではありません（UA 自動検出か検出失敗時の silent skip）が、npm_config_user_agent 任せにせず --use-* か --skip-install をエージェントが明示的に選ぶように、こちらは必須としています。

必須フラグ（または -y/--yes で「すべてデフォルトで進める」にオプトインしてください）:

• --template <triage|translate|redaction>
• --git（推奨。対話モードのデフォルトと同じ）または --skip-git
• パッケージマネージャー系フラグ: --use-npm / --use-pnpm / --use-yarn / --use-bun、または --skip-install
• --agents-md（特に CLAUDECODE 下では推奨）または --no-agents-md

フラグが不足したときの stderr 例。各フラグには一行の説明が併記され、ドキュメントを往復しなくてもエージェントが値を決められるようになっています:

arkor init: CLAUDECODE=1 detected. Interactive prompts are disabled.
Re-run with explicit flags:
  --template <triage|translate|redaction>
      Starter template: `triage` (support routing), `translate` (9-language translation), or `redaction` (PII removal).
  --git (recommended) or --skip-git
      `--git` runs `git init` and creates an initial commit (matches the interactive default); `--skip-git` leaves git setup to the user.
  --use-pnpm (or --use-npm / --use-yarn / --use-bun, or --skip-install)
      Which package manager to run `install` with after scaffolding. `--skip-install` leaves the install step to the user.
  --agents-md (recommended) or --no-agents-md
      `--agents-md` writes `AGENTS.md` + `CLAUDE.md` to brief AI coding agents that arkor post-dates their training data (recommended, especially under CLAUDECODE); `--no-agents-md` skips them.
Or pass -y/--yes to accept all defaults.

終了コードは 1、早期終了の前にファイル生成は一切行われないので、ディレクトリは元の状態のままです。同じルールは create-arkor にも適用されます（Quickstart に create-arkor 固有の詳細を記載しています。プロジェクト名を明示的に決めさせるための [dir] / --name 必須化も含む）。

​

エラー

メッセージ	意味	対処
Pick one of --git / --skip-git, not both.（--git と --skip-git のどちらか一方だけ指定してください）	git 関連の両フラグを渡した。	どちらか一方にする。
Unknown template "<id>". Available: triage, translate, redaction（未知のテンプレート <id>。利用可能: triage, translate, redaction）	--template の値がどの登録テンプレート ID にも一致しなかった。	一覧の ID を使う。
Commit signing failed: created an unsigned commit.（コミット署名に失敗しました。署名なしコミットを作成しました）	git init は成功したが初回コミットを GPG 署名できなかった。	署名のセットアップを直したら git commit --amend -S で再署名。リポジトリ自体は問題なし。

​

例

対話:

pnpm

pnpm arkor init

デフォルト採用、install スキップ、git スキップ:

pnpm

pnpm arkor init --yes --skip-install --skip-git

テンプレートを固定してパッケージマネージャーを強制:

pnpm

pnpm arkor init --template translate --use-pnpm

​

何が書かれるか

ツールが触るパスは最大 10 個で、無条件の 6 個に加え、AGENTS.md 関連の 2 個、パッケージマネージャー設定 2 個が条件付きで追加されます。いずれもユーザーの既存内容を上書きしません:

パス	振る舞い
src/arkor/index.ts	無ければ createArkor({ trainer }) で 作成。あれば そのまま。
src/arkor/trainer.ts	無ければ選んだテンプレートの createTrainer({...}) で 作成。あれば そのまま。
arkor.config.ts	無ければプレイスホルダーの export として 作成。あれば そのまま。プロジェクト構成 を参照。
README.md	無ければスターター README で 作成。あれば そのまま。
.gitignore	無ければ node_modules/、dist/、.arkor/ で 作成。ファイルがあって .arkor/ が入っていなければ追記で パッチ。既に入っていれば変更なし（Ok）。
package.json	無ければ name / private / type: "module" / dev+build+start のスターター scripts / devDependencies.arkor で 作成。不足している script があれば追加し、devDependencies.arkor がなければ追加する パッチ。既存の値（カスタム dev script など）は 上書きしません。すべて揃っていれば変更なし（Ok）。
AGENTS.md	無ければ arkor 管理の block を含めて 作成（デフォルト。--no-agents-md でスキップ可）。既存ファイルがあれば、arkor 管理 block（<!-- BEGIN:arkor-agent-rules --> / <!-- END:arkor-agent-rules --> で区切り）を パッチ（初回は末尾に追記、再 scaffold ではその場で置換）。marker 外のユーザー記述はすべて保持されます。canonical block が既に最新なら変更なし（Ok）。canonical 管理 block が複数含まれている場合、どちらを更新するかを推測すると壊れる可能性があるため、ファイルは そのままにして警告を出します。ユーザーが重複を解消すれば次回の再 scaffold でその場でパッチされます。
CLAUDE.md	無ければ Claude Code の import ディレクティブ @AGENTS.md で 作成（デフォルト。--no-agents-md でスキップ可）。既にファイルがあれば そのままで、プロジェクト固有の CLAUDE.md を上書きしません。AGENTS.md が canonical 管理 block 複数のため kept された場合は警告つきで スキップ されます。その状態で @AGENTS.md shim を作ると、未解決の重複ルールを Claude Code の context に auto-import してしまうためです。AGENTS.md を dedupe したあとの再 scaffold で作成されます。
pnpm-workspace.yaml	条件付き。 詳細は postinstall スクリプト（pnpm 11+） を参照。pnpm があり得て、かつ祖先に pnpm-workspace.yaml が無い場合に packages: [] + allowBuilds.esbuild: false（--allow-builds 指定時は : true）で 作成。ファイルが既にあって pnpm があり得る場合は パッチ: esbuild が未ピンならば esbuild: <bool> を allowBuilds: に追記。--use-npm / --use-yarn / --use-bun と pnpm モノレポのサブディレクトリ内では スキップ。
.yarnrc.yml	条件付き。 レイヤード判定の全文は packages/cli-internal/src/scaffold.ts を参照。yarn があり得る新規 scaffold（--use-yarn、UA 検出が yarn、または --use-* なしで UA 検出失敗）でのみ nodeLinker: node-modules で 作成。あれば そのまま（デフォルト以外の nodeLinker: は競合警告、nodeLinker: キー欠落は yarn-berry caveat）。明示的な非 yarn pm、および positive yarn-berry signal がない既存非空ディレクトリでの --use-yarn では スキップ。

CLI は install 前に “Files” ノートとしてファイル一覧を表示し、各パスの action（created / kept / patched / ok / skipped）を出すので、何が変わったか正確に確認できます。

​

自分で AGENTS.md を編集するときの規約

arkor 管理 block の判定は、BEGIN / END マーカー + 先頭シグネチャ行（# arkor is newer than your training data）の 3 条件をすべて満たす場合のみです。バッククオートで囲んだインラインのマーカー言及は安全ですが、fenced code block の中身としてマーカーとシグネチャ行をそのままの行として書いた場合、本物の管理 block と見分けがつきません。再 scaffold で自分のドキュメント例が誤って上書きされないよう、AGENTS.md を編集するときは次の規約に従ってください:

• マーカーはインラインのバッククオートで引用してください（例: `<!-- BEGIN:arkor-agent-rules -->`）。本物の管理 block の外で、マーカーを単独行に書かないでください。
• 仕様の説明などで verbatim ブロックとしてマーカーを示す必要がある場合は、シグネチャ行を 1 文字でも変えてください（例: # arkor is newer than YOUR training data）。これで検出ロジックにマッチしなくなります。
• ファイルにシグネチャ一致のブロックが 2 つ以上あると、scaffolder はパッチを拒否して warning を出します。その場合はファイルを dedupe してください。通常は古い手編集の canonical block を消して、残った 1 つを再 scaffold が更新する形になります。

​

関連項目

• Quickstart: 新規プロジェクトでの生成フロー
• プロジェクト構成: 各生成ファイルの役割
• arkor dev: init の次のステップ