Claude Code 実践

本章では、ターミナルを開いてから完全な Todo REST API を動かすまでの全工程を、Claude Code + DeepSeek V4 で行います。

Claude Code + DeepSeek V4 設定参考:Claude Code DeepSeek 設定

まず、Claude Code の基本操作インターフェースと日常的に使う頻度の高いコマンドを見てみましょう。

最初の Claude Code セッションを開始する

ターミナルを開き、任意の作業ディレクトリに移動して(または空のフォルダを新規作成して)、次のように入力します:

$ mkdir サンプル-todo-api
$ cd サンプル-todo-api
$ claude

初回起動時には、ウェルカム画面とバージョン情報、そして DeepSeek の環境変数設定が表示されます。

設定が有効かどうかわからない場合は、起動後すぐに入力します/status、Base URL が次の値を指していることを確認しますhttps://api.deepseek.com/anthropic。

よく使うスラッシュコマンド早見表

Claude Code のチャット画面では、/で始まるのは組み込みコマンドで、モデルには送信されません。

コマンド説明
/status現在のモデル、Base URL、セッション統計を表示
/help利用可能なすべてのコマンドを表示
/clear現在の会話コンテキストをクリア(ファイルは削除しない)
/exit または Ctrl+CClaude Code を終了
/undo直前のファイル変更を元に戻す
/diff最近の変更の git diff を表示

権限確認メカニズム

Claude Code がファイルへの書き込みやコマンドの実行を行おうとするとき、いったん停止して、実行しようとする操作をリストアップし、あなたの確認を待ちます。

これは Claude Code の最も重要な安全メカニズムで、初心者は AI が暴走して勝手に変更することを心配する必要はありません。

次のようなプロンプトが表示されます:

┌─────────────────────────────────────────────────┐
│  Claude wants to create the following files:     │
│                                                  │
│  • src/index.js                                  │
│  • src/routes/todos.js                           │
│  • package.json                                  │
│                                                  │
│  Allow? [Y/n]                                    │
└─────────────────────────────────────────────────┘

直接押すEnterまたは入力y確認、入力nスキップ。


実践プロジェクト:AI を使ってゼロから Todo API を構築する

このセクションでは、自然言語で Claude Code を操作して、ゼロから動作する Node.js REST API を生成します。

プロジェクトの目標

以下の機能を持つ REST API を構築します:

エンドポイント機能
GET /todosすべてのTodoを取得
POST /todos新しいTodoを作成
PUT /todos/:idTodoを更新(完了にマーク/内容の変更)
DELETE /todos/:idTodoを削除

技術スタック:Node.js + Express、データはメモリに一時保存します(データベースは不要で、複雑さを軽減できます)。

ステップ 1:自然言語で要件を記述する

Claude Code のチャット画面に以下の内容を入力します(コピー&ペーストでOK):

请帮我从零创建一个 Node.js + Express 的 Todo REST API 项目。

要求:
- 支持 GET /todos、POST /todos、PUT /todos/:id、DELETE /todos/:id 四个接口
- 数据先存在内存数组里,不需要数据库
- 每个 todo 包含:id、title、completed(布尔值)、createdAt 字段
- 请求和响应都使用 JSON 格式
- 加上基础的错误处理(404、400 等)
- 生成一份 README.md,说明如何启动和测试接口

项目结构建议:
my-todo-api/
├── src/
│   ├── index.js       # 入口文件
│   └── routes/
│       └── todos.js   # Todo 路由
├── package.json
└── README.md

優れたプロンプトを書くための3つの要素:コンテキスト(AIに技術スタックとプロジェクト背景を伝える)、制約(何が不要かを明確にする)、期待する出力(具体的なファイル構造やフォーマット要件を示す)。

ステップ 2:Claude Code がファイル構造を生成する

権限を確認した後、Claude Code は以下のファイルを順に作成します。

生成中に多くの権限確認がありますが、通常はそのまま Yes を選択すれば問題ありません:

成功すると、生成された内容や起動情報などを含む詳細な情報が出力されます:

生成されたプロジェクト構造を確認しましょう:

package.json

例

{
  "name": "my-todo-api",
  "version": "1.0.0",
  "description": "A simple Todo REST API built with Express",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

src/index.js(エントリーファイル)

例

// ファイルパス:src/index.js
// Todo API のエントリーファイル。Express アプリの設定と起動を担当

const express = require('express');
const todosRouter = require('./routes/todos');

const app = express();
// ポート番号:環境変数 PORT を優先、デフォルトは 3000
const PORT = process.env.PORT || 3000;

// ミドルウェア:JSON リクエストボディを解析(必須。これがないと req.body が undefined になる)
app.use(express.json());

// Todo ルーターを登録。/todos パスへのリクエストはすべて todosRouter が処理
app.use('/todos', todosRouter);

// ルートパス:ウェルカムメッセージとバージョン番号を返す
app.get('/', (req, res) => {
  res.json({ message: 'Todo API is running!', version: '1.0.0' });
});

// グローバルエラーハンドリングミドルウェア(必須。未処理の例外をキャッチする)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal Server Error' });
});

