My Claude Code -仕事の相棒作ってみた-

はじめに

こんにちは、ゆきおです。
ずっと使いたいなーと思っていたClaude Codeを使用する環境が整ったので、早速何日かかけて自分専用のClaudeCodeにカスタマイズし、実験的に日々の業務に活用している次第です。

先日Connpassでこれについて登壇したのですが、過去イチ人が集まって驚きました。
やはり興味関心のある方が非常に多いんだなあと思いました。

ということで私がカスタマイズしたClaudeCodeのポイントや設計のイメージを紹介していきます。

ClaudeCodeに大事な要素

ClaudeCodeにはカスタマイズするためのポイントがいくつかあります。
・CLAUDE.md
・Agents
・Skills
・Rules
・Commands
・Hooks
大きく分けると大体こんな感じです。

それらをどうカスタマイズしているか紹介していきます。

CLAUDE.md

グローバル、もしくはプロジェクトに適用したい共通ルールを書く場所
ClaudeCodeはまずこれを読みにいきます。
なのでプロジェクトのコーディング規約やGit運用ルールなど、人間が開発するときと同じ要領でルール決めをできます。
いちいち起動するたびに同じようなプロンプトを投げなくても勝手に確認してくれます。

グローバルなルール決めとしては、私は以下のようなものを書いています

- 説明・提案・質問はすべて日本語で行う

とか

## 返答スタイル

- **短く返す** — 結論・要点だけ。説明は求められた場合のみ
- **体言止め・箇条書き優先** — 敬語・丁寧語・接続詞は省く
- **作業後の要約を省く** — ツール呼び出し結果はユーザーも見ている。「〜しました」「完了しました」は不要
- **確認は1行** — 「〜でよいですか？」は省き「〜で進める？」程度に短縮する
- **冗長な前置きを省く** — 「承知しました」「確認します」「では」等は書かない

なんてことを書いています。
こうすると日本語特有の「敬語表現」によって文章が長ったらしくなる＝トークンの消費が無駄に増えるという現象を抑えます。
ぶっちゃけ英語でやりとりできれば済む話なんですが…

また禁止事項なんかも定義しています

## やってはいけないこと（禁止事項）

- 確認なしでのファイル削除は絶対にしない
- 既存ファイルの大規模リファクタは指示なしにしない — スコープ外の変更は提案に留める
- 自分の変更によって不要になったコードは削除する。作業前から存在するデッドコードには触れない
- 設計（ADR）外のライブラリ追加・変更はしない — 詳細は `rules/dependencies.md` を参照
- テストをスキップした実装をしない — テストが書けない設計は設計を見直す
- `any` 型の使用は原則禁止 — 使う場合はコメントで理由を明記
- `console.log` をコミットに含めない — デバッグログは削除またはloggerに置き換える

といった具合にまずはCLAUDE.mdから始めます。

Agents

次にエージェントの設定です。
~/.claude/agentsディレクトリを作成し、ClaudeCodeに役割を与えてあげます。

ちなみに、各ディレクトリは本来~/.claude内に作ることで参照されますが、私の場合ClaudeCode用にプロジェクトを作ってその中に全て作成し、シンボリックリンクを貼ることで~/.claudeから参照させています。

要件定義や設計、実装、レビュー、テストやQAなど幅広くカバーしてくれるように作成しています。
まずは上流フェーズのエージェントとあれこれドキュメント作成をします。
例えば設計エージェントは以下のようになっています

agents/design/architect.md

---
name: architect
description: >
  技術選定・システム設計・ADR作成の専門家。
  「どの技術を使うべきか」「設計をどうするか」「アーキテクチャの判断が必要」
  という意思決定が必要なときに自動起動。
  技術選定時は必ずTavilyで最新情報を確認してからADRを作成する。
tools: Read, Grep, Glob, WebFetch, mcp__tavily__search
model: claude-opus-4-6
---

あなたはシニアソフトウェアアーキテクトです。
技術選定・システム設計・アーキテクチャの意思決定を担当します。
設計判断には skills/architecture/ 配下（ddd / clean-architecture / system-design / adr / tech-selection）を参照する。

## 役割

