AIプロダクト開発におけるClaudeCode活用ガイド

Transcript

1. AIプロダクト開発における Claude Code 活用ガイド AIプロダクト開発における Claude Code 活用ガイド 音声文字起こしプロダクト SecureMemo での FE / BE の実践と「育てる資産」戦略 2026-09 / nishika inc. nishika inc. 1
2. AIプロダクト開発における Claude Code 活用ガイド 自己紹介 シニアアプリケーションエンジニア SecureMemo（オンプレ文字起こしプロダクト）の開発 FE / BE を担当 開発現場のいちメンバーとしての取り組みをお話しします。 nishika inc. 2
3. AIプロダクト開発における Claude Code 活用ガイド このセッションの狙い（アジェンダ） 1. 共通の土台 — Claude がルールに従う仕組み（FE/BE 共通） 2. FE の実践 — クリーンアーキ × Riverpod のスキル/フック 3. BE の実践 — モジュラーモノリスのガードレールと依頼のコツ 4. 資産戦略 — ルール・スキル・フックを「育てる」考え方 nishika inc. 3
4. AIプロダクト開発における Claude Code 活用ガイド 前提となる2つのプロジェクト SecureMemo — 当社が開発する日本語音声の文字起こしプロダクト。FE / BE の2リポジトリで構 成。 SecureMemo-fe SecureMemo-be 種別 Flutter デスクトップアプリ 日本語文字起こしサービス基盤 スタック Dart / Riverpod 3 / Freezed / drift FastAPI / TaskIQ / PostgreSQL / RabbitMQ 設計 クリーンアーキテクチャ bounded context のモジュラーモノリス 設計の正本 .claude/rules/* docs/ （01–09） スタックは違うが、Claude を「設計に従う実装者」として運用する構造は共通。 nishika inc. 4
5. AIプロダクト開発における Claude Code 活用ガイド 共通の土台 ① Claude が読むルールの階層 Claude Code はセッション開始時に設定を自動ロードする。 ファイル 役割 CLAUDE.md プロジェクト全体の指針・コマンド・構造・禁止事項 .claude/rules/*.md レイヤー/contextごとの詳細規約・レビュー観点 CLAUDE.local.md 個人ローカル設定（日本語返信・計画保存先など） これらは「お願い」ではなく OVERRIDE 指示。 デフォルト挙動より優先される。規約を変えたいときはまずここを直す。 nishika inc. 5
6. AIプロダクト開発における Claude Code 活用ガイド 共通の土台 ② 開発フロー 1. 依頼を出す ↓ Claude が rules を読み、設計に沿って計画（Plan Mode） 2. 実装（Edit / Write） ↓ ← 編集ごとに hook が自動実行（format / lint / 行数） ↓ ※ hook ＝ Claude の編集のたびに自動実行されるチェック処理 3. 品質ゲートを Claude 自身が回す（lint / 型 / テスト） ↓ 4. レビュー（スキルで観点を網羅） ↓ 指摘を修正 5. 人が commit / push を判断 ←─ pre-commit が最後の砦 人は「設計判断」と「レビュー」に集中、機械的検証は委譲する。 nishika inc. 6
7. AIプロダクト開発における Claude Code 活用ガイド 共通の土台 ③ 自動ガードレール Claude が逸脱しても自動で止まる三段の仕組み。 FE BE 編集ごと (hook) dart format ＋ トークン検査 ＋ 永続化ガード ruff format/check ＋ 400行ゲート commit前 変更 .dart に dart analyze ＋ トークンSSoT差分 ＋ ライ センス ruff/ty/行数/import境界/proto差分/ライセ ンス テスト全件 CI（Merge Queue）で flutter test pre-push で pytest 置き場所は違う（FE=CI / BE=ローカル）が、どちらもテスト全件を通らないと先へ進めない。 「通ったはず」ではなく、ゲートの出力が客観的証拠。完了報告はテスト実行出力とともに行うの が規約。 nishika inc. 7
8. AIプロダクト開発における Claude Code 活用ガイド FE の実践 ① ルールをパスに紐づける 規約は1枚の巨大ファイルにせず、レイヤー・関心事ごとに16ファイルへ分割。全部は読ませない。 # .claude/rules/data-database-migration.md の先頭 paths: - "lib/data/services/database/**/*.dart" # ← このパスを編集するときだけ - "drift_schemas/**" # このルールが自動ロードされる 編集するファイル 自動で効くルール lib/domain/models/** ドメインモデル（不変クラス・API モデル分離） lib/ui/**/view_models/** 状態管理の責務分離（Controller / State / Helper） lib/data/services/database/** DB マイグレーション手順のチェックリスト 設計のレイヤー構造 ＝ ルールの分割単位。触る場所が、守るべき規約を決める。 漏らすと過去バージョンのユーザーの DB が壊れる領域ほど、厚いルールをその場所限定で。 nishika inc. 8
9. AIプロダクト開発における Claude Code 活用ガイド FE の実践 ② スキルでレビューを畳む スキル ＝ 繰り返す作業手順を /コマンド 一発で呼び出せる形にパッケージ化したもの。 PR番号を渡せば GitHub PR を、省略すればローカル変更をレビュー。 スキル 内容 /rv-full 5観点（Lint+ルール+Perf+Sec+UI）並列。 --quick で軽量 /rv-rules ( -x3 ) アーキ/Riverpod/UIルール準拠（×3で見落とし防止） /rv-perf /rv-security /rv-ui 性能・秘匿/通信・デザイン平仄を個別に /format-and-lint /pr-description 整形・解析／PR説明欄の自動生成 いずれも明示実行のみ起動（ disable-model-invocation ）。 コミット前は /rv-full --quick 、PR前は /rv-full が目安。 nishika inc. 9
10. AIプロダクト開発における Claude Code 活用ガイド BE の実践 ① 配置とマイグレーションは規約に委譲 配置を任せる — architecture.md の配置決定フローに従わせる 「リアルタイム availability にフィルタ条件を追加して」 → context 判定・置き場所決定・ public.py 再エクスポートまで自動 context 境界は「お願い」ではなく契約 uv run --no-sync lint-imports # 依存マトリクス通りかを検証（pre-commit でも実行） DB マイグレーション — migrations/versions/ は手書き禁止 Claude にやらせるのは infra/entities.py のエンティティ定義まで 生成は alembic revision --autogenerate -m "..." （改変禁止） nishika inc. 10
11. AIプロダクト開発における Claude Code 活用ガイド BE の実践 ② 人が握る安全装置 危険な編集は hook が機械的に拒否（PreToolUse） マイグレーションの手書き・行数猶予リストへの追記・API ベースラインの直接編集 拒否理由が Claude に返り、Claude 自身が正しい手順に切り替える hook はリポジトリにコミット — 全員・毎回、同じように効く 破壊禁止の不変条件（外部仕様） HTTP API のパス/形状・DBスキーマ・配布物の名前/引数・設定JSON API回帰は openapi_baseline.json 差分で検知 破壊的・外部公開・不可逆な操作は Claude に握らせない。 これらに触れる変更は、まず設計の是非を人が判断してから。 nishika inc. 11
12. AIプロダクト開発における Claude Code 活用ガイド ここまでのまとめ — 役割分担 機械に委ねる（hook / pre-commit / linter） 整形・静的解析・行数・import境界・テスト実行 → 主観の入らない品質は人が見ない 規約に委ねる（ルール / スキル） 配置・レビュー観点・マイグレーション手順は明文化して従わせる → 「毎回説明する」を「一度書く」に変える 人が担う 設計判断とレビュー ／ 外部仕様の不変条件 ／ commit・push の判断 人に残るのは「判断」だけ。ここからが本題 —— その判断を毎回払うか、資産に積むか。 nishika inc. 12
13. AIプロダクト開発における Claude Code 活用ガイド 資産戦略 ① なぜ「育てる資産」なのか AI への指示には2種類ある。 使い捨ての指示 — その場のチャットで完結（履歴に消える） 資産化された指示 — .claude/ に書かれ、全員・毎回効く 同じ指摘を毎回チャットで言うのは、毎回コストを払うこと。 一度ルール化すれば、以後ゼロコストで全員に強制される。 Claude への指示は「複利で効く資産」になり得る。 資産に積むか、毎回支払うか —— それが分かれ道。 nishika inc. 13
14. AIプロダクト開発における Claude Code 活用ガイド 資産戦略 ② 3レイヤーと「暗黙知の昇格」 資産 蓄えるもの 効く相手 ルール ( rules/ ) 設計判断・規約・禁止事項 実装方針・レビュー観点 スキル 繰り返す作業手順 作業の再現性・属人化解消 フック 客観的に測れる品質ゲート 逸脱の機械的検知 チャット指摘 ──(2回繰り返したら)──▶ rules/ に明文化 ──(客観判定できるなら)──▶ hook / pre-commit で強制 目安は 「繰り返す指摘はルール、繰り返す手順はスキル、繰り返す確認はフック」。 nishika inc. 14
15. AIプロダクト開発における Claude Code 活用ガイド 資産戦略 ③ 資産は「回る」— 人が抜けても止まらない 資産化の見返りは「次から人が言わずに済む」だけではない。 人の代わりに Claude 自身が直すループが立ち上がる。 ＜人が入れるスイッチ — 一度だけ＞ その指摘を、規約とフックにする ＜以後は毎回・秒単位、人は関与しない＞ Claude が編集 → hook が拒否 → 拒否理由がそのまま返る → Claude が手順を直す → 通るまで繰り返す 実例 — 行数：「長すぎる」を一度だけ規約「400行以内」＋フックにした → 以後は Claude が自分で分割する。いま、行数を見ている人間は一人もいない。 移せるのは中身ではなくやり方。「編集のたびに検査する」体制を BE から FE へ広げた。 nishika inc. 15
16. AIプロダクト開発における Claude Code 活用ガイド 資産戦略 ④ アンチパターン（腐る兆候） 更新されないルール → 実態と乖離し、Claude が誤誘導される 強すぎる制限 → 正当な作業まで止まり、回避が常態化 スキル乱立 → どれを使うか分からない チャットで毎回同じ指摘 → 資産化のサインを見逃している ルールは書くだけでなく、消す・直すまで含めて運用する。 「使われていない／守られていない」資産は負債になる。 効果の指標は「人が同じ説明を繰り返していないか」。 nishika inc. 16
17. AIプロダクト開発における Claude Code 活用ガイド 明日からの実践チェックリスト 個人 [ ] チャットで同じ指摘を2回したら → ルール化を検討 [ ] 決まった手順を3回やったら → スキル化を検討 [ ] 「機械で測れるのに人が見ている」ものを探す → hook 候補 チーム [ ] レビューで出た恒久ルールを PR 内で .claude/ に還元 [ ] FE / BE で効いた運用を相互に移植 [ ] 月次などで古いルール・未使用スキルを棚卸し nishika inc. 17
18. AIプロダクト開発における Claude Code 活用ガイド まとめ Claude は「設計に従う実装者」、人は「設計判断とレビュー」 ルールは明文化 ＋ 機械強制（hook / pre-commit / linter） 規約化できる判断は委譲し、壊せないものは人が守る 気づきはその場で .claude/ に還元し、資産として育てる 使うほど強くなる仕組みを、チーム全員で積み上げる。 nishika inc. 18