ClaudeCodeの歩き方2（ナレッジを随時更新)

意図

ClaudeCodeを使っていると意図通りに動作してくれないことがよく起こる。感覚的にはchatgpt 3.5ぐらいの性能の低さを感じています。

(2025/09/14) 性能劣化の情報あり
https://blog.lai.so/news-20250912/

そこで、私がClaudeCode(sonnet4)を罵倒しながらも得たナレッジを、
自分のメモ代わりにここに更新しています。

尚開発者ならもっとスマートな解決方法があると思います。
その場合はコメントで教えて下さい。

私とClaudeCodeとの闘争（恥ずかしいやり取り）

ドキュメントに保存したと言いながらない

指示を無視して勝手な事を開始

質問しているのに、勝手に実装を開始

#仕事を誤魔化している

ISSUE

• 0001: 同じプロジェクト内で追加機能開発をしていると環境が散らかる
• 0002: ドキュメントを読んでいないためにトンチンカンな事をする
• 0003: 勝手に実装を始めてしまう
• 0004: 勝手に余計な機能を設計・実装してしまう
• 0005: 意図しない要件定義と設計をしてしまう
• 0006: 機能追加した際、新しいスクリプトを一から作ってしまうことで、またバグが入る。
• 0007: ベストプラクティスに従い、TDDで実装するとモックが出来た段階でテストOKと言い張る。
• 0008:　思っていたような要件定義や設計が出来ない。
• 0009:　古い設計や実装にしてしまう
• 0010:　ドキュメントをキチンと理解出来ていない
• 0011: 実装計画や設計書をみていないと思える挙動
• 0012: 問題一つ見つけたら、その問題飲み解決する

Solution

• 0001: python系はuvで管理するように指示を行い、ドキュメントに記載しているか確認する
• 0002: CLAUDE.meやREADMEに関連ファイルの存在を書き込むように指示をする
• 0003: プロンプトに〇〇することに集中して　と限定する
• 0004: プロンプトに必要最小限な機能を〇〇してください　と限定する
• 0005: プロンプトに不明点は私に逐次質問してください　を入れる
• 0006: 対処方法01: プロンプトに〇〇ファイルをコピーした上で修正・追加をしてください　と指示する
• 0006: 対処方法02: こまめにSolution:0002を行い、プロンプトに　ドキュメントに更新していない事項を確認した上で、ドキュメントに変更点を追加・更新してください
• 0007: 実データを使って検証をしてみる。結果を元に疑わしい点を指摘するとClaudeCodeは白状する
• 0008: Chatgptやgeminiのディープラーニングとシンキングを使って要件候補を出力したものをPDF化して、claudecodeに渡す
• 0009: 設計・実装計画段階でプロンプトに 〇〇についてはcontext7を調査して、仕様やベストプラクティスを深く理解してください とcontext7を使うように指示する
• 0010: 対処01 : プロンプトに深くよく理解してください　を入れる
• 0010: 対処02 : MCPのserenaやSequentialThinking を参照するように指示する
• 0011: @{設計書・計画書}　を指定して指示をする
• 0012: 同じプロンプトをもう一回実行してエラーがなくなるまで繰り返す。/sc:analyze　がよい。

サンプルで話者分類して文字起こしするための前処理を作ってみたときのプロンプト

まずはchatgpt5で要件と概要設計を詰めるためのプロンプト

プロンプト

貴方は優秀なAIエンジニアです。

以下の要件を実現するための最適なアーキテクチャーを選択してください。
不明点は質問してください

### 実現したいこと
音声ファイルから話している声の特徴から話者を分類して
話者を特定した上で文字起こしをしてください。

### 前提条件
- OS: ubuntu24.04.3
- CPU: intel 12世代CPU 12 core
- メモリ: 64GB
- SSD: 800GB
- GPU: nvidia RTX 3060 6GB

### 音声データ要件
- フォーマット形式: mp4,m4a,wav
- マイク一つから音声が集音されている
- 話者は2名から8名
- 声が重なっている

### 出力イメージ
[話者A] : 2025:09:05:00 : こんにちは
[話者A] : 2025:09:05:00 : こんにちは

