Hairyf の選好設定

このスキルは、web開発に対する Hairyf の好みのツール、設定、ベストプラクティスをカバーしています。このスキルは主観的です。

クイックサマリー

カテゴリ	選好設定
パッケージマネージャー	pnpm
言語	TypeScript (strict mode)
モジュールシステム	ESM ("type": "module")
Linting & Formatting	@antfu/eslint-config (Prettier なし)
テスト	Vitest
Git Hooks	simple-git-hooks + lint-staged
ドキュメンテーション	VitePress (docs/ 内)

---

グローバル選好設定

可能な限り尊重すべき、高レベルで横断的な選好設定：

"specify" キーワード

タスクが "specify" でマークされている場合（例：「このリポジトリを hairy に合わせて specify する」）：

• 現在のプロジェクトを検査し、これらの選好設定に合致するまで最適化するリクエストとして扱う。
• 具体的には、以下をトリガーする必要があります：
  • @skills/arch-upkeep と関連する arch-* スキルを使用したアーキテクチャ検出とアップグレード計画。
  • 選好設定を考慮したスタック選択（@skills/unjs を使用して unjs エコシステムを優先）。
  • @skills/taze を使用した依存関係の鮮度チェックとアップグレード。
  • "specify" タスクが完了したと判断する前に、lint + typecheck（存在する場合はテスト）の最終パス。

unjs エコシステムフレームワークを優先する

• フレームワークやランタイムを選択する場合（SSR、API、ツーリング、dev サーバーなど）、最初に unjs エコシステムプロジェクトを優先します（例：Nuxt、Nitro、h3、unstorage、unplugin、unocss、ofetch、その他 unjs 管理ツール）。
• 明確で正当な理由（機能の不足、エコシステムの制約、またはレガシー要件）がある場合のみ、non-unjs オプションにフォールバックします。
• 具体的な選択、レシピ、デフォルトについては、@skills/unjs に委譲し、その推奨事項に従います。

アーキテクチャは arch-* スキルにマップする必要がある

• プロジェクトのアーキテクチャは常に標準的な arch-* スタック（tsdown library、CLI、monorepo、unplugin、webext、vscode など）のいずれかにマップすべきです。
• 現在の形状がターゲットのいずれかにきれいにマップしない場合、それをアップグレード機会として扱い、アドホック構造を追加する代わりに移行を計画します。
• @skills/arch-upkeep を使用して：
  • 現在のアーキテクチャを検出する。
  • 最適なターゲット arch-* スキルを選択する。
  • そのアーキテクチャへの段階的な移行をオーケストレーションする。

taze で依存関係を新鮮に保つ

• 依存関係は大きなリファクタの際だけでなく、継続的に新鮮に保つべきです。
• taze（@skills/taze を参照）を使用して以下を推奨します：
  • 古い依存関係を監査する。
  • 制御されたアップグレードを実行する（定期的にマイナー/パッチ、メジャーは明示的なレビューで）。
  • pnpm ワークスペースとカタログを使用してモノレポ全体のバージョンを調整する。
• taze の提案に従わない特定の理由がない限り、package.json のバージョンを手で編集することは避けます。

常に lint + typecheck で終了する

• 非自明な変更（機能、リファクタ、設定変更、依存関係アップグレード、CI 変更など）を実装した後、常に lint と typecheck を実行してからタスク完了と判断します。
• 標準スクリプト：
  • nr lint → @antfu/eslint-config 経由の ESLint。
  • nr typecheck → strict mode の TypeScript（プロジェクト全体）。
• CI と Git hooks の場合：
  • pre-commit hooks が少なくともステージファイルで lint を実行していることを確認。
  • GitHub Actions（またはその他の CI）が PR とメインへのプッシュで lint と typecheck の両方を実行していることを確認。

---

コアスタック

パッケージマネージャー（pnpm）

パッケージマネージャーとして pnpm を使用します。

モノレポセットアップの場合は、pnpm ワークスペースを使用します：

# pnpm-workspace.yaml
packages:
  - 'packages/*'