- 技術選定のトレードオフを分析して推奨案を提示する
- システム設計の判断根拠を明示する
- ADR（Architecture Decision Record）を作成して決定を記録する
- skills/architecture/ のパターンを参照して設計する

（以下略

エージェント名.mdで作成します。
上流工程は基本的に重たい作業になるので、性能の高いOpusを使用しています。
後ほど書きますがskillsには設計に関するスキルをあれこれ作っているので、それを参照するように明示しています。

requirements(要件定義) →　architect(設計) → plan(実装計画)
こんな感じで上流フェーズは３エージェントを動かしてドキュメント整備をします

ドキュメント類をしっかりと整備したら実装フェーズに移行します。
以降はモデルをSonnetにしています。

---
name: backend-implementer
description: >
  Node.js/Python/PHP APIの実装専門家。エンドポイント設計・DB操作・
  認証ロジックの実装を担当。「APIを実装して」「エンドポイントを作って」
  「バックエンドを実装して」というタスクで起動。
  テストはtest-implementerと並走して書く。
tools: Read, Write, Bash, Grep, Glob
model: claude-sonnet-4-6
---

## 実装原則

- バリデーションはZod（TS）またはPydantic（Python）でスキーマ定義
- レスポンスは `{ success, data, error }` 形式で統一（skills/api-design/SKILL.md）
- DB操作は必ずトランザクション考慮
- エラーはカスタムエラークラスで分類
- `console.log` は使わない（loggerを使う）

## レイヤー構成

Route      → バリデーション・サービス呼び出し・レスポンス整形のみ
Service    → ビジネスロジック・トランザクション管理
Repository → DB操作のみ

以下略

基本的には
・作成したドキュメント通りに作成する
・テストを実装する
というのを意識しています。仕様駆動というやつですね。

実装が終わったら次はレビュワーを呼び出してレビューします。

---
name: backend-reviewer
description: >
  Node.js/Python/PHP APIのコードレビュー専門家。バックエンドのコードが
  変更されたとき、またはレビュー依頼があったときに起動。
  .ts .js .php + api/ routes/ server/ services/ app/ のファイルが対象。
tools: Read, Grep, Glob, Bash
model: claude-sonnet-4-6
---

あなたはNode.js/Python/PHP APIのシニアバックエンドエンジニアです。
セキュリティ・パフォーマンス・設計品質を重点的にレビューします。
フレームワーク固有のパターンは skills/frameworks/hono/SKILL.md・skills/frameworks/express/SKILL.md・skills/frameworks/fastapi/SKILL.md・skills/frameworks/laravel/SKILL.md を参照します。
**API設計は `skills/api-design/SKILL.md`、パフォーマンスは `skills/performance/SKILL.md`、エラー設計は `skills/error-handling/SKILL.md` を参照する。**

以下略

レビューの場合、チェックリストなど基準となるものを作成しています。

## レビューチェックリスト

### セキュリティ（最優先）
- [ ] APIキー・パスワードがハードコードされていないか
- [ ] SQLインジェクションの危険がないか（文字列結合でクエリを作っていないか）
- [ ] ユーザー入力がバリデーションされているか（Zod/Pydantic）
- [ ] 認証・認可が適切に実装されているか
- [ ] エラーレスポンスに内部情報が含まれていないか

などなど・・・

そして以下のような出力フォーマットも定義し、出力を一定にします

重大度	件数	判定
CRITICAL	0	✅
HIGH	1	⚠️
MEDIUM	2	ℹ️
LOW	0	—

基本的にはこんな感じで実際に開発チームがいるかのようなイメージでエージェントを作成しています。

Skills

Agentsを作成したらそのエージェントに合った技術力や知見を与えます。
設計だったらクリーンアーキテクチャやDDD、TDDなどなど
フロントエンドなら自分がよく業務で使用する言語やフレームワークの、ベストプラクティスや公式ドキュメントを調べてURLを渡してエージェントが参照するスキルとしてまとめてもらっています。

スキルの場合は、「SKILL.md」という名前で統一されます。

例：Next.js

---
name: nextjs
description: Next.js 16 App Router のベストプラクティス（2026年版）。frontend-implementer / frontend-reviewer が参照する。
---

# Next.js 16 — App Router ベストプラクティス

