LoginSignup
7
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@megmogmog1965(Yusuke Kawatsu)in株式会社リンクアンドモチベーション

Next.js + SQLite で開発できる Claude Code の Plugin を作ってみた

Last updated at Posted at 2025-10-23

この記事は何？

困りごと 😵

私の開発現場では現在、新規プロダクトの開発で Claude Code を用いています。

実装・ユニットテスト工程においては 100% Claude Code で行えていますが、そのノウハウが 手順書 だったり 個人の脳みその中 にあったりして、なかなか社内で他開発者に展開するのが難しい...と悩んでおりました。

どんな素晴らしい文書（ガイドブック）を書こうか！　という話をしょっちゅうしておりました😅

Claude Code の Plugins と Agent Skills の登場

Claude Code では、ここ最近立て続けに次の２つの機能がリリースされています。
Plugins と Agent Skills です。

この Agent Skills と、従来からある Subagents, Hooks, Slash Commands などをプラグインとしてバンドル＆配布することで、 なんちゃって手順書を卒業 することを試みました。

できあがったもの 🚀

（３分クッキングの如く）既に出来上がったものはこちらに...

このプラグインを導入すると、Next.js + SQLite を使った Web アプリケーション開発が、手順書とかなくとも自然とできるようになります。

あくまでお試し＆公開用として作ったものなので、内容はかなり簡易的です🙇‍♂️

使い方

まずは何を目指したか？ から説明した方が後の解説がわかりやすいので、このプラグインを使った開発の流れを説明します。

動作環境

  • Node.js - v24.4.1
  • Claude Code - v2.0.24
  • Next.js - v16.0.0

1. 新規に Next.js プロジェクトを作る

Next.js チュートリアル にある、おなじみの手順 npx create-next-app@latest で新規プロジェクトを作成します。

~/ % npx create-next-app@latest
✔ What is your project named? … next-sqlite-example
✔ Would you like to use the recommended Next.js defaults? › Yes, use recommended defaults
Creating a new Next.js app in /path/to/next-sqlite-example.

Using npm.

...

Success! Created next-sqlite-example at /path/to/next-sqlite-example

2. プラグインのインストール

次の手順で、Claude Code に Github repo として公開されている Plugins を導入します。

# claude code (cli) の起動.
claude

# marketplace. (npm で言うところの registry みたいなもの)
─────────────────────────────────────────────────────────
> /plugin marketplace add https://github.com/megmogmog1965/claude-marketplace
─────────────────────────────────────────────────────────

# marketplace 中の plugin 1つをインストールする.
─────────────────────────────────────────────────────────
> /plugin install nextjs-sqlite
─────────────────────────────────────────────────────────

3. 初期化 (CLAUDE.md などを生成する)

プラグイン導入すると使えるようになる /init コマンドを実行します。

ビルドインの /init コマンドもあるので注意。（名前かぶった...🫠)

─────────────────────────────────────────────────────────
> /init 
─────────────────────────────────────────────────────────
   /init                   Initialize a new CLAUDE.md file with codebase documentation
 → /nextjs-sqlite:init     Initialize Next.js + SQLite project with Claude Code configuration files
                           (plugin:nextjs-sqlite@claude-marketplace)

すると、次のファイルがプロジェクトルートにコピーされます。

CLAUDE.md　（参考資料↓はここにあるよ〜、こういう Skills があるよ〜、など全体概要を伝える）
docs/
  ├── software-development-lifecycle.md　（開発の手順を解説）
  ├── coding-rule.md　（コーディングルールの定義）
  ├── architecture.md　（Next.js, SQLite, Shadcn, Vite... など全体アーキテクチャを説明）
  ├── test-rule.md　（テストコードの生成と実行などのルール）
  └── ui-design-rule.md　（UIデザインについてのルール）

これらの設計ルールについて記述したファイルは CLAUDE.md や、後述する実装計画書から自然と参照されるようになっています。

4. 実装計画 (≒ 設計書) を生成する

作業が小さく明確なタスクであれば、本章をスキップ（実装計画書を作成しない）して、直接コーディング指示をすることもできます。

