dev-setup

リポジトリに開発環境設定を導入する。目的は「設定ファイルをたくさん置くこと」ではなく、 そのプロジェクトが今必要としている分だけを、壊さずに、動く状態で入れること。

対象範囲

指定がなければ TypeScript（Node / ブラウザ）前提で進める。 決定表もテンプレートも TS を基準に書いてある。JS のみのプロジェクトなら型チェック関連を落とすだけでよい。

他言語（Python、Go 等）が検出された場合は、TS 前提のテンプレートを流用せず、 その言語の標準的なツールに読み替える。.gitignore / .editorconfig / .gitattributes / CI の骨格（§references/ci-recipes.md の「必ず入れる4つの設定」）は言語非依存なので そのまま使えるが、フォーマッター・リンター・型チェックの選定は 確認してから決める（記憶で書くと現行のデファクトを外す）。

混在リポジトリの場合は、主たる言語を1つ聞いてからそちらに寄せる。両方に完全な設定を 入れようとすると量が膨らんで機能しない。

原則

この5つを守れないなら、このスキルを使う意味はない。

1. 検出が先、質問は後 package.json を読めば分かることを人間に聞かない。質問は検出で判別できなかった項目だけに絞る。 質問が多いツールは使われなくなる。
2. 質問は一度にまとめる 1問ずつ往復しない。最大4問を一度に提示する（§2）。
3. 既存ファイルは上書きしない 既にある設定は必ず読んでから、差分と衝突を提示して承認を取る。 「良かれと思って」既存のルールを消すのが最悪の失敗。
4. 入れすぎない 「厳格度=最小」で lefthook も Renovate も CODEOWNERS も入れるのは事故。 決定表（references/catalog.md）の該当セルにないものは入れない。 入れたくなったら提案だけして、承認を取ってから入れる。
5. 置いて終わりにしない 導入したら実際にコマンドを走らせ、既存コードで通ることを確認する。 初回実行で数百件エラーが出る lint 設定は、導入していないのと同じ（むしろ有害）。

手順

1. 検出

まずリポジトリの状態を読む。質問の前に必ずやる。

ls -a                                    # 既存の設定ファイル
cat package.json 2>/dev/null             # scripts / deps / packageManager / private
ls -a | grep -iE 'lock\.(yaml|json)$|\.lock$'  # パッケージマネージャ特定（zsh でも安全）
ls .github/workflows/ 2>/dev/null        # 既存CI
cat tsconfig.json 2>/dev/null
git log --oneline -20 2>/dev/null        # コミット規約の有無、活動状況
git remote -v 2>/dev/null                # GitHub かどうか

検出で分かること（＝聞いてはいけないこと）:

新規（空ディレクトリ）の場合は検出材料がないので、言語・種別も質問に含める。 加えて、git init と package.json（npm init -y 等）が未作成なら、設定ファイルを置く前に作る。 lockfile が無い段階ではパッケージマネージャも確定しないので、§2 の質問と併せて確認する。

2. 質問（1回だけ）

検出で埋まらなかったものだけを、まとめて聞く。既に会話で分かっているものは飛ばす。

セットアップ内容を決めたいので4点だけ確認させてください。

Q1. このプロジェクトの種別は？
  a) アプリケーション（Web / モバイル / デスクトップ）
  b) ライブラリ・パッケージ（配布する）
  c) モノレポ
  d) 検証・使い捨て

Q2. 誰が触りますか？
  a) 自分だけ
  b) 社内チーム
  c) OSS として公開

Q3. どのくらい縛りますか？
  a) 最小限（フォーマット崩れを防げれば十分）
  b) 標準（CIでlint/型/testを回す。壊れたコードをmainに入れない）
  c) 厳格（コミット前フック、依存自動更新、レビュー体制まで）

Q4. CIは？
  a) 不要
  b) GitHub Actions
  c) その他（  ）

Q3 が最も重要。出力量がこれで決まる。迷っている様子なら「チーム開発なら b が無難」と補足してよい。

回答が決定表と食い違ったら、回答を優先する。 例えば Q3=標準（表では CI は◎）でも Q4=不要 なら CI は入れない。ただし理由は一度確認する。「回す環境がまだ無い」だけなら、 後から足せるよう scripts だけ揃えておく、という中間が取れる。

質問の回答が返ってきたら、references/catalog.md の決定表を読んで導入対象を確定する。

3. 提案（適用前に必ず出す）

いきなりファイルを書かない。何を入れるかを表で見せて承認を取る。

以下を導入します。

