業務で育てたCLAUDE.mdについてのメモ

こんにちは。QA（Quality assurance：品質管理）チームの佐藤です。

この記事は、Supershipグループ Advent Calendar 2025の1日目の記事になります。

TL;DR

• 業務でClaude Codeを使う過程でCLAUDE.mdが使いまわしできそうなレベルで整ってきた
  • CLAUDE.mdへの記述は、Claude Codeが行った
• 最近はClaude Codeとのペアプログラミングで業務が回っている
  • 何度も再実行するプロンプトはClaude Codeがスクリプト化して実行してくれる
• Claude Codeとの約束事がCLAUDE.mdにまとまっている
  • CLAUDE.mdの中身はプログラミングのコードでなく、日本語の文章なので理解しやすい

はじめに

8月の後半くらいから、希望する開発者にClaude Codeが会社から提供されました。
ちょうど新規のプロジェクトに入るタイミングだったので、Claude Codeを使って業務に取り組みました。
それまでは、VS Code + GitHub Copilotという環境が提供されていたので、VS Code + Claude Codeという組み合わせでの作業環境構築に取り組みつつ、プロジェクトを進めます。

Claude Codeに限った話ではないですが、この記事を書いている間も、新しい機能が続々とリリースされていて、1ヶ月前の情報もあっという間に古くなる状況です。この記事は、現時点でのベストプラクティスを提供するというよりは、今年の成果のまとめメモといった趣旨で書き残しています。

CLAUDE.mdとは？

一般的なAIの使用イメージは、Webのインターフェイスから、プロンプトを入力すると、AIがあちこち検索して要約して、答えを表示してくれる…みたいな感じだと思いますが、今回の話は、VS Codeなどで、コードの編集をする作業にAIをエージェント(本人に代わって作業を行う人？)としてジョインし、一緒に働くという感じのイメージになります。上記のイメージの延長で、エージェントを使おうとすると、前回の指示や作業内容などを覚えていないので、「日本語で話して」みたいな指示を毎回することになります。

また、VS Codeと組み合わせて使う理由は、作業の範囲を明確にリポジトリ(ディレクトリ)とすることができるため、関連するコードを認識させ、エージェントがよりプロジェクトを理解した動作をするようにできるためです。

とはいえ、Claude Code on the Webやデスクトップ版のClaude Codeもリリースされていますので、コードの開発が一段落し、データの更新などの定型業務中心のフェーズに移行した場合には、デスクトップ版のClaude Codeの方がお手軽に作業できるかな？とかも思いますので、まだ試していないのですが、来年早々にでも触れてみたいと思います。

CLAUDE.mdには、そのリポジトリでの決まり事やルール、提供作業のマクロ的なものを記述することができ、毎回起動時に参照されて、日本語対応や定型作業などをClaude Codeが理解している状態で作業できるようにできます。

新規のプロジェクトを始める際に、CLAUDE.mdコピーしてきたり、既存のプロジェクトにもってきて「プロジェクトに合わせて最適化して」といった形で再利用できます。GitHubなどのリポジトリに含めてチームで共有することも可能です。

CLAUDE.mdへの記述も、自身で書き込むのではなく、プロンプトで「いまの作業、毎回やるのでCLAUDE.mdに追記しといて」的な指示でClaude Codeが自身で更新し、勝手に育っていきます。

個人的に得たClaude Codeを扱うポイント

• とにかくいろいろ聞きまくる（これできる？こうしたいのだけど…、〇〇とは？）
  • 正式名称があいまいだったり、不明でも、プロンプトに「〇〇みたいなやつできる?」と聞くと、「〇〇はこうしてこうするとできます」みたいな返答が返ってくるので、勉強になったりします。
• 自分で操作したり、コードを書くより正確なので、任せる
  • たった一文字のタイポや全角スペースに気づかず半日潰すことはなくなります。
• 作業の方向性は具体的にこちら側から示す
  • 実装に入る前には、「プランモード」で対話して、具体的な作業内容を確認する
  • 実装を始めて、ちょっと間違った方向に進んでるなと思ったらすぐ停止する
