antfu

参考テンプレート：antfu/starter-ts。新しい TypeScript プロジェクトをスキャフォールディングする際は、新しい構成を独自に考案するのではなく、その package.json のスクリプト、eslint.config.js、knip.json、tsdown.config.ts、ワークフローを踏襲してください。

コーディングのプラクティス

コードの構成

• 単一責任：各ソースファイルのスコープ／目的を明確にし、焦点を絞ってください
• 大きなファイルを分割する：ファイルが大きくなったり、扱う関心事が多くなりすぎたりしたら分割してください
• 型を分離する：型とインターフェースは必ず types.ts または types/*.ts に分離してください
• 定数を抽出する：定数は専用の constants.ts ファイルに移してください

実行環境

• アイソモーフィックなコードを優先する：可能な限り、Node、ブラウザー、ワーカーで動作する、実行環境に依存しないコードを書いてください
• 実行環境を明示する：コードが特定の環境に依存する場合は、ファイルの先頭にコメントを追加してください：

// @env node
// @env browser

TypeScript

• 戻り値の型を明示する：可能な場合は戻り値の型を明示してください
• 複雑なインライン型を避ける：複雑な型は専用の type または interface 宣言に抽出してください

明示性

暗黙的な「魔法」よりも、明示的で追跡しやすいコードを優先してください。人間でもエージェントでも、ツールを実行せずにすべての名前の出所をたどれるようにしてください。

• インポートを明示する：明示的な import 文を優先してください。自動インポートは避けてください。フレームワークが自動インポートを提供している場合（例：Nuxt/Nitro）は、新しいプロジェクトでは無効にしてください（app-development を参照）。
• デフォルトではパスエイリアスを使わない：相対インポート（./foo、../bar）を使ってください。パスエイリアス（@/、~/、#imports など）は、プロジェクトですでに設定されている場合に限り使用し、グリーンフィールドのコードに新たに導入しないでください。

コメント

• 不要なコメントを避ける：コードは自己説明的にしてください
• 「方法」ではなく「理由」を説明する：コメントにはコードの動作ではなく、その理由や意図を記述してください

テスト（Vitest）

• テストファイル：foo.ts → foo.test.ts（同じディレクトリ）
• describe／it API を使用してください（test は使用しないでください）
• 複雑な出力には toMatchSnapshot を使用してください
• 言語固有のスナップショットには、明示的なパスを指定して toMatchFileSnapshot を使用してください

---

ツールの選択

@antfu/ni コマンド

コマンド	説明
ni	依存関係をインストール
ni <pkg> / ni -D <pkg>	依存関係／開発依存関係を追加
nr <script>	スクリプトを実行
nu	依存関係をアップグレード
nun <pkg>	依存関係をアンインストール
nci	クリーンインストール（pnpm i --frozen-lockfile）
nlx <pkg>	パッケージを実行（npx）

npm パッケージのバージョンを確認する

パッケージの最新バージョンを調べるには、fast-npm-meta を使用してください。パッケージごとに数メガバイトになることもあるレジストリ全体のデータをダウンロードするのではなく、小さなメタデータエンドポイントに問い合わせます。

nlx fast-npm-meta version vite              # 7.3.1
nlx fast-npm-meta version "nuxt@^3.5"       # 3.5.22 — range-aware
nlx fast-npm-meta version vite nuxt vue     # multiple at once
nlx fast-npm-meta version vite --json       # JSON for scripting
nlx fast-npm-meta full vite                 # full version list + dist-tags

最新バージョンだけが必要な場合は、npm view <pkg> version を実行したり、レジストリから package.json を直接読み取ったりするよりも、この方法を優先してください。

TypeScript の設定

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

ESLint の設定

// eslint.config.js
import antfu from '@antfu/eslint-config'

export default antfu({
  type: 'lib', // or 'app' (default)
  pnpm: true, // enforce pnpm catalogs in package.json
  antislop: true, // flag redundant/duplicated AI-style code, ban explicit `any`
})

antislop: true は必ず有効にしてください。開発依存関係として eslint-plugin-slop と eslint-plugin-sonarjs が必要です。

設定オプションの詳細：antfu-eslint-config

Knip

リントツールは一度に1つのファイルしか確認しないため、未使用のファイル、エクスポート、依存関係を検出するには Knip を使用してください。

// knip.json
{
  "$schema": "https://unpkg.com/knip@6/schema.json",
  "project": ["src/**/*.ts"],
  "ignoreDependencies": []
}

