開発パターンとベストプラクティス集

version
1.0.0

Install

/plugin install recipes@otolab

Run it inside Claude Code after adding the marketplace with /plugin marketplace add otolab/ai-agent-prompts.

Contents

Discovered from source

Agents 10

Recipes - 作業方法・方針雛形集

Claudeとの作業において頻繁に利用する作業方法や方針の雛形を目的別に整理・保存するディレクトリです。

概要

目的: プロジェクト作成・管理時の一貫した作業方法を確立し、効率的で品質の高い開発を実現する

対象範囲:

  • プロジェクト作成時の初期設定手順
  • 開発フロー・方針テンプレート
  • ドキュメント作成・管理方針
  • 品質管理・テスト戦略
  • デプロイ・運用方針

ディレクトリ構造

recipes/
├── README.md                    # 本ファイル - 全体概要とインデックス
├── document-code-test/          # ドキュメント・コード・テストの三位一体同期管理
├── npm-workspaces-typescript/   # npm workspaces x TypeScript設定ガイド
├── serena-integration/          # Serenaコード解析ツールの導入・設定
└── testing/                     # テスト戦略・分類・実装指針

利用方法

新しいレシピの作成

  1. 目的に応じて適切なカテゴリディレクトリを選択
  2. {purpose}-{description}.md 形式でファイル作成
  3. テンプレート形式で具体的な手順・方針を記述

既存レシピの活用

  1. 目的に合致するレシピを検索・選択
  2. プロジェクトの特性に合わせてカスタマイズ
  3. 実践後の改善点をレシピにフィードバック

レシピ作成ガイドライン

記述原則

  • 具体性: 抽象的でなく実行可能な手順
  • 再現性: 誰でも同じ結果を得られる明確性
  • 保守性: 変化に対応できる柔軟な構造
  • 効率性: 無駄のない最適化された手順

テンプレート構成

# [レシピ名]

## 目的
[何を達成するためのレシピか]

## 前提条件
[必要な環境・知識・ツール]

## 手順
[具体的なステップバイステップ手順]

## 期待する成果
[完了時に得られる結果]

## 注意点・制約
[注意すべき点や制約事項]

## 関連レシピ
[関連する他のレシピへのリンク]

現在のレシピ

document-code-test/

ドキュメント・コード・テストの三位一体同期管理

  • DOCUMENT_CODE_TEST_SYNC.md - ドキュメント・コード・テストの三位一体同期管理方針
    • 三要素の同期戦略と「正」の判定基準
    • 不一致パターンの検出と解決手順
    • トレーサビリティ確保のためのコメント・テストタイトル方針

npm-workspaces-typescript/

npm workspacesとTypeScript Project References連携ガイド

  • setup-guide.md - モノレポ環境の正しい設定方法
    • 二つの依存関係グラフ(ランタイム/コンパイルタイム)の理解
    • ルート/パッケージレベルの具体的な設定例
    • npm操作の実行場所と-wフラグの重要性
    • トラブルシューティングと自動化ツール

testing/

テスト戦略・分類・実装指針

  • TEST_CLASSIFICATION.md - テストの分類と基本方針
    • ユニット/インターフェース/統合/システム/E2Eテストの定義
    • 各テストレベルの責任範囲と実装指針
    • モック使用方針とセットアップパターン

serena-integration/

Serenaコード解析・編集ツールの導入と設定

  • SERENA_PROJECT_SETUP.md - プロジェクトへのSerena導入手順
    • Claude Codeとの統合設定(自動アクティベート対応)
    • ブラウザ自動起動の無効化設定
    • 大規模プロジェクトのインデックス作成
    • プロジェクト固有の設定とトラブルシューティング

作成日: 2025年8月12日 最終更新: 2025年10月22日
管理者: Claude Code User

関連ファイル:

  • ~/.claude/CLAUDE.md - 個人作業指針
  • ~/.claude/TECH_NOTES.md - 技術開発ノート

ドキュメント・コード・テストの三位一体同期管理

概要

ドキュメント、コード、テストの三要素を常に同期させ、プロジェクトの整合性と品質を保つための方針です。

基本原則

三位一体の関係

ドキュメント ←→ コード ←→ テスト
     ↑                      ↓
     └────────────────────────┘

三要素は最終的に完全に同期されるべき

  • ドキュメント: 設計意図と仕様を記述
  • コード: 実際の動作を実装
  • テスト: 仕様と動作を保証

同期の基本戦略

「どれが正か」を判断し、正しいものに他を合わせる

  1. 通常の開発フロー: コード → テスト → ドキュメント

    • 実装が先行し、動作を確認してから文書化
  2. 設計駆動開発: ドキュメント → テスト → コード

    • 仕様を定義し、テストを書いてから実装
  3. テスト駆動開発: テスト → コード → ドキュメント

    • 期待動作を定義し、実装してから文書化

同期確認の実践

1. 正の判定基準

状況別の「正」の判定

状況正とすべきもの理由
実装済み機能の修正コード実際に動作しているものが真実
新機能の設計ドキュメント設計意図が最も重要
バグ修正テスト期待動作を明確に定義
リファクタリングテスト動作を変えずに実装を改善
仕様変更ドキュメント新しい仕様を起点に修正

2. 不一致の検出

三要素間の不一致パターン

  • D-C不一致: ドキュメントの説明とコードの動作が異なる
  • C-T不一致: コードの実装とテストの期待値が異なる
  • T-D不一致: テストの仕様とドキュメントの記載が異なる
  • D-C-T不一致: 三要素すべてが異なる(最も深刻)

3. 同期の実行手順

  1. 現状把握

    • 三要素それぞれの状態を確認
    • 不一致の箇所と種類を特定
    • 最後に更新された要素を確認
  2. 正の決定

    • 上記の判定基準に従って「正」を決定
    • 不明な場合は実際の動作(コード)を優先
    • 設計意図が重要な場合はユーザーに確認
  3. 同期作業

    • 正とした要素に他の要素を合わせる
    • 修正の順序: 依存関係の少ない要素から
    • 各修正後に整合性を確認

チェックポイント

必須確認項目

ドキュメント

  • APIの仕様が実装と完全一致
  • 使用例が実際に動作する
  • エラーケースの説明が正確

コード

  • ドキュメントに記載された機能を実装
  • テストケースをすべてパス
  • エッジケースの処理が適切

テスト

  • ドキュメントの仕様を網羅
  • コードの全機能を検証
  • 正常系・異常系の両方をカバー

同期の品質指標

  • カバレッジ: テストが仕様とコードをどれだけカバーしているか
  • 一致度: 三要素間で記述が一致している割合
  • 更新頻度: 各要素が適切に更新されているか
  • トレーサビリティ: 要素間の対応関係が明確か

トレーサビリティの確保

コメントとテストタイトルの役割

ドキュメントとの関連性を明示的に記述する意義

ドキュメントが充実していても、コードとテストには適切なコメントが必要です。これらは異なる役割を持ち、相互補完的に機能します。

コード内コメントの意義