• Gitのコミットやプッシュ・プルリクもClaude Codeに任せる
  • メッセージを詳細に生成してくれるので、自分で手抜きなメッセージを残すより全然有用
  • こちらからマージの報告などをしてあげないと、マージしたプルリクに追記しようとしたりするクセがある
    • おそらくプルリク作成前に確認を促す記述をCLAUDE.mdに追加することで対応できるはず（面倒なのでしていませんが）
    • 手動で操作したほうが早い場合もあるので、そのへんは適宜役割分担する
• こまめにコミットや文書作成をお願いしておくと、あとあと助かったりする（コードを辿るよりラク）
  • 作業ログを残すように、CLAUDE.mdに記述してます。見返すことは今のところありませんが、あとで見返すことができるという安心感が得られます。
• うまくいかなかった場合などは、反省会のような会話もしたりします。
  • 「◯◯の実装、うまく行かなかったけど、〇〇って指示したほうがよかった？」的なことを聞くと、アドバイスが返ってきます。

実際のCLAUDE.md

実際に使っているCLAUDE.mdから、汎用的に利用できそうなところを抜粋して補足説明します。
この記述は、Claude Codeが作成したもので、私は触っていませんが、読むとClaude Codeが理解している規則を把握できるので、指示が出しやすくなります。

# プロジェクト設定

## Claude Code使用時の重要な指示
- **回答言語**: 必ず日本語で回答すること（英語での回答は禁止）
- **出力スタイル**: Explanatory（説明的）モードを使用
  - 実行する操作の理由を明確に説明
  - コードの変更内容を詳細に解説
  - 各ステップの目的と結果を記述

## ドキュメント管理フロー
- ドラフト作成 → レビュー → 本番公開（main）の流れ
- 機能別ドキュメントは`docs/機能名`で分類
- 変更はプルリクエストでレビュー後にマージ

## コミット・PR規則
- コミットメッセージとGitHubのコメントは日本語で記載
- コミットメッセージ形式：`[種類] 変更内容の説明`
  - 例：`[feat] ユーザー認証機能を追加`、`[fix] ログイン時のバリデーションエラーを修正`
- PRタイトルも日本語で記載し、変更内容を簡潔に説明

## 作業ログ管理
- Claude Codeとの会話は作業ログとして`docs-dev/work_log/YYYY-MM-DD.md`に保存・追記
- **重要**: 日付は必ず環境設定の`Today's date`を優先して使用すること（ファイル名や既存の日付に惑わされない）
- 日付形式はYYYY-MM-DD（例：2025-08-14）
- 既存ファイルがある場合は追記、ない場合は新規作成

