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 を強制。
--git	確認なしで git リポジトリを初期化し、初回コミットを作成。
--skip-git	git init を黙ってスキップ。
--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 のヒントが表示されます。

​

テンプレート

テンプレート	タスク	出力の形
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

​

何が書かれるか

ツールが触るパスは最大 8 つ。いずれもユーザーの既存内容を上書きしません:

パス	振る舞い
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 で作成されます。

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 の次のステップ