役割:

  • ドキュメントへの参照ポイントを提供
  • 実装意図とドキュメント記載の関連を明確化
  • コードレビュー時の仕様確認を容易に
  • 将来の変更時に影響範囲を把握しやすく
テストタイトルの意義

役割:

  • テストが検証している仕様を明確化
  • テスト失敗時にどの仕様が満たされていないか即座に判断
  • カバレッジ分析時に仕様網羅性を確認
  • ドキュメント更新時の影響テストを特定

コメント省略の誤解

ドキュメント整備 ≠ コメント不要

要素記載内容読者
ドキュメント全体像・仕様・使い方エンドユーザー・開発者
コードコメント実装意図・制約・参照実装者・保守担当者
テストタイトル検証内容・仕様参照テスト実行者・QA

それぞれが異なる文脈で読まれ、異なる情報を提供します。

継続的同期のプラクティス

変更時のルール

  1. コード変更時

    • 関連テストの更新または追加
    • 影響を受けるドキュメントの更新
  2. ドキュメント変更時

    • 仕様変更の場合はテストを先に更新
    • 説明改善の場合はコードとの一致を確認
  3. テスト変更時

    • 仕様変更を反映している場合はドキュメント更新
    • バグ修正の場合はコードを修正
    • テストの意図を明確に記述

優先順位

  1. 最優先: 機能に影響する不一致
  2. 高優先: ユーザーに見える不一致
  3. 中優先: 内部仕様の不一致
  4. 低優先: 表記や文言の不統一

作成日: 2025年1月 用途: ドキュメント・コード・テストの三位一体同期管理方針

npm workspaces x TypeScript設定ガイド

npm workspacesとTypeScript Project Referencesの設定方法について解説しています。

詳細ドキュメント

@setup-guide.md

npm workspacesとTypeScript Project References設定ガイド

概要

このガイドは、npm workspacesとTypeScript Project Referencesを正しく連携させ、モノレポ環境でビルドキャッシュが適切に機能するための設定方法を解説します。

核心概念:二つの依存関係グラフ

モノレポには二つの独立した依存関係グラフが存在します:

  1. ランタイムグラフ - npm workspacesが管理(package.json)
  2. コンパイルタイムグラフ - TypeScript Project Referencesが管理(tsconfig.json)

これらの同期が崩れると、ビルドキャッシュが正しく機能しなくなります。

設定手順

1. ルートレベルの設定

package.json(ルート)
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "build": "tsc --build --force --verbose",
    "clean": "tsc --build --clean"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

重要ポイント:

  • private: true - ルートパッケージの誤公開を防止
  • workspaces - npm workspacesを有効化
  • 開発ツールはルートのdevDependenciesに統一
tsconfig.base.json(ルート)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",

    // Project References用の必須設定
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "incremental": true
  }
}
tsconfig.json(ルート)
{
  "files": [],
  "include": [],
  "references": [
    { "path": "packages/shared" },
    { "path": "packages/app" }
  ]
}

重要ポイント:

  • filesとincludeは空配列
  • referencesにすべてのパッケージをリスト

注意: ルートディレクトリにTypeScriptファイル(設定ファイル等)がある場合:

{
  "compilerOptions": {
    "noEmit": true  // ルートでのビルドファイル生成を防止
  },
  "include": [
    "packages/*/src/**/*"  // 型チェック対象を明示的に指定
  ],
  "exclude": [
    "node_modules",
    "**/dist",
    "**/*.test.ts"
  ]
}
  • noEmit: trueでルートディレクトリでのビルドファイル生成を完全に防止
  • includeで型チェックの範囲を適切に限定
  • 各パッケージは独自のtsconfig.jsonで実際のビルドを実行

2. パッケージレベルの設定

ライブラリパッケージ(packages/shared)

package.json

{
  "name": "@my-org/shared",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc --build --force --verbose"
  }
}

tsconfig.json

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*"],
  "references": []
}
アプリケーションパッケージ(packages/app)

package.json

{
  "name": "@my-org/app",
  "version": "1.0.0",
  "main": "dist/index.js",
  "dependencies": {
    "@my-org/shared": "*"
  },
  "scripts": {
    "build": "tsc --build --force --verbose"
  }
}

注意: npmではworkspace:*記法はサポートされていません。以下が使用可能:

  • "*" - ワークスペース内の任意のバージョン
  • "^1.0.0" - 特定バージョン(ただし実際にはワークスペースリンクが優先)
  • "file:../shared" - 相対パス(非推奨、workspacesがある場合は不要)

tsconfig.json

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../shared" }
  ]
}

最重要:dependenciesとreferencesが完全に対応していること!

運用上の注意事項

スクリプトのエラーハンドリング

npm workspacesには、複数ワークスペースのスクリプトを「順番に実行し、失敗時に停止する」組み込みオプションがありません。--workspacesフラグは全ワークスペースで並列実行され、1つが失敗しても他は継続されます。

問題のある設定:

{
  "scripts": {
    "build": "npm run build --workspaces",
    "test": "npm test --workspaces",
    "lint": "npm run lint --workspaces"
  }
}

これらは失敗しても次のワークスペースの処理が継続され、エラーを見逃す可能性があります。

推奨設定(明示的な順次実行):

{
  "scripts": {
    "build": "npm run build -w @my-org/core && npm run build -w @my-org/utils && npm run build -w @my-org/app",
    "test": "npm test -w @my-org/core && npm test -w @my-org/utils && npm test -w @my-org/app",
    "lint": "npm run lint -w @my-org/core && npm run lint -w @my-org/utils && npm run lint -w @my-org/app"
  }
}

メリット:

  • 失敗時に即座に停止(&&演算子の効果)
  • 実行順序が明確(依存関係順に記述可能)
  • CI/CDでのエラー検出が確実
  • エラー箇所の特定が容易

デメリット:

  • 新規パッケージ追加時にスクリプトも更新が必要
  • package.jsonが冗長になる

npm installの実行場所

必ずルートディレクトリで実行:

# 正しい
cd /path/to/monorepo
npm install

# 間違い(個別パッケージ内での実行)
cd packages/app
npm install  # これは依存関係グラフを破壊する

依存関係の追加

-wフラグを使用して特定ワークスペースに追加:

# packages/appにexpressを追加
npm install express -w @my-org/app

# packages/sharedにlodashを追加
npm install lodash -w @my-org/shared

新規パッケージ追加時のチェックリスト

  1. パッケージディレクトリを作成
  2. package.jsonを作成(name, main, types を適切に設定)
  3. tsconfig.jsonを作成(extends, composite を設定)
  4. ルートのtsconfig.jsonのreferencesに追加
  5. ルートでnpm installを実行
  6. 依存する他パッケージのtsconfig.jsonのreferencesを更新

依存関係追加時の同期手順

  1. package.jsonに依存関係を追加

    npm install @my-org/utils -w @my-org/app
    
  2. tsconfig.jsonのreferencesを更新

    // packages/app/tsconfig.json
    {
      "references": [
        { "path": "../shared" },
        { "path": "../utils" }  // 追加
      ]
    }
    

