0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 1 year has passed since last update.

@panshaka30

Claude Codeが上手く使えず苦労している(進行形)

0
Posted at

はじめに

私は業務でAWSのインフラ設計をすることが多く、アプリケーションについてはほぼノータッチの人生を歩んできました。
しかし、生成AIという強力なツールを使うことで、ノータッチのアプリケーション部分について触ることができるのではないかと思ってつい最近少し触り始めてみました。
ところが全然上手くいかず、先人たちの知識を見ながら上手く使えるように四苦八苦していて、悩んでいる最中ですが解決までできればいいなと思って、進行中のことを綴ります。

環境

以下の環境を使っていて、環境構築自体はネットの情報で特に困りませんでした。

  • Mac Book Air
  • Claude Code (Maxプラン)
  • (MCP：AWSの業務が多いのでAWS関連のMCPとObsidianのMCPのみを利用。)

やろうとしていること

  • Strands Agentsを用いてエージェント開発。ドキュメント作成やドキュメントレビューを実施するエージェントを作成を試みている。
    • イメージは以下。（これもClaude Codeで作成しました。）

苦労している点

私が直面した苦労点としては以下です。

  • 思っている以上のことを実装されて混乱する
    • 知らぬ間にフォールバック用の実装をしている
  • 知らないことを知っているものとして勝手に実装し出す
    • Strands Agentsを用いて実装を依頼したところ、わかっているふうに返答してきたので安心をしていたところ、全く関係ない実装で動かそうとしていた
  • 良かれと思ってドキュメントを量産する
    • 開発したものについて質問したら、それに関するドキュメントを量産する
  • (意外に)一つのドキュメント内で整合性を取らずに作成する
    • 実装ガイドに開発するコードの構成を記載したが、その直後に構成外のコード案を記載していた
  • 動作確認を仮想環境(venv)を使わずに実施していた
  • 勝手に判断して
    • requirments.txtの書き方が悪く古いバージョンをインストールしており、最新ドキュメントを参照した書き方にしても動作せず、バージョンの問題を考慮することなく勝手に実装を書き換える

個人的に考えているポイント

  • そもそも生成AIへの依頼の仕方がよくない（プロンプトエンジニアリングがうまくない）
    • 苦労している点のうち、適切にプロンプトで指定すれば良いことが明記できていない。MVPとして余計な実装をしないや定義していないドキュメントは作らない・作るにしても暫定的な格納先を決める、などのこちらの想定していることをプロンプトとして指示したりルール設定が必要...なのだと思っている。
  • Claude Codeの設定や周辺ツールを使いこなせていない
    • 機能をしらないので、設定などでカバーできることができていない。

対応予定の策

とりあえず、以下二点をやってみます。

  1. Claudeのメモリを使ってみる
    • こちら
    • CLAUDE.mdファイルに守ってほしいことを記載することでルールとして守ってくれるようなので、気になる点はどんどん記載していきたいと思います。ユーザーメモリ(~/.claude/CLAUDE.md)とプロジェクトメモリ(./CLAUDE.md)があるようですが、基本的にはユーザーメモリのレベルで直して欲しい点なので、そのレベルで使ってみたいと思います。開発ごとの細かいものがあればプロジェクトメモリレベルで使ってみたいと思います。
      めっちゃ
  2. 新しいものについては適切に情報をインプットする
    • Strands Agentsは新しいのものであり更新も頻度良く行われているので、使いたい機能などがあるときは適切に情報を伝えて使う

参考

Claude Desktopで相談して作ってもらったユーザーメモリ用のCLAUDE.mdファイル

Python Development Standards

Dependency Management

  • MUST: Only include actually used libraries in requirements.txt
  • MUST NOT: Specify version numbers in requirements.txt unless absolutely necessary
  • RATIONALE: Keep dependencies minimal and flexible for easier maintenance

Example:

# Good ✅
boto3
requests
fastapi

# Bad ❌
boto3==1.26.137
requests>=2.28.0,<3.0.0
pytest  # If not used in production code

Virtual Environment Policy

  • MUST: Always use venv for Python development and testing
  • MUST: Create venv before any package installation
  • MUST: Activate venv for all development work