| 対象 | 内容 | 既存との関係 |
| --- | --- | --- |
| .gitignore | Node + エディタ + OS | 新規作成 |
| .editorconfig | LF / UTF-8 / インデント2 | 新規作成 |
| biome.json | フォーマット + lint | 既存の .prettierrc と競合 → 統合案は下記 |
| .github/workflows/ci.yml | lint / typecheck / test | 既存 deploy.yml とは別ファイル |

見送ったもの:
- lefthook（Q3=標準のため。必要なら後から追加できます）

既存の .prettierrc には printWidth: 100 の指定があるので、biome.json 側に引き継ぎます。
これで進めてよいですか？

衝突がある場合は必ず明示する。 特に:

• Prettier/ESLint → Biome への移行は、既存のカスタムルールが落ちる
• 既存 .gitignore に追記する場合、重複行は作らない
• 既存 CI がある場合、ジョブを増やすのか置き換えるのかを確認する

4. 適用

assets/ のテンプレートをベースに、検出結果に合わせて調整して配置する。 1ファイルに複数の設定が入っている雛形は、決定表で許可された分だけ残す。 lefthook.yml は pre-commit（△＝標準では提案のみ）と post-merge（○＝標準では入れる）の 両方を含むので、丸ごとコピーすると承認していない pre-commit まで入る。 テンプレートをそのままコピーするのではなく、検出した内容（パッケージマネージャ、Node バージョン、 既存 scripts 名）を反映させること。

comment-lint を入れる場合（決定表で△以上）は、次の3点をセットで行う。1つでも欠けると動かない。

1. comment-review スキルの scripts/comment-lint.mjs を、対象リポジトリの scripts/comment-lint.mjs にコピーする（依存の追加は不要）。 このスキルは雛形を持たない。実体を2箇所に置くと更新が片方に入らないため
2. assets/lefthook.yml の comment-lint job を残す（lefthook を入れない方針なら削る）
3. assets/github/workflows/ci.yml の comment-lint job を残す（CI を入れない方針なら削る）

comment-review が導入されていない環境では 1 ができない。その場合は comment-lint を見送り、§6 に「見送った理由」として記録する。

comment-lint.config.json は既定で作らない（無くても既定値で動く）。 重大度を引き上げるときだけ置く。判断の前に、既存コードで node scripts/comment-lint.mjs --all を走らせて件数を見る。 設定キーとルール一覧は comment-review/references/lint-rules.md。

ファイルを置くだけでは動かない。次の3つを行う。(a) と (b) は必須、(c) は確認と提案のみ。

(a) package.json の scripts を定義する

CI も §5 の検証も、この scripts が存在することを前提にしている。既存の script 名があれば それに合わせ、無ければ導入したツールに応じて追加する。