重要: package.jsonでのバージョン指定について

  • npm: "*"または具体的なバージョン番号を使用
  • pnpm/yarn: "workspace:*"記法が使用可能
  • 混同しないよう注意!
  1. ビルドして確認
    npm run build
    

注意: --forceオプションにより、キャッシュを無視して全ファイルを再生成します。 npm run buildは意図的にファイルを生成したいときに使用されるため、常に最新の出力が必要です。

トラブルシューティング

ビルドキャッシュが更新されない

原因: package.jsonとtsconfig.jsonの依存関係が非同期 解決:

  1. 各パッケージのdependenciesを確認
  2. 対応するtsconfig.jsonのreferencesが存在することを確認
  3. tsc --build --cleanでキャッシュをクリア後、再ビルド

モジュールが見つからないエラー

原因: npm workspacesのシンボリックリンクが作成されていない 解決:

  1. ルートディレクトリでnpm installを実行
  2. node_modules内にシンボリックリンクが存在することを確認

型定義が参照できない

原因: composite: trueまたはdeclaration: trueが設定されていない 解決: 参照されるパッケージのtsconfig.jsonに両設定があることを確認

自動化ツール

依存関係の同期を自動化

# @monorepo-utils/workspaces-to-typescript-project-referencesを使用
npm install -D @monorepo-utils/workspaces-to-typescript-project-references

# package.jsonからtsconfig.jsonのreferencesを自動生成
npx workspaces-to-typescript-project-references

pre-commitフックに組み込むことで、常に同期を保つことができます。

まとめ

npm workspacesとTypeScript Project Referencesの連携において最も重要なのは:

  1. package.jsonを唯一の信頼できる情報源とする
  2. tsconfig.jsonのreferencesは常にpackage.jsonの依存関係を反映
  3. npm操作は必ずルートディレクトリで実行
  4. -wフラグを使って特定ワークスペースを指定

これらの原則を守ることで、安定したモノレポ環境を構築できます。

pnpm workspaces × TypeScript × Changeset設定ガイド

モノレポ環境での最適な技術スタック構成について解説しています。

技術スタックの組み合わせ

pnpm × TypeScript × Changeset

この3つの組み合わせにより、以下を実現します:

  • pnpm workspaces: 高速で効率的なパッケージ管理
  • TypeScript Project References: インクリメンタルビルドとキャッシュ最適化
  • Changeset: セマンティックバージョニングと自動リリース

なぜこの組み合わせか

1. 開発効率の向上
  • pnpmの高速インストール(npm比2-3倍)
  • TypeScriptのインクリメンタルビルド
  • Changesetによる自動バージョン管理
2. 信頼性の確保
  • pnpmの厳密な依存関係管理
  • TypeScriptの型安全性
  • Changesetによるリリース履歴の追跡
3. npm公開の安全性
  • pnpmのworkspace:*記法で内部依存を明確化
  • pnpm publish -rで依存順序を考慮した公開
  • Changesetでバージョン衝突を防止

クイックスタート

# pnpmのインストール
npm install -g pnpm

# プロジェクトの初期化
pnpm init
echo "packages:\n  - 'packages/*'" > pnpm-workspace.yaml

# TypeScriptとChangesetのセットアップ
pnpm add -D typescript @changesets/cli -w
pnpm changeset init

# 基本スクリプトの設定
npm pkg set scripts.build="tsc --build"
npm pkg set scripts.changeset="changeset"
npm pkg set scripts.version="changeset version"
npm pkg set scripts.publish="pnpm publish -r --no-git-checks"

典型的なプロジェクト構造

my-monorepo/
├── pnpm-workspace.yaml     # pnpm workspace設定
├── tsconfig.json           # TypeScript Project References
├── .changeset/
│   └── config.json        # Changeset設定
├── packages/
│   ├── common/
│   │   ├── package.json   # "name": "@my-org/common"
│   │   └── tsconfig.json
│   └── app/
│       ├── package.json   # "dependencies": {"@my-org/common": "workspace:*"}
│       └── tsconfig.json  # "references": [{"path": "../common"}]
└── package.json           # "private": true

詳細ドキュメント

  • @setup-guide.md - 基本設定と構築手順
  • @migration-guide.md - npmからpnpmへの移行ガイド
  • @publishing-guide.md - パッケージ公開とリリースフロー

よくある質問

Q: npmやyarnからの移行は難しい?

A: migration-guide.mdに段階的な移行手順があります。workspace記法の変換が主な作業です。

Q: Changesetは必須?

A: 必須ではありませんが、複数パッケージのバージョン管理が格段に楽になります。

Q: TypeScript Project Referencesの設定は複雑?

A: package.jsonの依存関係とtsconfig.jsonのreferencesを同期させるだけです。

実装例

このレシピを実際に適用したプロジェクト:

トラブルシューティングのヒント

  • npm公開が失敗: workspace:*が残っていないか確認
  • ビルドが遅い: tsconfig.jsonのreferencesが正しいか確認
  • changesetがない警告: PR作成前にpnpm changesetを実行

npmからpnpmへの移行ガイド

移行の動機

なぜpnpmを選ぶか

  • パフォーマンス: インストール速度が2-3倍高速
  • ディスク容量: 重複排除により50-70%削減
  • 信頼性: 厳密な依存関係管理で「動作するはずなのに動かない」を防止
  • モノレポ対応: workspace機能が標準搭載

移行タイミングの判断

以下の場合は移行を推奨:

  • モノレポでパッケージ間の依存関係が複雑
  • CI/CDのインストール時間を短縮したい
  • npm公開時のレースコンディションに悩んでいる
  • node_modulesのサイズが問題になっている
  • git worktreeやAIコーディングエージェントの並列実行を行う

事前準備

1. 現状の確認

# 現在の依存関係ツリーを記録
npm list --depth=0 > npm-dependencies.txt

# package-lock.jsonのバックアップ
cp package-lock.json package-lock.json.backup

# 現在のスクリプトを確認
npm run

2. pnpmのインストール

# npm経由でインストール
npm install -g pnpm

# または、スタンドアロンインストール
curl -fsSL https://get.pnpm.io/install.sh | sh -

3. バージョン選択

バージョンenableGlobalVirtualStoreNode.js要件
v10.12+opt-in(実験的)Node 18+
v11+グローバルインストールでデフォルト有効、プロジェクトはopt-inNode 22+

git worktreeやマルチエージェント開発を行う場合はenableGlobalVirtualStoreの有効化を推奨。v10.12+で利用可能。v11はNode 22+必須のため、CI環境のNode.jsバージョンと合わせて判断する。

段階的移行手順

Phase 1: 基本的な移行