> 情報収集日: 2026-03-23 / Next.js 16.2.1 + React 19.2 ベース

## App Router の基本原則

- **コンポーネントはデフォルトでサーバーコンポーネント** — `'use client'` は必要最小限に
- **クライアントコンポーネントは末端に押し込む** — ツリーの上位に置かない
- **データフェッチはサーバーコンポーネントで行う** — クライアントに秘密情報を渡さない
- **Node.js 20.9+ 必須**

```typescript
// ❌ 上位コンポーネントを全クライアント化
'use client';
export default function Layout({ children }) { ... }

// ✅ インタラクティブな部分だけクライアント化
// app/dashboard/page.tsx (Server Component)
export default async function DashboardPage() {
  const data = await fetchDashboardData();
  return (
    <div>
      <h1>ダッシュボード</h1>
      <InteractiveChart data={data} />  {/* ← ここだけ 'use client' */}
    </div>
  );
}

---

## ディレクトリ構成
src/
├── app/                    # App Router（ルート定義）
│   ├── (marketing)/        # ルートグループ（URLに影響しない）
│   │   ├── page.tsx
│   │   └── layout.tsx
│   ├── (dashboard)/
│   │   ├── page.tsx
│   │   └── layout.tsx
│   ├── api/                # Route Handlers
│   │   └── users/
│   │       └── route.ts
│   ├── layout.tsx          # Root Layout
│   ├── loading.tsx         # Loading UI
│   ├── error.tsx           # Error UI
│   └── not-found.tsx
│
├── components/
│   ├── ui/                 # shadcn/ui等の汎用コンポーネント
│   └── features/           # 機能特化コンポーネント
│
├── lib/                    # ユーティリティ
├── hooks/                  # カスタムフック（クライアント側のみ）
├── server/                 # サーバー専用コード（DB・外部API等）
└── types/                  # 型定義

以下略

こんな感じで、スキルには「情報収集日」を書くようにしています。
設計やコーディングスタンダードなど、そうそう変化が起きないものは良いんですがフレームワークやライブラリは頻繁に変更が入ります。
更新しないと古いままなので何ヶ月かに一回くらいのサイクルでアップデートが入っていないかを確認し、スキルを更新する棚卸しが必要になります。
そのため収集日を記載し、ClaudeCodeも人間もどのくらい経ったかを確認できるようにしました。

この要領でバックエンドやフロントエンドのフレームワークやライブラリ、設計やエラーハンドリングなど様々なスキルを随時更新しています。

Rules

次にルールです。
CLAUDE.mdとはまた別に、特定のルールを決めたいときはrulesディレクトリに作成します。

現状ではセキュリティやGit運用、ライブラリの導入を作成したり、行動の原理原則などを作成しています。

rules/principles.md

# 行動原則

実装・レビュー・タスク対応において常に適用する行動原則。悪例/良例のセットで意図を具体化する。

---

## 1. 確認してから進む

### 悪い例 — 曖昧な要件のまま実装する

ユーザー: 検索機能を追加して
Claude:  [いきなり実装開始]
         SearchBar コンポーネントを作成しました。
         全フィールドに対してあいまい検索するロジックを追加しています...

### 良い例 — 前提を確認してから進む

ユーザー: 検索機能を追加して
Claude:  確認させてください:
         - 検索対象: タイトルのみ or 全フィールド？
         - マッチ方式: 前方一致 / 部分一致 / 全文検索？
         - リアルタイム検索 or 送信ボタン契機？

略

こんな感じで、「ClaudeCodeにやって良いことと悪いことをハッキリ分からせる」ためのものがほとんどです。
最近ではClaudeCodeが起こした事故として、削除コマンドを実行してしまったとかフォースプッシュしてしまったとか色々話題に上がってきています。
そういうニュースを調べて、それを起こさないためのルール策定をしておくと同じ轍を踏むようなリスクはだいぶ軽減されると思います。

git.md

---
description: Gitワークフロールール。ブランチ戦略・コミット規約・PRルール。
---

# Gitワークフロールール

## ブランチ戦略
main          ← 本番。直接pushは禁止
develop       ← 統合ブランチ（チーム開発時）
feat/xxx      ← 新機能
fix/xxx       ← バグ修正
refactor/xxx  ← リファクタリング
chore/xxx     ← 設定・依存関係
docs/xxx      ← ドキュメントのみ

- `main` へのコミットは必ずPR経由
- ブランチ名はケバブケース（例: `feat/user-authentication`）
- 作業ブランチは `main` または `develop` から切る

略

こんな感じです。

Commands

次にコマンドです。
ClaudeCodeは/と打つといろんなコマンドが出てきます。
元々組み込まれているコマンドもありますし、commandsディレクトリを作成してカスタムコマンドを作ることもできます。

これは「この作業がコマンド一発で出来たらなあ」っていうのがあればコマンド化するのがおすすめです。

例えばshipコマンドを作成しています
commands/ship.md

---
description: コミット前チェックからPR作成まで一連のフローを実行する。フォーマット・型チェック・テスト・レビューをすべて通してからコミット・pushする。
---

# /ship

コミット前チェックを実行し、PRを作成する一連のフローを実行する。

## 使い方
/ship

## 実行内容

### Step 1: ステージング確認
`git diff --staged` で変更内容を表示する。
ステージングが空なら `git add` を案内して終了する。
main / master ブランチなら直接コミットを拒否する。

### Step 2: 自動チェック
以下をすべて実行する。失敗した場合は修正してから再実行する。

prettier --check .
tsc --noEmit
bun test --passWithNoTests

### Step 3: コードレビュー
`/review` と同じロジックで領域を判定してレビュアーを起動する。
CRITICAL / HIGH があれば差し戻す（Step 4以降に進まない）。

### Step 4: コミットメッセージ生成
変更内容から Conventional Commits 形式で自動生成する。
確認を求めてから `git commit` を実行する。

### Step 5: PR description生成・push
`pr-author` エージェントを起動してdescriptionを生成する。
確認後に `git push -u origin <branch>` を実行する。

### Step 6: 自動保存

PR 作成完了後に `/save` と同じ処理でセッションを保存する。
メモ: 「/ship: <ブランチ名> → PR #xxx を作成」

## 注意
- main / master への直接pushは絶対に拒否する
- `git push --force` は使わない

こんな感じでコマンド用のmdファイルを作成し、/shipと打てばこの通りのステップで実行されます。

また、私の場合はClaudeCodeが継続的に学習をできるような仕組みをコマンドで実装しています。
それ用に「continuous-learning」というスキルを作成しています。
learnコマンドとcurateコマンドを作成しました。

学習サイクル

学びや気づきがあったタイミングで「今のエラー修正を/learnで記録して」と言うと、CluadeCode用のプロジェクトにある/continuous-learning/instinctsに学習した内容を記録します。

---
description: 気づいたパターン・アンチパターンを即座に instincts/ に記録する。セッション終了を待たずに学びをリアルタイムで蓄積する。
---

# /learn

気づきや知見を `skills/continuous-learning/instincts/` に即座に記録する。

## 使い方

/learn <記録したい内容>

例:
- `/learn Zodスキーマはroute内にインラインで書かず schemas/ に分離する`
- `/learn N+1はselect_relatedで解決する。prefetch_relatedは逆参照に使う`
- `/learn Docker Composeのvolumesでnode_modulesをバインドすると激遅になる`

## 実行手順

**Step 1**: `$ARGUMENTS` が空の場合は「何を記録しますか？」と聞いて終了する。

**Step 2**: `$ARGUMENTS` の内容からカテゴリを判定する。

| キーワード | カテゴリ |
|---|---|
| テスト・test・vitest・jest・playwright・カバレッジ | `testing` |
| API・エンドポイント・endpoint・レスポンス・スキーマ・Zod | `api-design` |
| アーキテクチャ・設計・レイヤー・layer・分割・責務 | `architecture` |
| セキュリティ・認証・認可・auth・token・JWT | `security` |
| パフォーマンス・最適化・N+1・キャッシュ・cache・遅い | `performance` |
| コミット・commit・ブランチ・branch・PR・マージ | `git` |
| エージェント・agent・LLM・プロンプト・Mastra・LangChain | `ai-agent` |
| 上記に該当しない | `general` |

**Step 3**: Bash でファイルパスを確定する。

INSTINCTS_DIR=~/desktop/claude-code/skills/continuous-learning/instincts
mkdir -p "$INSTINCTS_DIR"
TODAY=$(date +%Y-%m-%d)
CATEGORY=<Step 2で判定したカテゴリ>
FILEPATH="$INSTINCTS_DIR/${TODAY}-${CATEGORY}.md"
echo "FILEPATH=$FILEPATH"
[ -f "$FILEPATH" ] && echo "EXISTS=true" || echo "EXISTS=false"

**Step 4**: ファイルへの書き込み。

- ファイルが**存在する場合**: Read ツールで既存内容を読み込み、`## パターン` セクションの末尾に `- $ARGUMENTS` を1行追記してから Write で保存する。
- ファイルが**存在しない場合**: Write ツールで以下のフォーマットで新規作成する。