// HTTP サーバーを起動
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

src/routes/todos.js(コアルーターファイル)

例

// ファイルパス:src/routes/todos.js
// Todo ルーターモジュール。完全な CRUD ビジネスロジックを含む

const express = require('express');
const router = express.Router();

// メモリストレージ:配列を使ってデータベースをシミュレート
// サービス再起動後はデータが失われる。後で SQLite などの永続化方式に置き換え可能
let todos = [];
// 自動増加の ID カウンター
let nextId = 1;

// GET /todos — すべてのTodoを取得
router.get('/', (req, res) => {
  res.json(todos);
});

// POST /todos — 新しいTodoを作成
router.post('/', (req, res) => {
  const { title } = req.body;

  // パラメータ検証:title は必須フィールドで、文字列型かつ空であってはならない
  if (!title || typeof title !== 'string' || title.trim() === '') {
    return res.status(400).json({ error: 'title フィールドは空にできません' });
  }

  // 新しい todo オブジェクトを構築
  const newTodo = {
    id: nextId++,                         // ID を自動増加
    title: title.trim(),                   // 前後の空白を除去
    completed: false,                      // 新しく作成した todo はデフォルトで未完了
    createdAt: new Date().toISOString(),   // ISO 8601 形式のタイムスタンプ
  };

  todos.push(newTodo);
  // 201 Created はリソースの作成成功を表す
  res.status(201).json(newTodo);
});

// PUT /todos/:id — Todoを更新
router.put('/:id', (req, res) => {
  // パスパラメータを文字列から数値に変換
  const id = parseInt(req.params.id);
  const todo = todos.find(t => t.id === id);

  // 404:リソースが存在しない
  if (!todo) {
    return res.status(404).json({ error:`id が ${id}のTodoが見つかりません`});
  }

  const { title, completed } = req.body;
  // 渡されたフィールドのみ更新し、渡されていないフィールドは元の値を保持
  if (title !== undefined) todo.title = title.trim();
  // Boolean() により completed が常にブール型になることを保証
  if (completed !== undefined) todo.completed = Boolean(completed);

  res.json(todo);
});

// DELETE /todos/:id — Todoを削除
router.delete('/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = todos.findIndex(t => t.id === id);

  if (index === -1) {
    return res.status(404).json({ error:`id が ${id}のTodoが見つかりません`});
  }

  // 配列から指定した位置の要素を削除
  todos.splice(index, 1);
  // 204 No Content は削除成功を表し、レスポンスボディは空
  res.status(204).send();
});

module.exports = router;

ステップ 3:変更内容をレビューして確認する

Claude Code がコードを生成したら、すぐに実行せず、レビューする習慣をつけましょう。

対話の中でさらに質問することができます:

你帮我生成的代码我看了一下,有几个问题想确认:
1. POST /todos 时,如果 title 是数字类型会怎么处理?
2. PUT 接口能同时更新 title 和 completed 吗?
3. 有没有对 id 不是数字的情况做处理?

Claude Code は一つずつ回答し、その場でコードを修正することもできます。

この「生成 → 質問 → 修正」のサイクルが、AI との協業における核となるリズムです。

ステップ 4:依存関係をインストールしてサービスを起動する

Claude Code のチャット画面に次のように入力します:

请帮我安装依赖并启动项目,然后告诉我怎么用 curl 测试每个接口

Claude Code は以下の操作を実行します(各ステップで確認を求められます)。

依存関係のインストール

$ npm install

出力例:

added 64 packages in 2.3s

サービスの起動

$ npm start

出力:

Server is running on http://localhost:3000

テストコマンド

新しいターミナルウィンドウを開き、以下の curl コマンドを順に実行します:

# 创建第一条 Todo
$ curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "学习 Claude Code"}'

# 创建第二条 Todo
$ curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "完成 DeepSeek 配置"}'

# 获取所有 Todos
$ curl http://localhost:3000/todos

# 把第一条标记为完成
$ curl -X PUT http://localhost:3000/todos/1 \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'

# 删除第二条
$ curl -X DELETE http://localhost:3000/todos/2

# 再次查看列表,确认删除成功
$ curl http://localhost:3000/todos

期待される出力(GET /todos の最終結果)

[
  {
    "id": 1,
    "title": "学习 Claude Code",
    "completed": true,
    "createdAt": "2026-05-20T10:30:00.000Z"
  }
]