1. クリーンアップ
rm -rf node_modules
rm -rf packages/*/node_modules
rm -f package-lock.json
2. pnpm-workspace.yaml作成
packages:
  - 'packages/*'

# git worktree / マルチエージェント開発向け(v10.12+)
# enableGlobalVirtualStore: true
3. 初回インストールとPhantom Dependencies検出

pnpm移行で最も頻出する問題がPhantom Dependencies(幽霊依存関係)。npmのフラットなnode_modules構造では推移的依存関係を暗黙的にimportできるが、pnpmの厳密な依存管理ではpackage.jsonに宣言されていない依存は解決できなくなる。

# まず通常インストールを試す
pnpm install

# エラーが出る場合、一時的にshamefully-hoistでインストールし検出に進む
pnpm install --shamefully-hoist

TypeScript(ESM)の検出:

tsc --noEmit --no-bail 2>&1 | grep "Cannot find module"

CommonJS形式の検出:

pnpm dlx knip --include=unlisted,unresolved

検出された依存関係は明示的に各パッケージのpackage.jsonへ追加する。shamefully-hoistは一時的な回避策であり、最終的には解消を目指す。

参考: レガシー Monorepo を安全かつ素早く pnpm workspace に移行する方法(PLAID社、13パッケージ/約500ファイルのKARTE APIモノレポ移行事例)

4. package.jsonスクリプトの更新
{
  "scripts": {
-   "install:all": "npm install",
+   "install:all": "pnpm install",
-   "build:all": "npm run build --workspaces",
+   "build:all": "pnpm run -r build",
-   "test:all": "npm test --workspaces",
+   "test:all": "pnpm run -r test"
  }
}
5. コマンドの置き換え
# postinstall
# npm: npm run build --workspace=packages/core
# pnpm: pnpm --filter @my-org/core build

# グローバルツール
# npm: npm install -g typescript
# pnpm: pnpm add -g typescript

# npx → pnpm dlx / pnpm exec
# npm: npx tsc --version
# pnpm: pnpm dlx tsc --version

Phase 2: workspace記法の変換

内部パッケージ参照の更新

変換前(npm):

{
  "dependencies": {
    "@my-org/common": "*",
    "@my-org/core": "^1.0.0"
  }
}

変換後(pnpm):

{
  "dependencies": {
    "@my-org/common": "workspace:*",
    "@my-org/core": "workspace:*"
  }
}
自動変換スクリプト
// convert-to-workspace.js
const fs = require('fs');
const path = require('path');

function convertPackageJson(filePath) {
  const pkg = JSON.parse(fs.readFileSync(filePath, 'utf8'));
  const workspacePackages = ['@my-org/common', '@my-org/core', '@my-org/app'];

  ['dependencies', 'devDependencies'].forEach(depType => {
    if (pkg[depType]) {
      workspacePackages.forEach(name => {
        if (pkg[depType][name]) {
          pkg[depType][name] = 'workspace:*';
        }
      });
    }
  });

  fs.writeFileSync(filePath, JSON.stringify(pkg, null, 2));
}

// 実行
convertPackageJson('./packages/app/package.json');

Phase 3: CI/CD環境の更新

GitHub Actions
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

+     - name: Setup pnpm
+       uses: pnpm/action-setup@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
-         node-version: '20'
-         cache: 'npm'
+         node-version: '22'
+         cache: 'pnpm'

      - name: Install dependencies
-       run: npm ci
+       run: pnpm install --frozen-lockfile

      - name: Build
-       run: npm run build
+       run: pnpm build
GitLab CI
-image: node:20
+image: node:22

+before_script:
+  - npm install -g pnpm
+  - pnpm config set store-dir .pnpm-store

cache:
  paths:
-   - node_modules/
+   - .pnpm-store/

install:
  script:
-   - npm ci
+   - pnpm install --frozen-lockfile

test:
  script:
-   - npm test
+   - pnpm test

トラブルシューティング

ピア依存関係の解決失敗

ERR_PNPM_PEER_DEP_ISSUES
# .npmrcに追加
echo "strict-peer-dependencies=false" >> .npmrc
echo "auto-install-peers=true" >> .npmrc

特定パッケージのホイスト要求

一部のツール(eslint、prettier等)がホイストされた依存に依存する場合:

# .npmrcで特定パターンのみホイスト
echo "public-hoist-pattern[]=*eslint*" >> .npmrc
echo "public-hoist-pattern[]=*prettier*" >> .npmrc

preserveSymlinksとpnpmの競合

レガシー設定でpreserveSymlinks: trueを使っている場合、pnpmのシンボリックリンクベースのnode_modules構造と競合する。

  • preserveSymlinksをfalseに変更
  • CommonJSをimportしているパッケージがある場合はvite-plugin-commonjs等で対処

pnpm --filterの静かな失敗

pnpm --filterでパターンがマッチしない場合、デフォルトではエラーにならず静かに成功する。CIで意図しないスキップが発生する原因になる。

pnpm --filter "@my-org/app" --fail-if-no-match build

Changesetとの統合問題

Error: You cannot publish over the previously published versions

Changesetの並列公開とnpmのレースコンディション。pnpmの順序公開で解決:

{
  "scripts": {
    "changeset:publish": "pnpm publish -r --no-git-checks"
  }
}

Docker環境での問題

FROM node:22
RUN npm install -g pnpm
COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
COPY packages/*/package.json ./packages/
RUN pnpm install --frozen-lockfile --prod

enableGlobalVirtualStoreの活用

git worktreeやAIコーディングエージェントの並列実行環境では、enableGlobalVirtualStoreの有効化を推奨。同一の依存ツリーを持つworktree間でnode_modulesを共有し、2つ目以降のworktreeではシンボリックリンク作成のみでpnpm installが完了する。

# pnpm-workspace.yaml
enableGlobalVirtualStore: true

パフォーマンス比較

インストール時間

# npm
time npm ci          # real 2m30s

# pnpm
time pnpm install --frozen-lockfile  # real 0m45s

ディスク使用量

# npm
du -sh node_modules  # 850M

# pnpm
du -sh node_modules  # 320M

ロールバック手順

# 1. pnpm関連ファイルを削除
rm -f pnpm-lock.yaml
rm -f pnpm-workspace.yaml
rm -rf node_modules

# 2. workspace:*記法を元に戻す(package.jsonを手動で編集)

# 3. package-lock.jsonを復元
cp package-lock.json.backup package-lock.json

# 4. npmで再インストール
npm ci

移行チェックリスト

必須

  • pnpm-workspace.yamlを作成
  • Phantom Dependenciesを検出・解消
  • workspace:*記法に変換
  • package.jsonのスクリプトを更新
  • CI/CDワークフローを更新
  • .gitignoreにpnpm-lock.yamlが含まれていないことを確認
  • READMEのインストール手順を更新

推奨

  • .npmrcを設定(ピア依存関係、ホイストパターン)
  • enableGlobalVirtualStoreの有効化を検討
  • --fail-if-no-matchをCIスクリプトに追加
  • チーム全体への周知

検証

  • pnpm installが成功
  • pnpm buildが成功
  • pnpm testが成功
  • CI/CDパイプラインが成功
  • npm公開が成功(該当する場合)

pnpmによるパッケージ公開とリリースフロー

なぜpnpmが公開に適しているか

npmの問題点

  • レースコンディション: 並列公開時に依存関係の解決に失敗
  • 公開順序の制御困難: 依存パッケージが先に公開される保証がない
  • バージョン衝突: "You cannot publish over the previously published versions"エラー