概要設計資料に基づいてClaudeCodeで設計

ここのポイントは理解すべきドキュメントと、作業結果を保存するドキュメントを明確に指定している所です。
これをしないとドキュメントを読まなかったり、更新しなかったり、ドキュメントを作ってもどこからも参照されないものを創ってしいます。

/sc:design @docs/音声前処理パイプライン設計.pdfを深くよく理解した上で設計してください。
- 開発はuvに追加パッケージを入れてください。環境名は「hoge」です。
- 使用するアーキテクチャーやアルゴリズム・ツールは、context7を調査し、仕様やベストプラクティスを理解した上で設計してください。
- 作成した設計ドキュメントは「docs/v1.0_音声前処理パイプライン設計.md」として保存してください。
- 「docs/v1.0_音声前処理パイプライン設計.md」を元にCLAUDE.meを更新してください。またファイルへの参照も記載してください。

設計に基づいたTDD実装計画

ここのポイントは、勝手に実装しないようにドキュメント化に徹している事。
実装時にエラーが大量発生したときにもトレースしやすいようにデバッグログ機能を入れること
疑似成功させないためにフェールバックさせず、例外を発生させること

/sc:workflow @docs/v1.0_音声前処理パイプライン設計.md を深くよく理解した上でTDDで実装計画を立案してください。
- 再度context7で使用するアルゴリズム・アーキーテクチャーの仕様やベストプラクティスを確認した上で実装計画を立ててください。
- フェールバックはせず、必ずエラーを出力するようにしてください。
- スクリプト実行時にデバッグしやすいようにログを出力するオプションを追加してください。
  ログはlogsフォルダに保存してください
- 作成した設計ドキュメントは「docs/v1.0_音声前処理パイプライン_TDD実装計画.md」として保存してください。
- 「docs/v1.0_音声前処理パイプライン_TDD実装計画.md」を元にCLAUDE.meを更新してください。またファイルへの参照も記載してください。

実装は段階的に実施

ここでのポイントはドキュメントをベースとしてどのフェーズを実装するかは指示しないこと
ClaudeCodeがドキュメントを見ながらPhase毎(複数一度に実施もある)に実装してくれる
全部の実装がおわるまで下記プロンプトを繰り返し実行する

/sc:implement @docs/v1.0_音声前処理パイプライン_TDD実装計画.md を深くよく理解した上で実装してください。
- 実装後は「docs/v1.0_音声前処理パイプライン_TDD実装計画.md」に状況を更新してください。
- またCLAUDE.meも確認し、必要あれば更新してください。

あとは、実行して、トラブルシューティングするか修正するかを繰り返します。

今まで前全振れてませんでしたがローカルリポジトリに保存をさせる/sc:git commit "message" は皆さんの流儀で行ってください。

機能追加するときの設計

(また事前にchatgptで追加機能の概要設計をしてもらっています)

ここでのポイントは、既存機能を破壊しないように、ドキュメントもスクリプトも分けることです
これをしないで何度痛い目を見たことか。
これ以降は基本同じ事の繰り返しです。

/sc:design @docs/v2.0_Diarization設計.mdを深くよく理解した上で追加機能を設計してください。}
- 完全に別機能となるため、既存機能とは分離して設計してください。データ受け渡しは前処理の出力ファイルを通して行います。
- 0.前処理の出力ファイルは/home/workspaces/nakanishi_ai_toText/output_testにあります。
- 開発はuvに追加パッケージを入れてください。環境名は「hoge_Diarization」です。
- 使用するアーキテクチャーやアルゴリズム・ツールは、context7を調査し、仕様やベストプラクティスを理解した上で設計してください。
- 作成した設計ドキュメントは「docs/v2.0_Diarization設計_claude.md」として保存してください。
- 「docs/v2.0_Diarization設計_claude.md」を元にCLAUDE.meを更新してください。またファイルへの参照も記載してください。

最後に

今後Claude,SuperClaudeのバージョンアップでどんどんナレッジが使えなくなって行くとは思うので、後日バージョンも記載していきます。

そして開発者のみなさんに是非私にナレッジを共有して貰えると嬉しいです。