---
title: {CATEGORY} パターン
confidence: 0.8
source_sessions: 1
last_seen: {TODAY}
---

## パターン

- {$ARGUMENTS}

## 根拠

/learn コマンドで手動記録。確かなパターンだけ curated/ に昇格させてください。

**Step 5**: 完了を報告する。

✅ 記録しました
カテゴリ: {CATEGORY}
ファイル: instincts/{TODAY}-{CATEGORY}.md
内容: {$ARGUMENTS}

他のプロジェクト上で実行しても、ClaudeCode用プロジェクトに集約するように保存先を指定しています。

記録が終わり次第、ClaudeCode用プロジェクト側でcurateコマンドを実行します。
curateコマンドを実行すると、learnコマンドによってinstinctsに格納された記録を解析し、「他のプロジェクトでも使えそうな汎用的な知見」と「そのプロジェクト特有の仕様」かを判断します。
汎用的な知見であれば昇格対象となり、continuous-learning/curated配下にある「patterns.md」と「anti-patterns.md」に抽出します。
そのプロジェクト特有のものであれば昇格せず、instinctsに格納した記録は抽出済みですのでファイルごと削除するまでが１セットになっています。

このサイクルを作っておくことで、実装していく上で学んだことをどんどん蓄積していけるわけですね。
コードを書いて動作確認してエラーが起きて解消したことを記憶していくという、さも人間がやっていることをClaudeCodeで再現出来るのではと思い実験的に使っています。