pnpmの解決策

  • 依存順序での公開: pnpm publish -rで自動的に依存順序を解決
  • *workspace:の自動変換: 公開時に実際のバージョンに変換
  • トランザクション的な公開: 失敗時のロールバック可能

基本的な公開設定

package.jsonの必須フィールド

{
  "name": "@my-org/package",
  "version": "1.0.0",
  "description": "Package description",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc --build",
    "prepublishOnly": "pnpm build"
  },
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  }
}

重要なポイント:

  • files: 公開するファイルを明示的に指定
  • prepublishOnly: 公開前のビルドを保証
  • publishConfig: スコープ付きパッケージの公開設定

.npmignoreは使わない

# ❌ 非推奨
echo "src/" >> .npmignore
echo "tests/" >> .npmignore

# ✅ 推奨: package.jsonのfilesフィールドを使用

Changesetによるバージョン管理

Changesetの初期設定

# changesetのインストール
pnpm add -D @changesets/cli -w

# 初期化
pnpm changeset init

.changeset/config.json

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": [],
  "privatePackages": {
    "version": true,
    "tag": false
  }
}

Changesetワークフロー

# 1. 変更後にchangesetを作成
pnpm changeset

# 2. 対話形式で変更内容を記録
# - 変更したパッケージを選択
# - major/minor/patchを選択
# - 変更内容の説明を入力

# 3. changesetファイルがコミット対象に追加される
git add .changeset/xxx.md
git commit -m "feat: add new feature"

# 4. リリース時にバージョン更新
pnpm changeset version

# 5. 公開
pnpm publish -r --no-git-checks

リリースフローの設計

推奨フロー: release/*ブランチ戦略

graph LR
    A[main] --> B[feature/*]
    B --> C[PR to main]
    C --> D[main + changeset]
    D --> E[release/*]
    E --> F[Version Update]
    F --> G[PR to main]
    G --> H[Merge = npm publish]

GitHub Actionsワークフロー

1. 開発フロー(changeset-check.yml)
name: Changeset Check

on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Check for changeset
        run: |
          if [[ "${{ github.head_ref }}" != release/* ]]; then
            pnpm changeset status
          fi
2. リリースPR作成(changeset-version.yml)
name: Create Release PR

on:
  push:
    branches: [main]

jobs:
  release-pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Create Release PR
        uses: changesets/action@v1
        with:
          # publishを指定しない(mainマージで公開しない)
          version: pnpm changeset version
          commit: 'chore: version packages'
          title: '🚀 Release packages'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3. 自動公開(release-publish.yml)
name: Auto Publish

on:
  pull_request:
    types: [closed]
    branches: [main]

jobs:
  publish:
    if: |
      github.event.pull_request.merged == true &&
      startsWith(github.event.pull_request.head.ref, 'release/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build packages
        run: pnpm build:all

      - name: Publish to npm
        run: pnpm publish -r --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

公開時のトラブルシューティング

問題1: workspace:*エラー

npm ERR! Invalid version: "workspace:*"

原因: npmコマンドで直接公開しようとした

解決:

# ❌ 間違い
npm publish

# ✅ 正解
pnpm publish

問題2: 依存パッケージが見つからない

npm ERR! 404 Not Found - @my-org/common@1.0.0

原因: 依存パッケージが先に公開されていない

解決:

# 依存順序で公開
pnpm publish -r

# または個別に順番に公開
pnpm publish --filter @my-org/common
pnpm publish --filter @my-org/app

問題3: distディレクトリが含まれない

npm ERR! package.json main field points to missing file

原因: filesフィールドの設定漏れ、またはビルド忘れ

解決:

{
  "files": ["dist"],
  "scripts": {
    "prepublishOnly": "pnpm build"
  }
}

問題4: バージョン衝突

npm ERR! 403 Forbidden - You cannot publish over the previously published versions

原因: 同じバージョンが既に公開されている

解決:

# changesetでバージョンを上げる
pnpm changeset version

# または手動でバージョンを上げる
pnpm version patch --filter @my-org/package

問題5: 認証エラー

npm ERR! 401 Unauthorized

解決:

# npmにログイン
npm login

# またはトークンを設定
npm set //registry.npmjs.org/:_authToken ${NPM_TOKEN}

プライベートレジストリへの公開

設定方法

# .npmrcに追加
echo "@my-company:registry=https://npm.my-company.com" >> .npmrc
echo "//npm.my-company.com/:_authToken=${PRIVATE_NPM_TOKEN}" >> .npmrc

package.jsonの設定

{
  "publishConfig": {
    "registry": "https://npm.my-company.com"
  }
}

セキュリティベストプラクティス

1. 2要素認証の設定

# npmアカウントで2FAを有効化
npm profile enable-2fa auth-and-writes

2. 公開前のドライラン

# 実際に公開せずに確認
pnpm publish --dry-run --filter @my-org/package

# tarballの内容を確認
pnpm pack --filter @my-org/package
tar -tzf my-org-package-1.0.0.tgz

3. スコープ付きパッケージの保護

{
  "name": "@my-org/package",
  "publishConfig": {
    "access": "public"  // または "restricted"
  }
}

4. 自動化されたセキュリティチェック

# CI/CDでのチェック
- name: Audit dependencies
  run: pnpm audit

- name: Check for secrets
  run: |
    if grep -r "password\|secret\|token" dist/; then
      echo "Potential secrets found!"
      exit 1
    fi

公開後の確認

パッケージの検証

# 公開されたパッケージの確認
npm view @my-org/package

# 最新バージョンの確認
npm view @my-org/package version

# ダウンロードして動作確認
cd /tmp
npm init -y
npm install @my-org/package
node -e "console.log(require('@my-org/package'))"

問題が発生した場合

# 72時間以内なら取り消し可能
npm unpublish @my-org/package@1.0.0

# deprecatedにする(推奨)
npm deprecate @my-org/package@1.0.0 "Critical bug found, use 1.0.1"

チームでの運用

ブランチ保護ルール

# GitHub Branch Protection
- Require pull request reviews
- Require status checks (CI/CD)
- Require branches to be up to date
- Include administrators
- Restrict who can push to release/*

リリース承認フロー

  1. 開発者: changesetを作成してPR
  2. レビュアー: コードレビューと承認
  3. メンテナー: release/*ブランチを作成
  4. 自動化: バージョン更新PR作成
  5. メンテナー: 最終確認とマージ
  6. 自動化: npm公開

まとめ

pnpmによるパッケージ公開の重要ポイント:

  1. 依存順序の自動解決: pnpm publish -rで安全に公開
  2. *workspace:の活用: 内部依存を明確に管理
  3. prepublishOnlyフック: ビルド忘れを防止
  4. *release/ブランチ戦略: 意図的な公開のみを許可
  5. Changesetとの統合: バージョン管理を自動化

これらの設定により、安全で確実なパッケージ公開が実現できます。

pnpm workspacesとTypeScript Project References設定ガイド

概要

このガイドは、pnpm workspacesとTypeScript Project Referencesを正しく連携させ、モノレポ環境でビルドキャッシュが適切に機能するための設定方法を解説します。

pnpm vs npm workspacesの主な違い

利点

  • 厳密な依存関係管理: シンボリックリンクによる効率的な管理
  • ディスク容量の節約: 重複パッケージの排除
  • 高速なインストール: 並列処理とキャッシュの最適化
  • *workspace:記法のサポート: より明確な内部パッケージ参照
  • 依存順序を考慮した公開: pnpm publish -rで依存関係順に公開

注意点

  • 厳密なピア依存関係チェック: 解決できないピア依存関係でエラー
  • Node.jsモジュール解決の厳格性: 宣言されていない依存関係へのアクセス不可

設定手順

1. ルートレベルの設定

pnpm-workspace.yaml(必須)
packages:
  - 'packages/*'

重要: このファイルがないとpnpm workspacesは機能しません。

package.json(ルート)
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "tsc --build",
    "build:all": "pnpm run -r build",
    "clean": "tsc --build --clean",
    "test": "pnpm run -r test",
    "lint": "pnpm run -r lint"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "@changesets/cli": "^2.27.0"
  }
}

pnpm特有のポイント:

  • workspacesフィールドは不要(pnpm-workspace.yamlを使用)
  • -rフラグで全ワークスペースでコマンド実行
  • --filterで特定パッケージを対象に実行可能
tsconfig.base.json(ルート)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,

    // Project References用の必須設定
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "incremental": true
  }
}
tsconfig.json(ルート)
{
  "files": [],
  "include": [],
  "references": [
    { "path": "packages/common" },
    { "path": "packages/core" },
    { "path": "packages/app" }
  ]
}

2. パッケージレベルの設定

ライブラリパッケージ(packages/common)

package.json

{
  "name": "@my-org/common",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsc --build",
    "prepublishOnly": "pnpm build"
  }
}

pnpm特有の追加:

  • filesフィールドで公開するファイルを明示
  • prepublishOnlyでビルドを保証

tsconfig.json

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*"],
  "references": []
}
アプリケーションパッケージ(packages/app)

package.json

{
  "name": "@my-org/app",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "dependencies": {
    "@my-org/common": "workspace:*",
    "@my-org/core": "workspace:*"
  },
  "scripts": {
    "build": "tsc --build",
    "start": "node dist/index.js"
  }
}

pnpmのworkspace:*記法:

  • 内部パッケージへの明確な参照
  • 公開時に実際のバージョン番号に自動変換
  • npm/yarnとの相互運用性を保証

tsconfig.json

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../common" },
    { "path": "../core" }
  ]
}

重要な運用ルール

インストールとビルド

# 依存関係のインストール(ルートで実行)
pnpm install

# 開発依存関係を除外してインストール
pnpm install --prod

# ロックファイルから厳密にインストール(CI用)
pnpm install --frozen-lockfile

# 全パッケージのビルド
pnpm build:all

# 特定パッケージのビルド
pnpm --filter @my-org/app build

依存関係の管理

# 特定パッケージに依存関係を追加
pnpm add express --filter @my-org/app

# 内部パッケージの依存関係を追加
pnpm add @my-org/common --filter @my-org/app --workspace

# ルートにdevDependenciesを追加
pnpm add -D eslint -w

# 全パッケージの依存関係を更新
pnpm update -r

パッケージ公開

# changesetの作成
pnpm changeset

# バージョン更新
pnpm changeset version

# 依存順序を考慮した公開
pnpm publish -r --no-git-checks

CI/CD設定

GitHub Actions設定例

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build packages
        run: pnpm build:all

      - name: Run tests
        run: pnpm test

トラブルシューティング

よくある問題と解決方法

1. peer dependenciesエラー

問題:

 ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

解決:

# .npmrcに追加
echo "auto-install-peers=true" >> .npmrc

# または明示的にインストール
pnpm add react --filter @my-org/app
2. workspace:*が解決されない

問題:

Cannot find module '@my-org/common'

解決:

  1. pnpm-workspace.yamlが存在することを確認
  2. ルートでpnpm installを実行
  3. node_modules/.pnpmにシンボリックリンクが作成されているか確認
3. ビルドキャッシュが効かない

問題: TypeScriptが毎回全ファイルを再コンパイル

解決:

# キャッシュをクリア
pnpm exec tsc --build --clean

# tsconfig.jsonの依存関係を確認
# package.jsonとtsconfig.jsonのreferencesが一致しているか確認
4. CI環境でのインストール失敗

問題:

ENOENT: no such file or directory, open 'pnpm-lock.yaml'

解決:

  • pnpm-lock.yamlをgitignoreしない
  • --frozen-lockfileフラグを使用
5. npm公開時のworkspace:*エラー

問題:

npm ERR! Invalid version: "workspace:*"

解決: pnpm publishを使用(自動的にバージョンに変換される)

移行時の注意点

npmからの移行
# 1. 既存のnode_modulesとpackage-lock.jsonを削除
rm -rf node_modules package-lock.json
rm -rf packages/*/node_modules