Standard workflow:

# Always start with:
python -m venv venv
source venv/bin/activate  # On Unix/Mac
# or
venv\Scripts\activate  # On Windows

# Then install dependencies:
pip install -r requirements.txt

Documentation Philosophy

Documentation Control

  • MUST NOT: Create additional documentation beyond initial definitions
  • MUST: Use temporary/ directory for any supplementary documents
  • PRINCIPLE: Single source of truth - avoid documentation proliferation

Directory structure for temporary docs:

project/
├── README.md           # Primary documentation only
├── temporary/          # All additional docs go here
│   ├── notes.md
│   ├── research.md
│   └── drafts/
└── src/

Documentation Rules

  • Keep documentation in code via docstrings and comments
  • Avoid creating multiple versions of the same information
  • If additional documentation is needed, always use temporary/ directory
  • Never commit temporary documentation to version control

Error Handling Philosophy

No Fallback Implementation

  • MUST NOT: Implement fallback mechanisms that hide errors
  • MUST: Let errors fail fast and clearly
  • MUST: Provide descriptive error messages

Error Implementation Pattern

# Good ✅ - Clear error propagation
def process_data(data):
    if not data:
        raise ValueError(f"Data cannot be empty, received: {data}")
    
    try:
        result = external_api_call(data)
    except RequestException as e:
        # Re-raise with context, don't fallback
        raise RuntimeError(f"API call failed for data {data}: {str(e)}") from e
    
    return result

# Bad ❌ - Hidden fallback
def process_data(data):
    try:
        result = external_api_call(data)
    except:
        result = default_value  # Don't do this
    return result

Error Reporting Standards

  • Include context in error messages (what failed, with what input)
  • Use appropriate exception types (ValueError, TypeError, RuntimeError, etc.)
  • Never use bare except clauses
  • Always preserve the original exception chain with from e

Example error patterns:

# Input validation
if not isinstance(input_data, dict):
    raise TypeError(f"Expected dict, got {type(input_data).__name__}: {input_data}")

# Missing required data
if 'required_field' not in config:
    raise KeyError(f"Configuration missing 'required_field'. Available keys: {list(config.keys> ())}")

# External service errors
except boto3.exceptions.ClientError as e:
    error_code = e.response['Error']['Code']
    raise RuntimeError(f"AWS operation failed with {error_code}: {e.response['Error']> ['Message']}") from e

General Development Principles

Code Quality

  • Write code that fails loudly when something is wrong
  • Prefer explicit over implicit behavior
  • Don't guess or assume - validate and verify

Testing Approach

  • Test for expected failures, not just success cases
  • Ensure error messages are helpful for debugging
  • Don't mock away error conditions

Development Workflow

  1. Set up venv first
  2. Install only necessary dependencies
  3. Write code that fails fast with clear errors
  4. Document in code, not in separate files
  5. Use temporary/ for any exploratory documentation

Command Preferences

Standard Python Commands

# Virtual environment (always use these)
python -m venv venv
source venv/bin/activate

# Dependency management
pip install -r requirements.txt
pip freeze  # Only for checking, not for saving

# Running code
python -m module_name  # Preferred over python file.py

Git Workflow

# Don't commit
git rm -r --cached temporary/  # Remove temporary docs
git rm -r --cached venv/       # Never commit venv

Important Notes

What NOT to do

  • Don't create "backup" or "v2" documentation files
  • Don't implement try/except blocks that return default values
  • Don't add development dependencies to requirements.txt
  • Don't work outside of virtual environments
  • Don't hide or suppress errors

What TO do

  • Keep requirements.txt minimal and version-free
  • Always use venv for isolation
  • Let errors bubble up with context
  • Use temporary/ directory for exploratory work
  • Write self-documenting code

Philosophy Summary

"Fail fast, fail clear, keep it minimal, keep it isolated"

  • Dependencies: Minimal and flexible
  • Environment: Always isolated with venv
  • Documentation: Single source of truth
  • Errors: Visible and informative
  • Code: Explicit and straightforward
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?