他にもセッションの内容を記録する/saveコマンドを作成して、新たに起動した際に以前の作業などが思い出せるような仕組み作りもしています。

MCP

最後にあまり使っていませんがMCPの設定もしています。
これはローカルの.claudeの設定ファイルに記述が必要で、調べれば設定方法が出てくると思います。

MCPとはAIが外部ツールにアクセスするためのプロトコルですね。
FigmaやPlaywrightなどよく使われているツールに、ClaudeCodeがアクセスして使えるようになります。

私の場合は「Tavily」というAI向けのリアルタイム検索エンジンを使わせてリアルタイムの新鮮な情報をWeb検索させたり、ローカルで画面をテストするときに「Playwright」を使わせてUIテストやスクショなど実行させるというのを試しています。

終わり

こんな感じで
・Agents
・Skills
・Rules
・Commands
・Hooks(いまいち使いこなせていないので書いてない
・MCP
とClaudeCodeをカスタマイズする上で大事な要素を紹介しました。

今回はほんの一部ですが、実際には３４エージェントと４０スキル作成しています。
フロントエンドでも実装とレビューを分けるなど、なるべく担当範囲を絞ることで精度が向上するというのが公式でも言われているのでそれなりに細かくなっている次第です。

海外ではClaudeCodeのカスタマイズをしたリポジトリがいくつか出てきて話題になっています。（everything-claude-codeやgstackなど）

OSSなのでそのままそれらを使うのも良いんですが、正直セキュリティやプロンプトインジェクションなどのリスクを考えるとローカルに自分で持っておくのも良いんじゃないか？と思い、公開はせずコツコツ作成して日々育てております。
また、そういうのは恐ろしく細かくカスタマイズされておりオーバースペックな気もしたので、やはり「自分で作る」ということに意味があるのかなと思っています。

皆さんも、自分による自分のための自分だけのClaudeCodeを作って、日々の業務に活用していきましょう！