# 2. pnpm-workspace.yamlを作成
echo "packages:\n  - 'packages/*'" > pnpm-workspace.yaml

# 3. workspace:*記法に変換
# package.jsonで "^1.0.0" → "workspace:*" に変更

# 4. pnpmでインストール
pnpm install

# 5. .gitignoreを更新
echo "pnpm-lock.yaml" >> .gitignore  # 削除(コミットする)
CI/CDワークフローの更新
  • npm ci → pnpm install --frozen-lockfile
  • npm run → pnpm run
  • npm install -g → pnpm add -g
  • キャッシュキーをpackage-lock.json → pnpm-lock.yamlに変更

ベストプラクティス

1. ルートpackage.jsonの整理

{
  "private": true,
  "scripts": {
    "build": "tsc --build",
    "build:all": "pnpm run -r build",
    "test": "pnpm run -r test",
    "lint": "pnpm run -r lint",
    "changeset": "changeset",
    "changeset:version": "changeset version",
    "changeset:publish": "pnpm publish -r --no-git-checks"
  },
  "devDependencies": {
    // 全パッケージ共通の開発ツールのみ
  }
}

2. パッケージレベルのスクリプト

{
  "scripts": {
    "build": "tsc --build",
    "test": "vitest",
    "lint": "eslint src",
    "prepublishOnly": "pnpm build"
  }
}

3. 依存関係の階層化

  • ルート: 開発ツール(TypeScript, ESLint, Vitest等)
  • パッケージ: 実行時依存関係のみ
  • workspace:*で内部依存関係を明示

4. .npmrcの設定

# pnpm特有の設定
shamefully-hoist=false
auto-install-peers=true
strict-peer-dependencies=false

# パフォーマンス設定
package-import-method=copy
prefer-frozen-lockfile=true

Vitest設定に関する注意事項

import.meta.resolve()の使用について

Vitestでimport.meta.resolve()を使用する場合、バージョン要件があります。

はい、バージョンによって解決されています。

