自己紹介
はじめまして、株式会社 MG-DX で Web フロントエンドエンジニアをしている植木です。
オンライン診療・服薬指導サービス「薬急便」の開発に携わっており、主に Web フロントエンド開発と Flutter アプリケーション開発を担当しています。現在は通常の開発業務のほか、AI を活用した開発環境の構築も兼務しています。
はじめに
本記事では、2025 年 7 月の導入から 12 月までの約 5 か月間で、Claude Codeをどのように整備してきたかを振り返ります。
この記事の構成
- Phase 1: Claude Codeの導入
- Phase 2: ガイドラインへの分割
- Phase 3: Commandを知る
- Phase 4: Agent Skills の導入
- Phase 5: Rules と Skills への完全分離
- Phase 6: 別のAI Agent対応
想定読者
- Claude Code の導入を検討している方
- 既に Claude Code を使っているが、運用方法を模索している方
- AI 支援開発の標準化を目指すチーム
Part 1: Claude Codeの導入
2025 年 7 月、プロジェクトに Claude Code を導入しました。それまでは、Copilotで補完に使うぐらいで、Agentを使った開発はしていませんでしたが、x界隈を見ていると、盛り上がっているので使いたいと思っていたところに、全社で申請すれば使えるとなり、そこに乗っかり使い始めました。
当時のドキュメント構成は非常にシンプルでした。README.mdやテストガイドラインは昔、まとめていたものがあったので、それを頼りにCLAUDE.mdを作成しました。この作成も、Claude Codeに頼りつつで、AIに任せればいいんだと知ったのがこのタイミングでした。
CLAUDE.mdにとにかく詰め込むということで、プロジェクト概要、技術スタック、開発コマンド、コーディング規約、テストガイドライン、CI/CD 対処法、PR レビュー観点、Issue 対応フロー、API 生成手順——すべてを書いていました。この頃は、書けるだけ書いたら読み込んでくれるだろうで運用していました。
Phase 2: ガイドラインへの分割
トークンが限界に来ることが多く、どうにかならないかと調べていたところで、コンテキストという概念を知り、CLAUDE.mdに詰め込み過ぎていたことに気がつきました。
PR レビューガイドライン
最初に分離したのは、PR レビューのガイドラインでした。コードレビューの観点、禁止事項を独立したファイルに移しました。GitHub Actionsでclaudeのレビューを実行するため、その時に読んでもらうように整備しています。
AI駆動開発
同じく、GitHub Actionsでclaudeを動かして、PM自身がIssueを書いてくれたら、働いてくれたらいいなと、Issueに対するワークフローを作りました。 Issue テンプレートの使用方法、対応時の禁止事項、実装手順のチェックリストなど、Claude Code Actions で実行するためのガイドラインとして作成しました。
Phase 3: Slash Commandを知る
ここまではコミットする、PRを作成するは毎回、文章で指示していたのですが、手順が統一されていない、テストを実施しないなど、バラバラでここを統一できたらいいなと思っていたところ、Slash Commandの存在を知りました。コミットまでの手順、PRの手順を整備して、テストの実行、コミットログの記載方法などを詳細に決めました。
これまで、コミットは各自に任せていて、1行で英語で書くみたいな文化でやっていたり、バラバラだったのですが、PRを作成する上で、コミットログは重要な情報になるので、AIによって詳細に書いてもらうようにしました。
同じく、PRの作成もそれに倣って、充実した内容になり、人が書くよりもわかりやすいPRになりました。
コミットやPR以外だと、ローカルでのセルフレビューや、コミットをまとめるコマンドを作っています。
Phase 4: Agent Skills の導入
Agent Skillsは2025 年 10 月にできたようですが、使い出したのは12月です。標準仕様になったところで知り、別ファイルでまとめていた仕様をちゃんとskillとして作成しました。
implementation-guideは、コーディング規約に特化した Skill です。実装ワークフローの確認、既存コード調査、品質チェック実施を支援します。機能実装、バグ修正時に使用します。
design-docは、設計ドキュメント作成に特化した Skill です。設計ドキュメントを書くとき、テンプレートの使用方法、見積もり基準、フロントエンド観点——設計時に必要な情報だけが提供されます。
test-coverage-analyzerは、テスト用で、テスト戦略の改善、TDDの支援、テストガイドライン遵守確認に使用します。
CLAUDE.mdにまとめていた内容を移したので、これでコンテキストの消費が抑えられたらなぁというので入れました。効果はあまり感じられてないですが、開発の体験自体は変わってないので、大丈夫なのかなと思っています。
Phase 5: Rules と Skills への完全分離
Skillsもルールまで入れると内容が盛り盛りになるので、ドキュメント構造を再設計し、.claude/rules/と.claude/skills/で分けました。
.claude/rules/の構成
.claude/rules/には、6 つのガイドラインを配置しました。
- implementation-guide.md : コーディング規約、TDD、テストガイドライン
- design-doc-guide.md : 設計ドキュメント作成ガイド
- specification-guide.md : 仕様書管理ルール
- spec-validation-guide.md : 仕様検証ガイドライン
- issue-handling-guide.md : Issue 対応の原則と禁止事項
- test-coverage-guide.md : テスト品質とカバレッジガイドライン
Phase 6: 別のAI Agent対応
現在は、ベースとしてClaude Codeを基準にして揃えたのですが、CursorやCodexを使う人もいるので、同じルールを適用できないかとそれぞれの仕様を確認し、できる範囲で合わせるようにしています。
シンボリックリンクによる統合管理
Agent Skillsは標準化されているので、それぞれ.cursorや.codexにシンボリックリンクを貼って対応しました。AGENTS.mdもCLAUDE.mdのシンボリックリンクになっています。
最初にslash commandでコミットやPRをコマンドで作成していましたが、Agent Skillsに変更し、Claude Code以外でも使えるようにしました。
振り返りと学び
5 か月で得られた教訓
CLAUDE.md は分厚くするのではなく、システムプロンプトの一部として機能させる
Claude Code は、会話開始時に CLAUDE.md を自動的に読み込んで、システムプロンプトの一部として組み込みます。この特性を理解すると、CLAUDE.md の役割が明確になります——詳細なルールを詰め込むのではなく、プロジェクトのアーキテクチャ概要、ワークフロー、ツール連携といった「文脈」を提供し、各専門ガイドへの導線を示すことに集中すべきです。
スラッシュコマンドは「作業の品質を揃える仕組み」として機能する
単なる省力化ではなく、人によって手順が変わらない運用を実現すると、AI 支援の効果が安定して出せるようになります。Claude Code の分析能力を最大活用し、安全性チェックで事故を未然に防ぎ、GitHub API 連携は正しい使い方を明文化することで、安定した運用が実現できました。
Claude Code 公式ベストプラクティスに準拠する
.claude/rules/と.claude/skills/という標準構造に従うことで、将来的なツールのアップデートにも対応しやすくなります。
シンボリックリンクを活用し、複数 IDE での統合管理を実現する
同じルールを複数の場所で管理する無駄を省き、メンテナンス負荷を大幅に削減できます。
おわりに
Claude Codeを使うまでは、自分でコードを書くもので、AIはただの補完ツールと思っていました。現在は、自分でコードを書くことはほとんどなくなりました。ルールや仕様を整備し、メンバーに知見を共有することで、チームの開発スピードの向上ができたんじゃないかなと思っています。
最初の頃は、自分で使うために色々と整備していたのですが、メンバーに伝えると、かなり好評で、Claude Codeは全員で使うようになりました。他のチームにも概念は持ち込めるなと、バックエンドにもPRを投げて整備していました。今でも気になったところは細かく整備し直したり、より効率を上げられるようにするにはどうしたらいいかを試行しています。
次に、興味あるのはテストの自動化で、文章形式の内容でテストができないか、いろいろと調べています。まとまったら、記事を書きたいと思っています。
参考情報
- Claude Code: Best practices for agentic coding - Anthropic 公式のベストプラクティス
- CLAUDE.md - Claude Code Docs - CLAUDE.md の公式ドキュメント
- Skill authoring best practices - Agent Skills 作成ガイド
- Agent Skills - Claude Code Docs
Discussion