Knip が報告した項目は削除して修正してください。ignoreDependencies に追加するのは、package.json のスクリプト以外から呼び出されるツール（例：taze）に限ってください。

スクリプトと ci ゲート

すべてのプロジェクトで、すべてのチェックを1つのコマンドで実行する ci スクリプトを用意してください：

{
  "scripts": {
    "build": "tsdown",
    "lint": "eslint --cache",
    "typecheck": "tsc",
    "knip": "knip",
    "test": "pnpm run build && vitest",
    "ci": "pnpm run lint && pnpm run typecheck && pnpm run knip && pnpm run test --run"
  }
}

コミットする前に必ず nr lint --fix を実行して整形し、その後 nr ci を実行して成功することを確認してください。 ci が失敗する状態でコミットしないでください。ルールを無効にしたり、除外設定を追加したりせず、根本原因を修正してください。

Git フック

simple-git-hooks + nano-staged を使用します。pre-commit フックでは ci のすべてのチェックを実行し、prepare では skills-npm を使ってエージェントスキルもインストールします。

{
  "scripts": {
    "prepare": "git config core.hooksPath .githooks && simple-git-hooks && skills-npm"
  },
  "simple-git-hooks": {
    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && pnpm run ci && pnpx nano-staged"
  },
  "nano-staged": {
    "*": "eslint --fix --no-warn-ignored"
  }
}

.githooks を .gitignore に追加し、pnpm-workspace.yaml の allowBuilds に simple-git-hooks: true を追加します。

skills-npm

skills-npm は、インストール済みの npm パッケージに含まれるエージェントスキルをシンボリックリンクで配置し、skills フィールドで宣言されたスキルを取得して、インストールのたびにエージェントのスキルディレクトリに配置します。開発依存関係としてインストールし、上記のように prepare に組み込みます。また、skills/npm-* を .gitignore に追加します。生成された skills-npm-lock.json をコミットします。

公開

NPM_TOKEN シークレットよりも、npm Trusted Publishing（OIDC）の利用を推奨します。リリースは、id-token: write を指定した release.yml を通じて、CI 上で v* タグから実行します。nr release（bumpp）は、バージョンの更新、タグ付け、プッシュのみを行います。詳細は設定方法をご覧ください。

pnpm カタログ

バージョン管理には、pnpm-workspace.yaml で名前付きカタログを使用します。

カタログ	用途
prod	本番環境の依存関係
inlined	バンドラーにインライン化される依存関係
dev	開発ツール（リンター、バンドラー、テスト）
frontend	フロントエンドライブラリ

デフォルトのカタログは避けてください。カタログ名はプロジェクトのニーズに応じて変更できます。

---

参考資料

トピック	説明	参考資料
ESLint Config	フレームワークのサポート、antislop、フォーマッター、ルールの上書き、VS Code の設定	antfu-eslint-config
Project Setup	.gitignore、GitHub Actions、OIDC による信頼済み公開、VS Code 拡張機能	setting-up
App Development	Vue/Nuxt/UnoCSS の規約、自動インポートの制御、Storybook によるコンポーネントテスト	app-development
Library Development	tsdown によるバンドル、純粋な ESM での公開、publint、API スナップショット	library-development
Monorepo	pnpm ワークスペース、エイリアスの一元管理、Turborepo	monorepo