以前のバージョンではimport.meta.resolve()はサポートされていませんでしたが、Vitest 1.0以降(より正確には、基盤となるVite 5.0以降)では、Node.jsのバージョンが適切であれば利用可能です。

現在(2025年10月)の最新版のVitest v2.xとVite v7.xをお使いであれば、import.meta.resolve()は期待通り動作します。

状況の経緯
  1. 以前の状況 (Vite 4 / Vitest 0.x): import.meta.resolve()はNode.jsの比較的新しい(v18.19+ / v20.6+で安定化)機能です。Vitestが内部で使用するvite-nodeが、この機能に完全には対応していませんでした。そのため、import.meta.resolve is not a functionといったエラーが発生していました。

  2. 現在の状況 (Vite 5+ / Vitest 1.0以降):

    • Vite 5.0(およびVitest 1.0)へのメジャーアップデートに伴い、Node.js v18.18.0以上が必須となりました。
    • このアップデートとvite-nodeの改善により、Node.jsがネイティブでサポートするimport.meta.resolve()がVitestの実行環境でも正しく動作するようになりました。
必須要件

Vitestでimport.meta.resolve()を使用するには、以下の2つの条件を満たす必要があります:

  1. Vitestのバージョン: v1.0.0 以上(2025年10月時点の最新: v2.x)
  2. Node.jsのバージョン: v18.19.0 または v20.6.0 以上(import.meta.resolveが安定化されたバージョン)

これらの最新の環境であれば、import.meta.resolve()は期待通り動作します。

もし現在古いバージョンをお使いの場合は、VitestおよびNode.jsのアップデートをご検討ください。

まとめ

pnpm workspacesとTypeScript Project Referencesの連携において重要なポイント:

  1. pnpm-workspace.yamlが必須
  2. *workspace:記法で内部パッケージを明確に参照
  3. pnpm publish -rで依存順序を考慮した公開
  4. --frozen-lockfileでCI環境での再現性を保証
  5. prepublishOnlyスクリプトでビルドを保証

これらの設定により、高速で信頼性の高いモノレポ環境を構築できます。

プロジェクトにSerenaを導入するレシピ

目的

コードベースの解析・編集ツールSerenaをプロジェクトに導入し、Claude Codeでの開発効率を大幅に向上させる

前提条件

  • Claude Code (Claude Desktop)がインストール済み
  • uv (Python package manager)がインストール済み
  • プロジェクトがGit管理されている(推奨)
  • Git(ローカルクローン版を使用する場合)

手順

1. 初期設定(全プロジェクト共通・初回のみ)

1.1 グローバル設定ファイルの作成・編集
# 設定ファイルを作成(初回実行時に自動生成される)
uv run serena config edit
1.2 ブラウザ自動起動の無効化(任意)

~/.serena/serena_config.yml を編集:

# ダッシュボード機能は有効のまま、ブラウザ自動起動のみ無効化
web_dashboard: true                  # ダッシュボード機能自体(有効推奨)
web_dashboard_open_on_launch: false  # 起動時の自動ブラウザ起動(無効推奨)

メモ: ダッシュボードは http://localhost:24282/dashboard/index.html で手動アクセス可能

2. プロジェクトへの導入

2.1 プロジェクトディレクトリへ移動
cd /path/to/your/project
2.2 Claude Codeへの統合

方法A: リモートリポジトリから直接実行(簡単)

# IDEアシスタントコンテキストで、現在のプロジェクトを自動アクティベート
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context ide-assistant \
  --project $(pwd) \
  --enable-web-dashboard true \
  --enable-web-dashboard-open-on-launch false

方法B: ローカルにクローンしたSerenaを使用(推奨・高速)

# 1. Serenaをローカルにクローン(初回のみ)
git clone https://github.com/oraios/serena ~/tools/serena

# 2. Claude Codeに追加(クローンしたディレクトリを指定)
claude mcp add serena -- uv run --directory ~/tools/serena \
  serena start-mcp-server \
  --context ide-assistant \
  --project $(pwd) \
  --enable-web-dashboard true \
  --enable-web-dashboard-open-on-launch false

メリット:

  • 方法A: セットアップが簡単、常に最新版
  • 方法B: 起動が高速、オフラインでも使用可能、カスタマイズ可能

オプション説明:

  • --context ide-assistant: Claude Code用に最適化された設定
  • --project $(pwd): 現在のディレクトリを自動アクティベート(毎回の手動アクティベート不要)
  • --enable-web-dashboard-open-on-launch false: ブラウザ自動起動を無効化
2.3 大規模プロジェクトの場合(推奨)
# プロジェクトのインデックスを作成(初回の処理速度が大幅に向上)
uvx --from git+https://github.com/oraios/serena serena project index

3. プロジェクト固有の設定(任意)

3.1 プロジェクト設定ファイルの確認・編集

.serena/project.yml が自動生成されます。必要に応じて編集:

# 言語設定(自動検出されるが、必要なら変更)
language: typescript  # python, go, rust, java, php, ruby等

# プロジェクト名(アクティベート時に使用)
project_name: "my-awesome-project"

# 除外設定
ignore_all_files_in_gitignore: true  # .gitignoreを尊重
ignored_paths:                        # 追加の除外パス
  - "build/"
  - "dist/"
  - "*.generated.ts"

# セキュリティ設定
read_only: false  # true にすると読み取り専用モード

# プロジェクト固有の初期プロンプト(任意)
initial_prompt: |
  このプロジェクトは〇〇システムです。
  主要な技術スタック: React, TypeScript, Node.js
  コーディング規約: ESLint設定に従う

3.5 ローカルSerenaの更新(方法Bを使用している場合)

# Serenaの更新
cd ~/tools/serena
git pull origin main

4. 使用方法

4.1 基本的な使い方

Claude Codeで以下のように指示:

  • 「このファイルの〇〇関数を修正して」
  • 「〇〇クラスの使用箇所を全て確認」
  • 「型定義を追加して」
4.2 手動アクティベート(--projectオプション未使用の場合)
# 初回
"Activate the project /path/to/project"

# 2回目以降(プロジェクト名で指定可能)
"Activate the project my-awesome-project"
4.3 ダッシュボードへのアクセス

ブラウザで以下にアクセス:

  • http://localhost:24282/dashboard/index.html
  • 複数インスタンス起動時: ポート24283, 24284...

期待する成果

  • トークン効率の大幅改善: ファイル全体を読む必要がなくなる
  • 精度の向上: シンボル単位での正確な編集
  • 処理速度の向上: インデックスによる高速検索
  • IDE相当の機能: リファレンス検索、シンボル検索等

注意点・制約

セッション管理

  • 新しいClaude Codeセッションでは再度MCPサーバーが起動される
  • --projectオプション使用時は自動アクティベートされる
  • コンテキスト圧縮後も設定は維持される

パフォーマンス

  • 初回実行時は言語サーバーの起動に時間がかかる場合がある
  • 大規模プロジェクトではインデックス作成を強く推奨
  • node_modules等は自動的に除外される