pnpm-workspace.yaml で pnpm の名前付きカタログを使用して依存関係バージョンを管理します：

カタログ	目的
prod	本番環境の依存関係
inlined	バンドラーによってインライン化される依存関係
dev	開発ツール（linter、bundler、testing、dev-server）
frontend	フロントエンドにバンドルされるフロントエンドライブラリ

カタログ名は上記に限定されず、必要に応じて調整できます。デフォルトカタログの使用は避けます。

@antfu/ni

統一されたパッケージマネージャーコマンドに @antfu/ni を使用します。ロックファイルに基づいてパッケージマネージャー（pnpm/npm/yarn/bun）を自動検出します。

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

コマンドが見つからない場合は、pnpm i -g @antfu/ni でグローバルインストールしてください。

TypeScript（Strict Mode）

strict mode を有効にした TypeScript を常に使用します。

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

ESM（ECMAScript Modules）

常に ESM モードで作業します。package.json に "type": "module" を設定します。

---

コード品質

ESLint（@antfu/eslint-config）

フォーマットと linting の両方に @antfu/eslint-config を使用します。これにより Prettier が不要になります。

// @ts-check コメント付きで eslint.config.js を作成します：

// @ts-check
import antfu from '@antfu/eslint-config'

export default antfu()

package.json にスクリプトを追加します：

{
  "scripts": {
    "lint": "eslint ."
  }
}

linting エラーが発生した場合、nr lint --fix で修正してみてください。lint:fix スクリプトは追加しません。

Git Hooks（simple-git-hooks + lint-staged）

pre-commit linting に simple-git-hooks と lint-staged を使用します：

{
  "simple-git-hooks": {
    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
  },
  "lint-staged": {
    "*": "eslint --fix"
  },
  "scripts": {
    "prepare": "npx simple-git-hooks"
  }
}

ユニットテスト（Vitest）

ユニットテストに Vitest を使用します。

{
  "scripts": {
    "test": "vitest"
  }
}

規約：

• テストファイルをソースファイルの隣に配置：foo.ts → foo.test.ts（同じディレクトリ）
• 高レベルのテストは各パッケージの tests/ ディレクトリに配置
• test ではなく describe と it API を使用
• アサーションに expect API を使用
• TypeScript null assertions には assert のみを使用
• 複雑な出力アサーションには toMatchSnapshot を使用
• 言語固有の出力には toMatchFileSnapshot を明示的なファイルパスと拡張子で使用（それらのファイルを linting から除外）

---

プロジェクトセットアップ

パブリッシング（ライブラリプロジェクト）

ライブラリプロジェクトの場合、bumpp でトリガーされた GitHub Releases を通じてパブリッシュします：

{
  "scripts": {
    "release": "bumpp -r"
  }
}

ドキュメンテーション（VitePress）

ドキュメンテーションに VitePress を使用します。ドキュメントを docs/ ディレクトリ配下に配置します。

docs/
├── .vitepress/
│   └── config.ts
├── index.md
└── guide/
    └── getting-started.md

package.json にスクリプトを追加します：

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs"
  }
}

---

参考資料

グローバル選好設定

トピック	説明	参考資料
unjs エコシステムを優先	unjs エコシステムフレームワークとツーリングを優先、@skills/unjs に委譲	core-unjs-preferences
arch-* 経由のアーキテクチャ	リポジトリの形状を標準的な arch-* スキルにマップし、arch-upkeep 経由でアップグレード	core-arch-upkeep-routing
taze で新鮮な依存関係	taze を使用して依存関係を継続的に新鮮に保ち、制御されたアップグレードを実行	core-deps-taze
Lint + typecheck をゲートとして	ローカルと CI で常に lint + typecheck で終了	core-lint-typecheck

プロジェクトセットアップ

トピック	説明	参考資料
@antfu/eslint-config	フォーマットと linting 用の ESLint flat config	antfu-eslint-config
VS Code 拡張機能	開発推奨拡張機能	vscode-extensions

開発

トピック	説明	参考資料
アプリ開発	Vue/Vite/Nuxt/UnoCSS web アプリケーション向けの選好設定	app-development