Spec-Driven Development実践：CLIツール「claudelog」を要件定義から実装まで1日で完走した記録

「要件定義から実装・テストまで1日で終わる」——大げさに聞こえるかもしれないが、Spec-Driven Developmentのワークフローに乗せれば実際に可能になる。

本記事では、2026年2月11日にClaude Codeの会話ログをOllamaで要約するCLIツール「claudelog」を、要件定義から実装・テストまで1日で完走した記録を紹介します。途中で仕様変更が入り、設計を修正する場面も含めて、Spec-Driven Developmentの実践フローを具体的に記録します。

claudelogとは

claudelogは、Claude Codeの会話ログ（JSONLファイル）をOllamaのローカルLLMで要約し、Markdownファイルに出力するCLIツールです。

解決したい課題:

Claude Codeの会話ログは大量に溜まるが、後から振り返るのが困難
「あのとき何を議論したか」を素早く確認したい
ローカルで完結させたい（外部APIへの送信を避ける）

技術スタック:

TypeScript
Jest（ユニットテスト + 統合テスト）
Ollama（ローカルLLM）

Spec-Driven Developmentの5ステージ

claudelogの開発では、以下の流れで進めました。

ステージ1: 要件定義（/sc:design）

まず、ツールの目的と機能要件を明確にしました。

1
## 機能要件
2
- Claude Codeの会話ログ（JSONL）を読み込む
3
- Ollamaで要約を生成
4
- Markdownファイルに出力（追記モード）
5

6
## 非機能要件
7
- ローカル完結（外部API不使用）
8
- TypeScriptで型安全に実装

ステージ2: テスト設計（/test-design）

要件が固まった段階で、先にテストケースを設計しました。

1
// ユニットテストの設計例
2
describe("parseConversationLog", () => {
3
  it("JSONLファイルを正しくパースできる", () => {
4
    // 正常系：会話ログのパース
5
  });
6

7
  it("不正なJSONL行をスキップする", () => {
8
    // 異常系：壊れた行の処理
9
  });
10
});
11

12
describe("appendToMarkdown", () => {
13
  it("既存ファイルに追記できる", () => {
14
    // ファイルが存在する場合
15
  });
5 collapsed lines
16

17
  it("ファイルが存在しない場合は新規作成する", () => {
18
    // ファイルが存在しない場合
19
  });
20
});

ステージ3: 実装（/sc:implement）

テスト設計に基づいて実装を進めました。

1
// Markdown追記（append）の実装例
2
import { appendFileSync, existsSync, writeFileSync } from "fs";
3

4
const appendToMarkdown = (filePath: string, content: string): void => {
5
  if (existsSync(filePath)) {
6
    appendFileSync(filePath, `\n\n${content}`);
7
  } else {
8
    writeFileSync(filePath, content);
9
  }
10
};

ステージ4: テスト実行（/sc:test）

Jest でユニットテストと統合テストを実行し、全テストがパスすることを確認しました。

ステージ5: Git操作（/sc:git）

テスト完了後、コミット・プッシュを実行——のはずでしたが、ここで問題が発生しました（後述）。

途中の仕様変更：マージ機能 → 単純追記に簡素化

開発途中で、当初予定していた「複数ログのマージ機能」を「単純追記（append）」に簡素化する仕様変更を行いました。

変更前の設計:

複数の会話ログを日付順にマージしてMarkdownに出力
重複検出・排除ロジック

変更後の設計:

単純に既存ファイルへ追記
マージ・重複排除は不要

変更の判断理由:

マージ機能はMVPには過剰
追記で十分にユースケースを満たせる
実装・テストの複雑さを大幅に削減できる

Spec-Driven Developmentの利点は、こうした仕様変更が設計ドキュメントの修正で明確に追跡できることです。要件定義に立ち返り、「マージ機能はスコープ外」と記録することで、後から「なぜこの機能がないのか」が分かります。

ドキュメント管理：docs/の命名規則

claudelogプロジェクトでは、設計ドキュメントを docs/ ディレクトリに番号付きで管理しました。

1
docs/
2
├── 001_requirements.md      # 要件定義
3
├── 002_design.md            # 技術設計
4
├── 003_test_design.md       # テスト設計
5
└── 004_implementation.md    # 実装メモ

この 001_XXX, 002_XXX の命名規則により、ドキュメントの作成順序が一目で分かります。Spec-Driven Developmentの各ステージの成果物が時系列で整理されるため、後から振り返る際に便利です。

git commit時のHEREDOCエスケープ問題

開発の最終段階、git commitで予想外のトラブルに遭遇しました。

発生した問題

Claude Codeがgit commitを実行する際、複数行のコミットメッセージで以下のエラーが発生しました。

1
# エラー1: -m オプションの改行でシェルが誤解釈
2
git commit -m "feat: implement claudelog" \
3
  -m "Add markdown append functionality" \
4
  -m "Co-Authored-By: ..."
5

6
# → error: pathspec ' ' did not match any file(s) known to git
7
# → zsh: command not found: -m

1
# エラー2: 引用符のネストで-mの値が空に
2
# → error: switch 'm' requires a value
3
# → zsh: command not found: Co-Authored-By

解決策：HEREDOCの使用

最終的に、HEREDOCを使うことで安定してコミットメッセージを渡せるようになりました。

1
git commit -m "$(cat <<'EOF'
2
feat: implement claudelog markdown append
3

4
Add functionality to parse Claude Code conversation logs
5
and append summaries to markdown files using Ollama.
6

7
Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
8
EOF
9
)"

ポイント: <<'EOF'（シングルクォート付き）にすることで、メッセージ内の特殊文字がエスケープされずにそのまま渡されます。

なお、この問題はclaudelogプロジェクトに限らず、Claude Codeでのgit操作全般で発生しうる問題です。詳細は別記事にまとめています。

1日で完走できた要因

1. ステージごとの明確なゴール

各ステージの完了条件が明確なため、「今どこにいるか」「次に何をすべきか」が常に分かります。

2. テスト先行による手戻り削減

テスト設計を実装前に行うことで、実装中に「この関数のインターフェースどうしよう」と迷う時間がゼロになります。

3. 仕様変更を恐れない構造

仕様変更が発生しても、要件定義ドキュメントを更新すれば、影響範囲が明確になります。claudelogでは「マージ → 追記」への変更を、設計フェーズのうちに判断できました。

4. AIとの分業

人間: 要件の判断、仕様変更の意思決定、最終的なコミット実行
AI: コード生成、テストコード作成、ドキュメント整形

まとめ

Spec-Driven Developmentは「ドキュメントを書く手間」ではなく「意思決定を記録する仕組み」です。claudelogの開発では、途中の仕様変更（マージ → 追記への簡素化）も設計ドキュメント上で追跡でき、1日という短期間でも迷わず完走できました。

特にAI駆動開発では、各ステージの成果物がそのままAIへの指示書になるため、人間の意図が正確に伝わります。「要件定義 → 設計 → テスト設計 → 実装 → テスト」の流れを1日で回せるのは、AI時代ならではのSpec-Driven Developmentの威力です。