{
  "scripts": {
    "format": "biome format --write .",
    "lint": "biome check .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

型チェックを入れないなら typecheck を、テストが1本も無いなら test を書かない。 書かなかった script は CI からも必ず外す。 存在しない script を叩いて落ちる CI は、 原因が分かりにくいぶん無い方がましになる。

(b) ランタイムバージョンのファイルを先に置く

assets/github/workflows/ci.yml は node-version-file: .node-version を参照している。 このファイルが無いと setup-node はその場で失敗する。node -v で確認した値（または 合意した LTS）を書いた .node-version を先に作る。バージョン固定を入れない方針なら、 ci.yml 側を node-version: <値> の直書きに変える。どちらか一方は必ずやる。

(c) Claude Code 側の自動フォーマットが設定済みか確認する

フォーマッターを入れたのに、実行が毎回手動のままでは効果が半減する。編集のたびに 自動でフォーマッターを走らせる Claude Code の PostToolUse hook が設定済みかを確認する。

jq -r '.hooks.PostToolUse // empty' .claude/settings.json ~/.claude/settings.json 2>/dev/null

出力が空なら未設定。その場合は設定を提案する。承認が取れたら update-config スキルに 渡して設定してもらう。このスキルが settings.json を直接書くことはしない（理由は「非目標」）。

既に設定済みなら何も言わない。二重に提案しない。

ツール選定の判断基準は references/catalog.md、 CI の書き方は references/ci-recipes.md を読む。

バージョンを固定する箇所（Node、Actions のタグ等）は、記憶で書かずに確認する。 現行 LTS や最新メジャーは変わる。node -v、npm view <pkg> version、公式ドキュメントで確かめる。

5. 検証

配置したら実際に動かす。ここを飛ばさない。

<pm> install
<pm> run format   # または biome check --write .
<pm> run lint
<pm> run typecheck
<pm> run test

• lint が大量にエラーを吐く場合：ルールを緩めるか、自動修正をかけるか、 段階導入（新規ファイルのみ対象）にするかを提案する。エラーまみれのまま放置しない。

• pnpm で ERR_PNPM_IGNORED_BUILDS が出たら、先にそれを解消する。 pnpm 10 以降は 依存の postinstall を既定で実行しない。lefthook のようにインストール時処理を持つ パッケージがあると install が非ゼロで終わり、以後すべての pnpm run <script> が 依存状態チェックで失敗する（lint も typecheck も動かない）。エラーの見た目が スタックトレースなので原因に辿り着きにくい。

  pnpm-workspace.yaml に許可を書く。allowBuilds はリストではなくマップで、 値に true / false を取る（リストで書くと無視されて症状が変わらない）。

  # pnpm-workspace.yaml
  allowBuilds:
    lefthook: true

  pnpm approve-builds を対話で実行しても、同じ allowBuilds に書き込まれる。 dangerouslyAllowAllBuilds: true は全依存のスクリプトを無条件で実行するので使わない。 なお onlyBuiltDependencies / neverBuiltDependencies などは pnpm 11 で削除され、 allowBuilds に統合されている。既存プロジェクトで見かけたら移行が要る。

• Git hooks を入れた場合は、.git/hooks への登録まで確認する。 npm / pnpm 経由で lefthook を入れた場合は postinstall が自動で登録する（sync hooks: pre-commit, post-merge と出る）。ただし上記のビルド遮断が起きていると登録もされない。brew 等で入れた場合や、 登録が確認できない場合は lefthook install を明示的に実行する。 登録後、実際に対象ファイルを変更してコミットし、フォーマットが走ることを確認する。
• comment-lint を入れた場合は --all で現状を確認する。 既定は差分のみを見るので 導入直後は静かだが、既存コードの状態を把握せずに重大度を引き上げると後で詰まる。 error が多いルールは comment-lint.config.json で warning か off に落とす。
• 型チェックが大量にエラーを吐く場合：noUncheckedIndexedAccess や exactOptionalPropertyTypes は既存コードで数百件出ることがある。まず strict: true だけで 通し、追加オプションは1つずつ有効にして件数を見る。通らなかったオプションは無理に残さず外し、 §6 に「見送った理由」として記録する。
• CI ファイルは push しないと動かないので、ローカルで同じコマンド列が通ることを確認して代替とする。
• 既存コードに大量の差分が出るフォーマット適用は、フォーマット専用のコミットを分けるよう促す。 .git-blame-ignore-revs に追加すれば blame も汚れない。

6. 記録

導入内容を docs/setup.md（または README の一節）に残す。何を入れたかだけでなく 何をあえて入れなかったかを書く。これがないと、次に触った人（AIを含む）が 一度見送った設定を「足りない」と判断して勝手に再導入する。

## 開発環境設定

| 設定 | ツール | 用途 |
| --- | --- | --- |
| フォーマット/lint | Biome | `pnpm lint` / `pnpm format` |
| CI | GitHub Actions | PR時に lint / typecheck / test |

### あえて入れていないもの
- commitlint: コミット規約を強制するほどの人数ではないため
- Renovate: 依存が少なく手動更新で足りるため

非目標

このスキルがやらないこと。求められても勝手に踏み込まない。

• アプリケーションのコード生成（コンポーネント雛形、ルーティング等）。設定ファイルの領分に留める。
• 既存のビルド設定の作り替え（Vite/Next の設定変更）。触るなら明示的に依頼されたときだけ。
• デプロイ設定。CI は「壊れたコードを弾く」までを担当。デプロイは別の依頼として扱う。
• Claude Code 自体の設定への書き込み（settings.json の hooks、権限の allowlist）。 編集のたびに手でフォーマッターを打つ手間を減らす設定は update-config スキルの担当で、 ここでは書き込まない。ただし未設定なら提案はする（§4-(c)）。 黙って放置すると、フォーマッターを入れたのに手動実行が続く。
• 好みの押し付け。タブ/スペース、セミコロン有無などは既存コードの多数派に合わせる。 新規で決めようがない場合のみツールのデフォルトを使う。

参照ファイル

• references/catalog.md — 何を入れるかの決定表、ツール選定基準（Biome vs Prettier+ESLint 等）
• references/ci-recipes.md — GitHub Actions の構成パターンと、CI 時間・コストを抑える書き方
• assets/ — 各設定ファイルのテンプレート