## ブランチ運用
- main: 公開ドキュメント（直接プッシュ禁止、PRベースで更新）
- docs/*: ドキュメント更新・追加用ブランチ（例：docs/user-auth、docs/api-guide）

## 作業フロー自動化コマンド

### 🚀 作業開始・終了・休憩の自動化
Claude Codeが特定のフレーズを認識して、対応するスクリプトを自動実行します：

**作業開始**:
- フレーズ: `「本日の作業を開始します」`
- 実行: `dev_tools/scripts/start_work.sh`
- 機能:
  - Working Tool起動 (http://localhost:8501)
  - Docusaurusテストサーバー起動 (http://localhost:3000)
  - 本日の作業ログファイル作成/更新
  - Git状態の確認

**作業終了**:
- フレーズ: `「本日の作業を終了します」`
- 実行: `dev_tools/scripts/end_work.sh`
- 機能:
  - 全サーバーの停止 (Working Tool、Docusaurus)
  - 作業ログに終了時刻を記録
  - Git状態の最終確認
  - 未コミット変更の警告表示

**休憩・作業保存**:
- フレーズ: `「ちょっと休憩します」`
- 実行: `dev_tools/scripts/take_break.sh`
- 機能:
  - 作業ログに休憩時刻を記録
  - 変更内容を自動コミット
  - リモートにプッシュ
  - プルリクエストの作成/更新

### 📋 使用例
    ```
    Claude Code> 本日の作業を開始します
    → Working Tool、Docusaurusサーバーを起動、作業ログを準備
    
    Claude Code> ちょっと休憩します
    → 進捗を自動保存、プッシュ、プルリクエスト作成
    
    Claude Code> 本日の作業を終了します
    → 全サーバーを停止、作業ログを更新、最終状態を確認
    ```

## よく使うコマンド
- ドキュメント更新開始: `git checkout main && git pull origin main && git checkout -b docs/更新内容`
- 変更確認: `git status && git diff`
- コミット・プッシュ: `git add . && git commit -m "[docs] 変更内容" && git push origin ブランチ名`
- 手動作業開始: `dev_tools/scripts/start_work.sh`
- 手動作業終了: `dev_tools/scripts/end_work.sh`
- 手動休憩保存: `dev_tools/scripts/take_break.sh`

## バージョン管理
- **バージョン形式**: メジャー.マイナー.パッチ（例：v1.0.0）
- **リリースタグ**: Gitタグでバージョン管理

## コードスタイル
- インデント: 2スペース
- 文字コード: UTF-8
- 改行コード: LF

Claude Code使用時の重要な指示

ここで回答を日本語で行うことを設定しています。出力スタイルは、Claude Codeの機能で、Explanatory（説明的）モードを指定すると、コンソールにエージェントがどういう目的で、何をしようとしているのかの説明文が表示されるようになり、作業経過を監視しやすくなると同時に、知らなかった機能の説明なんかも入るので、理解が深まります。自分で検索しながら半信半疑で「こうかな？」みたいにやっていた時代とは雲泥の差です。ただし、もっともらしい誤った回答をすることもあるので、うまく動作しない時などは、別のAIに同じ質問をしてみるとかの工夫も必要です。

コミット・PR規則

以前はSourceTreeなどのツールを使って、ソースの管理をしていたのですが、コミットの際のメッセージなど簡素な一言で済ませていました。AI経由でプロンプトから「コミットとプッシュして」などの指示で詳細なメッセージも生成してくれているので、おそらく情報共有の点からみても大分品質向上していると思います。

作業ログ管理

最初は日付をよく間違っていたのですが、「日付間違えないように最初に確認するように、CLAUDE.mdに記載しておいて」みたいな話をしたら、以後直りました。たぶん、**重要**の部分を追記したのだと思います。

おわりに

AIを業務で利用するようになったのは、今年の3月くらいからで、まだ一年も経っていませんが、その間に大分ツールが進化して、まだまだこれからも進化しそうなのがちょっと怖くもあり、楽しみでもあります。

途中、1ヶ月くらいClaude Codeが利用できない期間があり、その間はClaude Codeで構築した環境をなんとかGitHub Copilotで再現できないかと四苦八苦していたのですが、Claude Codeが再び利用できるようになり、戻って来ると、絶妙なところで、Claude Codeの方が使いやすいなぁ…というのが個人的な感想です。

とくに、Explanatory（説明的）モードが気に入っていて、なぜそうするのか？みたいな内容をコンソールに出力してくれるので、曖昧だった知識も解像度が上がりますし、間違った動作をしようとしているClaude Codeを事前に制止できたりします。疑問に思ったことは即座にプロンプトで質問し、Claude Codeが間違っていれば修正されます。

ただ、間違ったまま会話で押し通されたこともあるので、そのへんは他の生成AIにセカンドオピニオンを求めるなどの判断が必要になります。そのへんは複数AIに作業分担させることができるツールのニュースなども見かけますので、よさそうなものがあれば試していきたいです。

最後に宣伝です。

Supershipではプロダクト開発やサービス開発に関わる人を絶賛募集しております。
ご興味がある方は以下リンクよりご確認ください。
Supership 採用サイト
是非ともよろしくお願いします。