同じバグを3回踏んでから、ようやくノートを取り始めた話

AIエージェント開発の初心者向けガイド。プロンプトとの違い、Skills・自動化との区別、必要なファイル構成を解説。Claude Codeを使ったPRDレビューエージェントの実装例とテスト・改善ループを具体的に説明。複雑なマルチエージェント構成ではなく、明確な仕事 1 つから始める方針を提示。

Claude Agent Skills が増えると参照の腐りとスキル同士の発火被りが静かに発生する問題に直面。参照整合チェック、frontmatter 検証、description の類似度判定（Jaccard）を組み合わせた skills-lint を開発し、毎 PR で機械的に検出・CI を落とす仕組みを構築。依存なしで npx で実行可能。

Claude Code の初心者が陥りやすい「動くが想定と違う」という問題は、指示に含まれない暗黙の判断を Claude が仮決定することが原因。superpowers 拡張を導入すると、brainstorming・計画・TDD・レビューを自動で挟み、実装前に要件と判断を洗い出し、小さなタスクに分割して進めることで、この問題を回避できる。Sonnet と Opus をコスト効率よく組み合わせる設定も紹介。

ChatGPT のシェア低下と Claude・Gemini 台頭が報じられるが、市場全体のシェアや総合ベンチマーク順位は複数タスク・複数ユーザーの平均値であり、個人の特定タスクにおける最適モデル選択を保証しない。タスク・評価軸を固定し同一プロンプトで複数日比較する小規模評価ハーネスを個人で用意することが、市場ランキングに振り回されずモデルを選ぶ実務的な解になる。