本来は /docs/requirements/*.md などに格納した要件定義ファイルの要件定義番号を入力としたい！

プラグイン導入すると使えるようになる /spec コマンドを実行します。

─────────────────────────────────────────────────────────
> /nextjs-sqlite:spec トップページにおみくじを引く機能を追加してください。
                      結果はデータベースに保存して日付とともに一覧表示してね。
─────────────────────────────────────────────────────────

すると、次の実装計画書ファイル (マークダウン) が生成されます。

生成された内容があなたの期待値と異なった場合は、具体的に修正指示を出しましょう。

docs/spec/20251022223557-omikuji-feature.md
# おみくじ機能

## 概要

トップページにおみくじを引く機能を追加します。おみくじの結果（大吉、中吉、小吉、吉、凶など）をランダムに抽選し、結果を日付とともにデータベースに保存します。また、過去のおみくじ履歴を一覧表示します。

## タスク

各タスクは機能的に独立して実装が完了でき、動作検証ができるようにすること。
また、作業が完了した項目には `[✓]` を付けてください。

### タスク1: マイグレーション - おみくじ結果テーブルの作成

**実装**:
1. [ ] Prismaスキーマの作成: `prisma/schema.prisma` を新規作成
   - `Omikuji` モデルを定義
     - `id`: Int (主キー、自動採番)
     - `result`: String (おみくじの結果: 大吉、中吉、小吉、吉、末吉、凶、大凶)
     - `createdAt`: DateTime (抽選日時、デフォルト値: now())
   - インデックス: `createdAt` に降順インデックスを追加（履歴一覧表示の高速化）
2. [ ] データベース設定: `.env` ファイルを作成
   - `DATABASE_URL="file:./dev.db"` を設定
3. [ ] Prisma Client セットアップ: `lib/db.ts` を作成
   - シングルトンパターンで Prisma Client インスタンスを作成
4. [ ] マイグレーション実行: `update-prisma-schema` skill を使用
   - `prisma/migrations/` にマイグレーションファイルを自動生成
   - データベースにマイグレーションを適用
   - Prisma Client を再生成

**品質チェック**:
1. [ ] スキーマ変更が正常に適用された
2. [ ] Prisma Client が再生成された
3. [ ] マイグレーションエラーがない
4. [ ] `build` subagent でビルドエラーがないことを確認

---

### タスク2: バックエンド - おみくじAPI実装

**実装**:
1. [ ] APIルートの作成: `app/api/omikuji/route.ts`
   - **POST /api/omikuji**: おみくじを引く
     - おみくじの結果をランダムに抽選（大吉、中吉、小吉、吉、末吉、凶、大凶）
     - 結果をデータベースに保存
     - 保存した結果を返す
   - **GET /api/omikuji**: おみくじ履歴を取得
     - `createdAt` 降順で全件取得
     - JSON形式で返す
   - エラーハンドリング（データベースエラー、バリデーションエラー）
2. [ ] ビジネスロジックの実装: `lib/omikuji.ts`
   - `drawOmikuji()`: おみくじを引いてDBに保存する関数
   - `getOmikujiHistory()`: おみくじ履歴を取得する関数
   - おみくじの結果配列: `['大吉', '中吉', '小吉', '吉', '末吉', '凶', '大凶']`
3. [ ] 型定義の追加: `types/omikuji.ts`
   - `OmikujiResult` 型: Prisma から生成される型を利用
   - `OmikujiResponse` 型: API レスポンスの型

**テスト** (実装後に記述):
1. [ ] ユニットテスト: `lib/omikuji.test.ts`
   - `drawOmikuji()` のテスト: モックを使用してDB保存を検証
   - `getOmikujiHistory()` のテスト: モックを使用してDB取得を検証
   - おみくじ結果がランダムに選ばれることを検証

**品質チェック**:
1. [ ] `test` subagent でテスト実行、エラーがあれば修正
2. [ ] `lint` subagent で静的解析実行、エラーがあれば修正
3. [ ] `build` subagent でビルド実行、エラーがあれば修正

---

### タスク3: フロントエンド - トップページUI実装

**実装**:
1. [ ] トップページの更新: `app/page.tsx`
   - Server Component で初期おみくじ履歴を取得
   - `OmikujiClient` コンポーネントを配置
   - 既存の Next.js デフォルトコンテンツを置き換え
   - レイアウト: 中央配置、最大幅 `max-w-2xl`、パディング `p-8`
2. [ ] クライアントコンポーネントの作成: `components/omikuji/OmikujiClient.tsx`
   - 「おみくじを引く」ボタン
     - クリックで POST /api/omikuji を呼び出し
     - 結果を取得後、履歴を再取得
   - おみくじ結果の表示エリア
     - 最新の結果を大きく表示
     - アニメーション効果（フェードイン）
   - おみくじ履歴の一覧表示
     - テーブル形式で表示（日時、結果）
     - 降順ソート（新しい順）
     - 最大10件表示
   - ローディング状態の表示
   - エラーハンドリング
3. [ ] スタイリング
   - Tailwind CSS を使用
   - ダークモード対応
   - レスポンシブデザイン（モバイル対応）
   - 既存の `app/page.tsx` のスタイルパターンに従う
     - 背景色: `bg-zinc-50 dark:bg-black`
     - テキスト色: `text-black dark:text-zinc-50`
     - ボタンスタイル: `rounded-full`, `hover:` 効果

**テスト** (実装後に記述):
1. [ ] ユニットテスト: `components/omikuji/OmikujiClient.test.tsx`
   - ボタンクリックで API が呼ばれることを検証
   - fetch のモック
   - 履歴が正しく表示されることを検証

**品質チェック**:
1. [ ] `lint` subagent で静的解析実行、エラーがあれば修正
2. [ ] `build` subagent でビルド実行、エラーがあれば修正
3. [ ] `run_dev` skill を使用してUIを手動検証
   - おみくじを引くボタンが動作すること
   - 結果が表示されること
   - 履歴が更新されること
   - レスポンシブデザインが正しく動作すること

---

5. 実装をする (Claude Code が...笑)

ひとこと、こう言うと最後まで実装をしてくれます。

─────────────────────────────────────────────────────────
> それでは、実装計画書の内容に基づいて実装を開始してください！
─────────────────────────────────────────────────────────

ここで大事な点は下記の通りです。

  1. 作業は全て実装計画書に書いてあるので、Agent が迷うことはない
  2. 処理が長引いてコンテキストが失われても、現在の進捗、次に何をすべきか、は実装計画書に書かれている

実装計画書がきちんと書かれていれば、それなりの規模のコードでも期待通りの生成をしてくれます。

(fin)

結果、こんな Web アプリケーション（ページ）を生成してくれました。

✨✨✨ なんて素敵なUX！ 笑 ✨✨✨

きちんと、おみくじの結果はデータベース (SQLite) に保存されます。

image.png

しくみの解説

ここからは、本プラグインで何をしているか説明します。

プラグインに含めたもの

次の Claude Code で実現できる機能をプラグインに同梱して、開発者の環境で使える (or 自動的に使われる) ようにしました。

機能 誰が利用？ 説明
Slash Commands 開発者 開発者（人間）向けの特定処理のショートカットコマンドです。
Subagents Agent判断 コンテキスト枯渇による Agent の記憶忘却を回避する目的で使用します。

頻繁に実施される＆テキスト出力の多い処理を Subagent で実行します。
Agent Skills Agent判断 Claude Agent の判断によって、自動で実行させたい一連の処理（能力, Subroutine）を定義します。
Hooks ルールベース Claude Agent の判断に依存せず、ルールベースで必ず実行が保証される処理です。

プラグインのディレクトリ構成

nextjs-sqlite/
|   ### プラグインの metadata 情報 ###
├── .claude-plugin/
│   └── plugin.json
|
│   ### Custom slash commands (optional) ###
├── commands/
│   ├── init.md        # "init_files" skill を呼び出すだけ.
│   └── spec.md        # 実装計画書を作る手順を記載.
│
|   ### Custom agents (optional) ###
├── agents/
│   ├── lint.md        # `npm run lint` を subagent で.
│   ├── build.md       # `npm run build` を subagent で.
│   └── test.md        # `npm run test` を subagent で.
│
|   ### Agent Skills (optional) ###
├── skills/
│   ├── init_files     # CLAUDE.md や docs/*.md をプロジェクトにコピーする.
│   │   ├── SKILL.md
│   │   ├── scripts
│   │   │   └── copy_files.sh
│   │   └── templates
│   │       ├── CLAUDE.md
│   │       └── docs
│   │           ├── architecture.md
│   │           ├── coding-rule.md
│   │           ├── software-development-lifecycle.md
│   │           ├── test-rule.md
│   │           └── ui-design-rule.md
│   ├── update-prisma-schema/  # prisma.schema 修正とマイグレーション実行の一連手順.
│   │   └── SKILL.md
│   └── run_dev/               # `npm run dev` をする.
│       └── SKILL.md
│
|   ### Event handlers (optional) ###
└── hooks/                     # ファイルが修正されたら自動で `npm run lint`.
    └── hooks.json

プラグインの動作

図にするとこうです。

  1. /init: プロジェクトに最適化（Next.js + SQLite）した、CLAUDE.md や各種設計方針資料 /docs/*.md をプロジェクトルートに配置
  2. /spec: 実装内容を 実装計画書.md に書き出す
    • 開発者との期待値の合意（要件があってるか？　アーキテクチャがあってるか？）
    • 途中でコンテキストが失われても、作業を再確認できるように
  3. 開発者: 実装の開始を指示
  4. Agent: ファイル 実装計画書.md を読んで、その通りに実装
    • （スキーマの修正→マイグレなど）複雑かつ定型の処理は Agent Skills で実行
    • （lint, build, test など）subagent 実行で結果だけ見てコンテキスト節約

image.png

各種モジュールの解説 (commands, agents, skills, hooks)

各機能でそれぞれ１つだけピックして中身を見ていきます。

Slash Commands

開発者が /spec コマンドを実行した際に、次の markdown 指示に基づいて実行計画書が生成されます。

commands/spec.md
---
description: 実装計画書を作成する
allowed-tools: Bash, Read, Write, Edit, Grep, Glob
---

# 実装計画書作成コマンド

**$ARGUMENTS** で指定された要件定義を実現する詳細な実装計画書を作成します。具体的な要件定義が指示されていない場合は、実装計画をしたい要件をユーザーに聞いてください。

## 1. 仕様書ドキュメント構造

ファイル `docs/spec/{yyyyMMddHHmmss}-{title}.md` を以下の形式で作成してください：

```markdown
# {title}

## 概要

{実装アプローチの簡潔な要約}

## タスク

各タスクは機能的に独立して実装が完了でき、動作検証ができるようにすること。
また、作業が完了した項目には `[✓]` を付けてください。

### タスク1: マイグレーション - {タスク名}

**実装**:
1. [ ] Prismaスキーマの修正: `prisma/schema.prisma` を編集
   - モデル、フィールド、リレーション、インデックスの追加/変更
   - 例: `Post` モデルを追加し、`User` への `authorId` リレーションを設定
2. [ ] マイグレーション実行: `update-prisma-schema` skill を使用
   - `prisma/migrations/` にマイグレーションファイルを自動生成
   - データベースにマイグレーションを適用
   - Prisma Client を再生成

**品質チェック**:
1. [ ] スキーマ変更が正常に適用された
2. [ ] Prisma Client が再生成された
3. [ ] マイグレーションエラーがない
4. [ ] `build` subagent でビルドエラーがないことを確認

---
...

長いので以降割愛。

Subagents

Agent の自己判断で Subagents は実行されます。

次の Subagents では、npm run lint の処理を行い、必要であれば修正までします。うまくいったかどうか最終結果のみを親 Agent に報告します。

結果のみ親には通知されるので、コンテキストが消費されない。

agents/lint.md
---
name: lint
description: ESLint 及び各種 Linter を実行し、ソースコードの静的解析を行います。違反が検出された場合は修正を行います。
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

# Lint Agent

あなたは Next.js + SQLite プロジェクトの静的解析を担当する専門エージェントです。

## 役割

ESLint および各種 Linter を実行し、コードの品質を保証します。検出された違反は自動的に修正します。

## 実行手順

1. **Lint の実行**
   - `npm run lint` コマンドを実行してください
   - 出力結果を詳細に分析してください

2. **違反の検出と分析**
   - エラーや警告が検出された場合、各違反項目を特定してください
   - ファイルパス、行番号、違反内容を把握してください

3. **自動修正の試行**
   - まず `npm run lint -- --fix` で自動修正を試みてください
   - 自動修正できたかどうかを確認してください

4. **手動修正**
   - 自動修正できなかった違反については、以下の手順で修正してください:
     - Read ツールで該当ファイルを読み込む
     - 違反内容を理解し、適切な修正方法を判断する
     - Edit ツールで修正を適用する
   - 1つずつ確実に修正してください

5. **修正の検証**
   - すべての修正後、再度 `npm run lint` を実行してください
   - すべての違反が解消されたことを確認してください

6. **結果の報告**
   - 修正した違反の数と内容を要約してください
   - 修正できなかった項目がある場合は、その理由を説明してください

## 重要な注意事項

- コードの意図や機能を変更しないでください
- TypeScript の型エラーは別のエージェント（build）が担当します
- テストコードも lint 対象に含まれます
- プロジェクトの `.eslintrc` 設定に従ってください
- 修正後は必ず lint を再実行して検証してください

Agent Skills

データベーススキーマの修正は、常に次の一連の手順を追ってほしいです。

直接プロンプト指示すると、毎回やり方がバラバラでイライラするので、Agent Skills にします。

  1. prisma.schema の変更
  2. validate の実行
  3. マイグレーションの適用
  4. 検証
skills/update-prisma-schema/SKILL.md
---
name: update-prisma-schema
description: Prisma で定義されたデータベーススキーマ (schema.prisma) の修正変更と、マイグレーション適用を実行します。データベーススキーマ (schema.prisma) の変更が必要なときに使用してください。
allowed-tools: Read, Edit, Bash, Grep, Glob
---

# Update Prisma Schema Skill

このスキルは、Prisma のデータベーススキーマを変更し、マイグレーションを適用します。

## 目的

- Prisma スキーマファイル (`schema.prisma`) の修正
- マイグレーションファイルの生成
- データベースへのマイグレーション適用
- Prisma Client の再生成
- スキーマ変更の検証

## 使用タイミング

このスキルは以下の状況で使用してください：

- 新しいテーブル（モデル）を追加するとき
- 既存テーブルにカラムを追加・削除・変更するとき
- リレーション（外部キー）を追加・変更するとき
- インデックスやユニーク制約を追加するとき
- データ型を変更するとき

## 実行手順

### 0. Prisma + SQLite の初期セットアップ（初回のみ）

プロジェクトに Prisma がまだセットアップされていない場合は、以下の手順で初期化してください：

**Prisma のインストール：**

```bash
npm install prisma --save-dev
npm install @prisma/client
...

長いので以降割愛。

Hooks

ファイルの修正後など、Agent の判断によらず、ルールベースで必ず実行 したい処理を Hooks として登録します。

今回は試しに、ファイル変更で npm run lint するようにしました。

Agent は Hooks の処理経過 (stdout) を見ません。

その為 Hooks の処理が失敗して、何らかの分岐対応をさせたい場合は、Hooks 側で exit 2 で終えるようにします。

※Claude >> Hooks >> 終了コード

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f \"$CLAUDE_PROJECT_DIR/package.json\" ] && grep -q '\"lint\"' \"$CLAUDE_PROJECT_DIR/package.json\"; then cd \"$CLAUDE_PROJECT_DIR\" && npm run lint -- --fix || exit 2; fi",
            "timeout": 120,
            "description": "Auto-run ESLint fix after file modifications"
          }
        ]
      }
    ]
  }
}
7
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
7
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?