おめでとうございます。AI 支援で開発した最初の API が動き出しました。

発展チャレンジ:Claude Code に新機能を追加してもらう

API が動作するようになったら、自然言語で Claude Code に機能を拡張してもらいましょう:

请给 Todo API 加上以下功能:
1. GET /todos 支持 ?completed=true/false 的查询参数过滤
2. GET /todos 支持 ?sort=createdAt&order=desc 的排序参数
3. 同时更新 README.md 里的接口文档

Claude Codeが既存のコード構造をどのように理解し、ファイル全体を書き直すのではなく、正確に正しい位置に新しいロジックを挿入するかを観察します。

これこそが、通常のコード生成ツールよりも優れている点です。


CLAUDE.md:プロジェクト記憶ファイル

CLAUDE.mdはClaude Codeのプロジェクトレベルの記憶ファイルであり、AIが起動するたびに自動的にプロジェクトの規約を把握できるようにします。

なぜ必要か

Claude Codeは起動するたびに「まっさらな状態」です——前回のセッションで何を言ったか覚えていません。

しかし、プロジェクトのルートディレクトリにCLAUDE.mdファイルがあれば、Claude Codeは起動するたびにそれを自動的に読み込みます。これはAIへの「プロジェクト説明書」に相当します。

CLAUDE.mdがない場合の課題:

  • 毎回「Expressを使っていてKoaは使わない」と説明し直さなければならない
  • AIが命名規約を忘れて、またキャメルケースのファイルを生成してしまう
  • チームメンバーがそれぞれAIに異なる約束事を伝え、コードスタイルが混乱する

CLAUDE.md の書き方テンプレート

プロジェクトのルートディレクトリにCLAUDE.mdを作成し、内容は以下のテンプレートを参考にしてください:

# 项目说明(CLAUDE.md)

## 项目概述
这是一个 Node.js + Express 的 Todo REST API 项目。
当前阶段:数据存在内存中,下一步会迁移到 SQLite。

## 技术栈
- 运行时:Node.js 18+
- 框架:Express 4.x
- 测试:(暂无,后续加 Jest)
- 代码风格:ESLint + Prettier(配置见 .eslintrc)

## 目录结构
src/
├── index.js        # 入口,只做 app 配置和监听
└── routes/
    └── todos.js    # Todo 业务逻辑全在这里

## 命名规范
- 文件名:kebab-case(如 todo-service.js)
- 变量/函数:camelCase
- 常量:UPPER_SNAKE_CASE
- 路由文件按资源名命名(如 users.js、products.js)

## 重要约定
- 所有接口返回 JSON,错误统一格式:{ "error": "错误描述" }
- HTTP 状态码语义要准确:创建成功用 201,删除成功用 204
- 禁止在路由文件里直接操作数据库(现在是内存数组,将来是 DB)
- 每个路由文件只处理一种资源

## 禁止事项
- 不要用 var,只用 const/let
- 不要用回调风格,统一用 async/await
- 不要在代码里写中文注释(英文注释即可)
- 不要安装 lodash,原生 JS 方法够用

## 启动方式
npm start          # 生产模式
npm run dev        # 开发模式(nodemon 热重载)

## 测试接口
见 README.md 的 curl 示例

Claude Code に CLAUDE.md を自動生成させる

手書きしたくない?直接AIに生成してもらいましょう:

请根据当前项目的代码结构和我们的对话记录,
帮我生成一份 CLAUDE.md 文件,
内容包括项目概述、技术栈、目录结构、命名规范和重要约定。

Claude Codeが生成済みのすべてのファイルを分析し、このプロジェクトに適したCLAUDE.mdを自動的に整理します。

CLAUDE.md のメンテナンスのリズム

タイミングやるべきこと
新しい依存関係を導入する「技術スタック」セクションを更新する
ファイル構造を変更する「ディレクトリ構造」セクションを更新する
新しいコーディング規約を定める「重要な約束事」に追加する
AIが同じミスを繰り返していることに気づく「禁止事項」に追加する

CLAUDE.mdをGitにコミットすれば、チームの全メンバーとAIが同じ規約を共有できます。

これはAIを活用したチームコラボレーションの基盤となります。


本章のまとめ

学んだこと対応する内容
Claude Codeを起動し、DeepSeek設定を確認するセッションの開始と /status
3つの要素からなるプロンプトで要件を記述するステップ1:自然言語での記述
AIが生成したコードをレビューするステップ3:レビューと疑問の提起
依存関係のインストール、起動、curlを使ったAPIテストステップ4:実行とテスト
CLAUDE.mdでプロジェクト記憶を管理するCLAUDE.mdの設定
その他の拡張