トラブルシューティング

  • ダッシュボードが開かない: 手動で http://localhost:24282/dashboard/index.html にアクセス
  • プロジェクトが認識されない: .serena/project.yml の存在を確認
  • 処理が遅い: serena project index を実行
  • 複数インスタンス: ダッシュボードでプロセス管理可能

高度な設定

複数プロジェクトの管理

~/.serena/serena_config.yml に自動登録される:

projects:
  - /path/to/project1
  - /path/to/project2
  - /path/to/project3

カスタムコンテキスト・モード

# カスタムコンテキストやモードを指定
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context custom-context.yaml \
  --mode interactive,editing

Docker経由での実行(実験的)

docker run --rm -i --network host \
  -v /path/to/projects:/workspaces/projects \
  ghcr.io/oraios/serena:latest \
  serena start-mcp-server --transport stdio

関連レシピ


作成日: 2025年10月22日 作成者: Claude Code Assistant バージョン: 1.0.0

参考資料:

テストの分類と基本方針

テストの分類定義

1. ユニットテスト (Unit Tests)

定義: 単一のモジュール、クラス、関数の振る舞いを検証するテスト

特徴:

  • 外部依存はすべてモック化
  • 高速実行(ミリ秒単位)
  • 内部実装の詳細をテスト
  • ホワイトボックステスト

配置例:

  • src/**/*.test.ts
  • src/**/*.spec.ts
  • テスト対象と同じディレクトリに配置

対象例:

  • 純粋関数の入出力検証
  • クラスの個別メソッド
  • 状態管理ロジック
  • バリデーション処理

2. インターフェーステスト (Interface Tests)

定義: モジュールの公開インターフェース仕様を検証するテスト

特徴:

  • モジュールの公開API(exports)のみをテスト
  • 内部実装には依存しない
  • インターフェース契約の遵守を保証
  • ブラックボックステスト

配置例:

  • test/interface/**/*.test.ts
  • tests/api/**/*.test.ts

対象例:

  • 公開メソッドの仕様確認
  • APIエンドポイントの契約
  • パッケージのexportsが期待通りの型と動作を提供することの確認

3. 統合テスト (Integration Tests)

定義: 複数のモジュール間の相互作用を検証するテスト

特徴:

  • 実際のモジュール間連携を確認
  • 一部の外部システム(DB等)はモック可
  • システムの部分的な結合をテスト
  • 中速実行(100ms-1s/test)

配置例:

  • test/integration/**/*.test.ts
  • tests/integration/**/*.test.ts

対象例:

  • モジュール間のデータフロー
  • イベント駆動型処理の連鎖
  • サービス間の通信
  • トランザクション処理

4. システムテスト (System Tests)

定義: 実際の外部システムと接続して動作を検証するテスト

特徴:

  • 実際のDB、外部API等を使用
  • 環境依存(Docker、実DBが必要)
  • 実際の子プロセス起動を含む
  • 中速実行(1-5s/test)

配置例:

  • test/system/**/*.test.ts
  • DB固有: db/test/system/**/*.test.ts

対象例:

  • 実DBへのCRUD操作
  • 外部プロセスとの通信
  • ファイルシステム操作
  • ネットワーク通信

5. E2Eテスト (End-to-End Tests)

定義: ユーザー視点でシステム全体の動作を検証するテスト

特徴:

  • システム全体を起動
  • 実際のユーザーシナリオを再現
  • 最も現実に近い環境
  • 低速実行(5s以上/test)

配置例:

  • test/e2e/**/*.test.ts
  • e2e/**/*.test.ts

対象例:

  • 完全なユーザーフロー
  • APIからUIまでの一連の操作
  • 複数システムの連携シナリオ

テスト実行戦略

実行コマンドの構成

# ユニットテスト
npm test                    # 全パッケージのユニットテスト(高速)
npm run test:unit           # 明示的にユニットテストのみ

# インターフェーステスト
npm run test:interface      # 全インターフェーステスト

# 統合テスト
npm run test:integration    # 統合テスト実行

# システムテスト(要Docker/実環境)
npm run test:system         # システムテスト実行

# E2Eテスト(要完全環境)
npm run test:e2e           # E2Eテスト実行

# 組み合わせ実行
npm run test:ci            # CI用(ユニット+統合)
npm run test:all           # 全テスト段階実行

CI/CDでの実行順序

  1. ユニットテスト - 最速、常に実行
  2. インターフェーステスト - 高速、常に実行
  3. 統合テスト - 中速、PR時実行
  4. システムテスト - 低速、マージ前実行
  5. E2Eテスト - 最遅、リリース前実行

共通セットアップパターン

グローバルセットアップ(統合・システムテスト用)

// test/setup/global.ts
let globalResources: GlobalResources;

export async function setupTestEnvironment() {
  if (!globalResources) {
    globalResources = await initializeResources();
  }
  return globalResources;
}

export async function teardownTestEnvironment() {
  if (globalResources) {
    await globalResources.cleanup();
  }
}

テストヘルパー

// test/helpers/test-utils.ts
export function createTestContext() {
  return {
    // 共通のテストユーティリティ
  };
}

export async function waitForCondition(
  condition: () => boolean,
  timeout = 5000
) {
  // 条件待機ユーティリティ
}

テスト実装の指針

新機能開発時

  1. インターフェーステストで仕様を定義
  2. ユニットテストで内部実装を保証
  3. 統合テストで他モジュールとの連携確認

バグ修正時

  1. バグを再現するテストを先に書く
  2. 該当レベルのテストで修正を確認
  3. リグレッションテストとして保持

リファクタリング時

  1. インターフェーステストが通ることを確認
  2. 内部実装(ユニットテスト)は必要に応じて更新
  3. パフォーマンステストで改善を確認

モックの使用方針

原則

  • 最小限のモック: 必要最小限に留める
  • 実装より振る舞い: 実装詳細ではなく振る舞いをモック
  • 明示的な依存関係: モックする理由を明確に

モック対象の判断基準

  • モックすべき: 外部API、ファイルシステム、時間、乱数
  • モックを避ける: ビジネスロジック、データ変換、純粋関数
  • 状況による: DB(テストレベルによる)、ログ出力

テストの品質指標

カバレッジ目標

  • ユニットテスト: 80%以上
  • 統合テスト: 主要フロー100%
  • E2Eテスト: クリティカルパス100%

テストの独立性

  • 各テストは他のテストに依存しない
  • 並行実行可能
  • 実行順序に依存しない

アサーションの品質

  • 明確な期待値
  • 適切なエラーメッセージ
  • 境界値のテスト

パフォーマンス考慮事項

テスト高速化

  • 並列実行の活用
  • 共有リソースの再利用
  • 不要な待機時間の削減

リソース管理

  • テスト後のクリーンアップ徹底
  • メモリリークの防止
  • ファイルディスクリプタの適切な管理

作成日: 2025年1月 用途: 汎用的なテスト戦略テンプレート

Sponsors

Details

Marketplace
otolab/ai-agent-prompts
Source
recipes
Category
Community
Keywords
patterns, best-practices, development

More from otolab/ai-agent-prompts

All 5