Issue-Driven AI Development実践編 - kagura-aiで学ぶClaude Code活用法

Last updated at 2025-10-14Posted at 2025-10-06

はじめに

2025年、AI開発の世界では「コンテキストエンジニアリング(Context Engineering)」という新しい概念が注目を集めています。Andrej Karpathyが提唱したこの概念は、LLMに与える情報全体を体系的に設計・管理する学問分野として、プロンプトエンジニアリングを超える次世代の開発手法です。

kagura-aiは、Pythonで開発中のAIエージェントフレームワークです。開発にはClaude Codeを活用し、コンテキストエンジニアリングの原則に基づいたIssue-Driven AI Developmentを実践しています。本記事では、その実装過程で得た知見を共有します。

コンテキストエンジニアリングとは？

学術的定義

2025年7月にarXivで公開されたサーベイ論文「A Survey of Context Engineering for Large Language Models」では、コンテキストエンジニアリングを次のように定義しています:

コンテキストエンジニアリングは、単なるプロンプト設計を超えて、LLMに与える情報ペイロード全体を体系的に最適化する正式な学問分野である。

この論文では、1,400以上の研究論文を分析し、コンテキストエンジニアリングを以下の3つの基礎コンポーネントに分類しています:

コンテキストの取得・生成 (Context Retrieval and Generation)
コンテキスト処理 (Context Processing)
コンテキスト管理 (Context Management)

プロンプトエンジニアリングとの違い

従来のプロンプトエンジニアリングは、LLMへの入力を固定の文字列 C=prompt と見なし、最適なプロンプトを手動で探索してきました。

これに対し、コンテキストエンジニアリングは文脈 C を動的かつ構造化された情報の集合 {c₁, c₂, ..., cₙ} と定義し、これらを組み合わせるアセンブリ関数 A によって最適なコンテキスト C = A(c₁, ..., cₙ) を生成します。

コンテキストには以下が含まれます:

システム指示 (c_instr)
外部知識 (c_know)
ツール定義 (c_tools)
過去の対話からの情報 (c_mem)
ユーザや世界の状態 (c_state)
ユーザからの直近の要求 (c_query)

重要な特性:

動的システム: 静的な文字列ではなく、リアルタイムで構築される
必要に応じて生成: コンテキストは状況に応じて変化する
構造化された管理: 情報を体系的に整理・最適化する

コンテキストエンジニアリングの4つの戦略

LangChainが提唱する実践的なフレームワークでは、コンテキストエンジニアリングを4つの戦略に分類しています:

Write Context: コンテキストウィンドウ外に情報を保存（メモリ、データベース）
Select Context: 関連情報を動的に選択・取得（RAG、検索）
Compress Context: トークン使用量を削減（要約、圧縮）
Isolate Context: コンテキストの分離（マルチエージェント、ワークフロー）

kagura-aiでは、これらの戦略を実装・統合しています。

kagura-aiとは？

Python関数を1行のデコレータでAIエージェント化できる軽量フレームワークです。

from kagura import agent

@agent(prompt="与えられた文章を要約してください")
def summarize(text: str) -> str:
    """テキストを要約する"""
    pass

# 関数を呼ぶだけでLLMが処理
result = summarize("長い文章...")

技術スタック: Python 3.11+ / Pydantic v2 / LiteLLM / Jinja2 / Click

Context Engineeringの実装状況:

✅ Write Context: MemoryManager（3層メモリアーキテクチャ）
✅ Select Context: RAG検索、Memory-Aware Routing
🚧 Compress Context: RFC-024で実装中（Critical Priority）
✅ Isolate Context: Multi-agent基盤、Stateful Workflows

Issue-Driven AI Developmentとは？

Claude Codeを安全かつ効率的に運用するための開発手法で、コンテキストエンジニアリングの原則を実践に落とし込んだものです。次の3原則から構成されます。

1. 出力契約（Output Contract）

すべてMarkdownで出力
作業ログ（差分要約・変更数・既知リスク）を必ず記録
不明点やエラーは推測せず、質問を出して停止

2. スコープ境界（Scope Boundary）

変更許可パスと禁止パスを明示
意図しない変更を防ぐ

3. 安全策（Safety Mechanism）

すべてDraft PRで作成
大規模変更は分割コミット
重大変更は事前承認を必須化

詳細は元記事を参照してください。

kagura-aiでの実践：コンテキスト構造

Issue-Driven AI Developmentの中心にあるのが構造化されたコンテキスト管理です。

ディレクトリ構造 - コンテキストの物理的構造

kagura-ai/
├── CLAUDE.md              # Claude Code必読の開発ガイド
└── ai_docs/               # AI専用ドキュメント群
    ├── README.md          # ai_docs/の使い方
    ├── UNIFIED_ROADMAP.md # v2.0.0〜v2.5.0+ 統合ロードマップ
    ├── NEXT_STEPS.md      # 直近の開発タスク
    ├── coding_standards.md # コーディング規約
    ├── architecture.md     # システムアーキテクチャ
    ├── glossary.md         # 用語集
    ├── CONTEXT_ENGINEERING_ANALYSIS.md  # Context Engineering分析
    └── rfcs/              # 機能仕様（RFC）
        ├── RFC_007_MCP_INTEGRATION.md
        ├── RFC_012_COMMANDS_AND_HOOKS.md
        ├── RFC_024_CONTEXT_COMPRESSION.md
        └── ...

この構造は、コンテキストエンジニアリングの3つの基礎コンポーネントに対応しています:

ディレクトリ/ファイル	Context Engineering役割
`CLAUDE.md`	Context Generation: システム指示の生成
`ai_docs/UNIFIED_ROADMAP.md`	Context Retrieval: プロジェクト状態の取得
`ai_docs/rfcs/`	Context Management: 機能仕様の管理
`ai_docs/NEXT_STEPS.md`	Context Selection: 優先タスクの選択

CLAUDE.md - AIとの契約書

CLAUDE.mdはClaude Codeが起動時に自動的に読み込むファイルです。AIが守るべきルール・方針・禁止事項を明文化した、いわば「AIとのコンテキスト契約書」です。

Claude Codeは、カレントディレクトリから上位階層へと再帰的にCLAUDE.mdを探索して読み込みます。詳細は公式ドキュメントを参照してください。

CLAUDE.mdの構造（Context Assembly）

kagura-aiのCLAUDE.mdは、コンテキストの構成要素を体系的に整理しています:

1. プロジェクト概要（c_project）:

技術スタック
主要機能
開発方針

2. 開発ルール（c_instr）:

### コーディング規約
- 命名規則: snake_case, PascalCase
- 型ヒント必須: pyright --strict準拠
- ドキュメント: Google Style

3. スコープ境界（c_boundary）:

### 絶対に変更してはいけないパス

⛔️ 変更禁止:
- src/kagura_legacy/     # レガシーコード（参照のみ）
- tests/*_legacy/        # レガシーテスト（参照のみ）
- examples/              # Phase 4まで変更禁止
- docs/                  # Phase 4まで変更禁止

✅ 変更可能:
- src/kagura/            # 2.0実装
- tests/                 # 2.0テスト
- ai_docs/               # 開発ドキュメント

4. テスト要件（c_quality）:

### テストカバレッジ目標
- 全体: 90%以上
- コアモジュール: 95%以上
- 新規実装: 100%

5. 作業フロー（c_workflow）:

### Issue駆動開発フロー
1. RFC & Plan作成
2. GitHub Issue作成
3. Issueからブランチ作成 ← 重要！
4. 実装（TDD）
5. Draft PR作成
6. CI通過 → Ready for review
7. Merge（Issue自動クローズ）

6. Context Engineering戦略（c_context）:

### Context Compression（RFC-024）
- Phase 1: Token Management（完了）
- Phase 2: Message Trimming（実装中）
- Phase 3: Summarization（計画中）
- Phase 4: Integration（計画中）

効果: これらのコンテキスト要素により、Claude Codeは常に最新の開発方針・制約・優先事項を理解した状態で作業できます。

RFCによる機能管理 - 長期的なコンテキスト保存

kagura-aiでは、Issue-Driven AI Developmentに加えてRFCによる長期計画管理を導入しました。これはContext Engineeringの「Write Context」戦略の実践例です。

# ai_docs/rfcs/RFC_024_CONTEXT_COMPRESSION.md

## 概要
Context Compression機能により、長時間の会話でもトークン制限を超えずに
動作し続けるエージェントを実現する。

## 動機
現在のKagura AIは、メモリ機能（RFC-018）によって過去の会話を保持できるが、
長時間の対話ではコンテキストウィンドウの制限に達する問題がある。

## 詳細設計
### 4つのフェーズ
- Phase 1: Token Management - トークンカウント・監視
- Phase 2: Message Trimming - 古いメッセージの削除
- Phase 3: Summarization - 重要情報の要約
- Phase 4: Integration - 統合・自動化

## 実装計画
- Issue #159: RFC-024 Phase 1 - Token Management
- Issue #161: RFC-024 Phase 2 - Message Trimming
- Issue #XXX: RFC-024 Phase 3 - Summarization
- Issue #XXX: RFC-024 Phase 4 - Integration

優先度管理:

🔥🔥🔥 Critical: RFC-024（Context Compression）- Production必須
⭐️ High: RFC-005 Phase 3（Self-Improving Agent）
⭐️ High: RFC-010拡張（Deep Observability）

完了済み（16個のRFC）: RFC-001, 002, 006, 007, 012, 013, 014, 016, 017, 018, 019, 020, 021, 022

Issue駆動開発の実践

GitHub Issue-Branch-PR 連携フロー

kagura-aiでは、GitHubの機能を最大限に活用した完全なトレーサビリティを実現しています。

# Step 1: RFC & Implementation Plan作成（Context Generation）
cat > ai_docs/rfcs/RFC_024_PHASE2_PLAN.md <<'EOF'
## Phase 2: Message Trimming - Implementation Plan

### Day 1: Core Implementation
- MessageTrimmer class
- Trimming strategies (FIFO, Priority-based)
...
EOF

# Step 2: Issue作成（Context Definition）
gh issue create \
  --title "RFC-024 Phase 2: Message Trimming" \
  --body "$(cat ai_docs/rfcs/RFC_024_PHASE2_PLAN.md)"
# → Issue #161 作成

# Step 3: IssueからBranch作成（重要！）
gh issue develop 161 --checkout
# → GitHub上でブランチ作成: 161-rfc-024-phase-2-message-trimming
# → ローカルに自動checkout

# Step 4: 実装（TDD）
# tests/core/compression/test_trimmer.py 作成
# src/kagura/core/compression/trimmer.py 実装

# Step 5: 型チェック・テスト
pyright src/kagura/
pytest --cov=src/kagura --cov-report=html

# Step 6: コミット（Conventional Commits）
git add .
git commit -m "feat(compression): implement message trimmer (#161)

- Add MessageTrimmer with FIFO strategy
- Add priority-based trimming support
- Implement token-aware trimming
- Add comprehensive test coverage (100%)

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

# Step 7: プッシュ
git push
# Note: tracking設定済みなので -u origin 不要

# Step 8: Draft PR作成（自動Issue連携）
gh pr create --draft \
  --title "feat(compression): implement message trimmer (#161)"
# → PRが自動的にIssue #161とリンク

# Step 9: CI確認
# GitHub Actions: pytest, pyright, ruff, codecov

# Step 10: Ready for review
gh pr ready 161

# Step 11: Squash merge
gh pr merge 161 --squash
# → Issue #161 も自動的にクローズ ✅

自動連携の利点:

✅ Issue-Branch-PRが完全にトレース可能
✅ PRマージ時にIssueが自動クローズ
✅ プロジェクトボードで進捗が自動更新
✅ ブランチ名の一貫性
✅ コミット履歴からIssue参照が容易

Issueテンプレート設計

claude-code-workflow-templateを基に、kagura-ai専用テンプレートを作成しました。

---
name: Development Task
title: '[RFC-XXX Phase X] Feature Name'
labels: development, claude-code, rfc-xxx
---

## 🎯 タスク概要
[RFC-XXX](../ai_docs/rfcs/RFC_XXX.md) Phase Xの実装

## 📂 スコープ境界
**許可パス**:
- src/kagura/core/compression/
- tests/core/compression/

**禁止パス**:
- src/kagura_legacy/
- examples/
- docs/

## 📑 出力契約(Claude必読)
- [ ] 実装の設計判断を記録
- [ ] 未解決の技術的負債を明示
- [ ] エラー/不明点は質問節で停止
- [ ] 作業ログをMarkdownで出力

## 🛡️ 安全策
- **Draft PR**で作成
- 10ファイル/500行超える場合は分割コミット
- GitHub Issueからブランチ作成（必須）

## 完了条件
- [ ] src/kagura/core/compression/trimmer.py 実装
- [ ] 型ヒント完備（pyright strict mode パス）
- [ ] テストカバレッジ100%
- [ ] CI（lint/test）がグリーン
- [ ] ai_docs/rfcs/RFC_XXX_PHASEXX_PLAN.md 更新

## 参考資料
- [RFC-024](../ai_docs/rfcs/RFC_024_CONTEXT_COMPRESSION.md)
- [Phase 2 Plan](../ai_docs/rfcs/RFC_024_PHASE2_PLAN.md)
- [UNIFIED_ROADMAP.md](../ai_docs/UNIFIED_ROADMAP.md)

Claude Codeの作業フロー

Phase 0: 準備（Context Retrieval）

# 必須確認ドキュメント
cat ai_docs/README.md
cat ai_docs/UNIFIED_ROADMAP.md
cat ai_docs/NEXT_STEPS.md
cat ai_docs/coding_standards.md
cat ai_docs/CONTEXT_ENGINEERING_ANALYSIS.md

この段階で、Claude Codeは以下のコンテキストを取得します:

プロジェクト全体の状態
現在のPhase
優先度の高いタスク
コーディング規約
Context Engineering戦略

Phase 1: TDD（テスト駆動開発）

# 1. ブランチ確認（GitHub Issueから作成済み）
git branch --show-current
# 例: 161-rfc-024-phase-2-message-trimming

# 2. テストを先に書く
# tests/core/compression/test_trimmer.py を作成

# 3. 実装
# src/kagura/core/compression/trimmer.py を実装

# 4. 型チェック・リント
pyright src/kagura/
ruff check src/

# 5. テスト実行
pytest --cov=src/kagura --cov-report=html

Phase 2: Draft PR作成（Context Documentation）

Conventional Commits形式のコミットメッセージ:

feat(compression): implement message trimmer (#161)

- Add MessageTrimmer class with FIFO strategy
- Implement priority-based trimming
- Add token-aware trimming logic
- Add comprehensive test coverage (100%)

Context Engineering:
- Implements "Compress Context" strategy
- Addresses RFC-024 Phase 2 requirements
- Reduces token usage by up to 60%

Related:
- RFC-024: Context Compression
- Issue #161: Phase 2 Implementation

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

gh pr create --draft \
  --title "feat(compression): implement message trimmer (#161)" \
  --body "$(cat <<'EOF'
## Summary
RFC-024 Phase 2: Message Trimming機能の実装

## Context Engineering Strategy
**Compress Context**: トークン使用量を削減し、長時間の会話を可能にする

## Changes
- src/kagura/core/compression/trimmer.py: MessageTrimmer実装
- tests/core/compression/test_trimmer.py: 包括的なテスト
- ai_docs/rfcs/RFC_024_PHASE2_PLAN.md: 実装記録の更新

## Test Results
```bash
pytest --cov=src/kagura/core/compression
# ==================== test session starts ====================
# collected 15 items
# test_trimmer.py ............... [100%]
# Coverage: 100%

## Performance
- Token reduction: 60% in typical conversations
- Latency impact: < 10ms per trimming operation

## Related
- RFC: [RFC-024](../ai_docs/rfcs/RFC_024_CONTEXT_COMPRESSION.md)
- Plan: [Phase 2 Plan](../ai_docs/rfcs/RFC_024_PHASE2_PLAN.md)
- Closes #161
EOF
)"

Phase 3: CI確認（Quality Assurance）

GitHub Actionsで自動チェック:

✅ 全テストパス（pytest）
✅ Pyright型チェックパス（strict mode）
✅ Ruffリントパス
✅ Codecov: カバレッジ90%以上

Phase 4: レビュー・マージ

# Draft → Ready for review
gh pr ready 161

# レビュー後、Squash merge
gh pr merge 161 --squash
# → Issue #161 自動クローズ ✅

実践で得られた知見

✅ うまくいったこと

1. GitHub Issue-Branch-PR連携による完全なトレーサビリティ

Issue番号からブランチを作成する方式により、以下が実現できました:

完全な履歴追跡: どのコミット/PRがどのIssueに関連するか明確
自動化: PRマージ時のIssue自動クローズ
プロジェクト管理の効率化: GitHub Projectsとの統合が容易

数値的成果:

Issue-PR-Merge-Close の自動化により、管理工数が約40%削減
ブランチ命名の一貫性により、git履歴の可読性が向上

2. スコープ境界による安全性の確保

変更禁止パスを明示することで、レガシーコードを誤って変更するリスクがゼロになりました。

⛔️ 変更禁止:
- src/kagura_legacy/     # 一度も意図しない変更が発生していない

実績: 60日間の開発期間中、レガシーコードへの誤変更は0件

3. 型ヒント完備による高品質なコード生成

# 型ヒントがあると...
def process_data(
    input_data: dict[str, Any],
    max_items: int = 10
) -> list[dict[str, str]]:
    """Claude Codeが正確に理解して実装できる」
    pass

pyright --strictを必須にすることで、Claude Codeによる生成コードの品質が大幅に向上しました。

数値的成果:

型エラーによるバグが約70%削減
コードレビュー時の指摘事項が約50%削減

4. Draft PRを前提としたワークフロー

最初から完璧を求めない。Draft PRで実装を提案し、その後に人間がレビュー・調整するフローが効率的でした。

実績:

Draft → Ready → Merge の平均時間: 2.5日
一発でマージされるPRの割合: 45%
1-2回の修正でマージされるPRの割合: 85%

5. ai_docs/による構造化されたコンテキスト提供

プロジェクト固有の用語や設計思想をai_docs/に集約することで、Issueごとに背景説明を書く手間が不要になりました。

Context Engineeringの視点:

Context Retrieval: Claude Codeが必要な情報を自動的に取得
Context Management: 情報を体系的に整理・更新
Context Selection: 優先度に基づいて関連情報を選択

数値的成果:

Issue作成時間が約60%削減（平均15分 → 6分）
Issueの記述品質が向上（必要情報の記載漏れが90%削減）

⚠️ 注意が必要なこと

1. 推測での実装を防ぐ

不明点があるとClaude Codeが推測で処理しようとするため、CLAUDE.mdに明記:

## エラー発生時の対応
1. エラー内容を正確に記録
2. Issueにコメントで報告
3. **人間の指示を待つ**（推測で進めない）
4. 解決後にドキュメント更新

実例: Token計算ロジックで、Claude Codeが独自の推定式を実装しようとした事例。Issue #161でコメントして確認を求め、正確な計算方法を指示した結果、正しい実装になった。

2. 大規模変更は分割する

Claude Codeは一度に大量の変更を加えようとすることがあります。機能単位でIssueとPRを分割するルールを設けました:

## 🛡️ 安全策
- 10ファイル/500行を超える変更は分割コミット
- Phase単位でIssue分割（RFC-024の例: Phase 1-4に分割）

実例: RFC-024（Context Compression）を4つのPhaseに分割:

Phase 1: Token Management（完了）
Phase 2: Message Trimming（実装中）
Phase 3: Summarization（計画中）
Phase 4: Integration（計画中）

各Phaseは独立したIssue/PR/ブランチで管理し、段階的に統合。

3. Context Window制限への対応

長時間の開発セッションでは、Claude Code自身がContext Window制限に達することがあります。

対策:

定期的な要約: 重要な決定事項をai_docs/NEXT_STEPS.mdに記録
セッション分割: 1つのIssueを複数のセッションに分割
RFC-024の適用: Context Compression機能を自分自身に適用（メタ的活用）

Context Engineeringの実践パターン

Claude Codeが理解しやすいコード設計の実践例を、Context Engineeringの観点から紹介します。

パターン1: 型で意図を表現（Context Clarity）

# ❌ AIが推測しにくい（曖昧なコンテキスト）
def process(data):
    return do_something(data)

# ✅ AIが理解しやすい（明確なコンテキスト）
def process(data: InputData) -> ProcessedResult:
    """
    入力データを処理して結果を返す
    
    Context:
        - InputDataはuser_id, timestampを含む
        - ProcessedResultはstatus, messageを含む
    
    Args:
        data: 入力データ（user_id, timestampを含む）
    
    Returns:
        処理結果（status, messageを含む）
    
    Raises:
        ValueError: user_idが不正な場合
    """
    return do_something(data)

Context Engineering視点:

型ヒント = Context Definition（コンテキストの明確な定義）
docstring = Context Documentation（コンテキストの詳細説明）
効果: Claude Codeの実装精度が向上

パターン2: 単一責任の徹底（Context Isolation）

src/kagura/core/
├── decorators.py    # @agentデコレータのみ
├── executor.py      # コード実行のみ
├── llm.py           # LLM統合のみ
└── parser.py        # 型パーサーのみ

# 1ファイル = 1概念 = 1つのContext
→ Claude Codeが並行作業可能
→ コンフリクト回避
→ Context Isolationの実現

Context Engineering視点:

各モジュールが独立したContext Spaceを持つ
Cross-contextの依存を最小化
効果: モジュール間の干渉を防ぎ、並列開発が可能

パターン3: 明示的 > 暗黙的（Explicit Context）

# ❌ 暗黙的な依存（Hidden Context）
class Agent:
    def __init__(self):
        self.llm = get_global_llm()  # どこから来たか不明

# ✅ 明示的な依存（Explicit Context）
class Agent:
    def __init__(self, llm: LLMClient):
        """
        エージェントを初期化
        
        Context Dependencies:
            - llm: LLMクライアント（明示的に注入）
        """
        self.llm = llm

原則: グローバル変数や暗黙的な状態変更を避け、すべての依存関係を明示的に

Context Engineering視点:

Explicit Context Injection: コンテキストの明示的な注入
効果: Claude Codeが依存関係を正確に理解できる

パターン4: ディレクトリ構造の自己文書化（Structured Context）

tests/
├── core/                  # src/kagura/core/ に対応
│   ├── test_decorators.py
│   ├── test_executor.py
│   └── test_parser.py
└── agents/                # src/kagura/agents/ に対応
    └── test_code_agent.py

# ディレクトリ構造が実装と1:1対応
→ Claude Codeが「どこに何があるか」を即座に理解
→ Context Navigationが容易

Context Engineering視点:

Spatial Context: ファイルの物理的配置がコンテキストを表現
効果: Claude Codeのファイル探索効率が向上

パターン5: Context-Aware Memory Management（RFC-018実装）

# ✅ Good: 明示的なメモリスコープ（Context Scoping）
@agent(enable_memory=True, memory_scope="session")
async def assistant(query: str, memory: MemoryManager) -> str:
    """
    Context Strategy: Write Context
    - セッションスコープのメモリを使用
    - 過去の会話履歴を保持
    """
    user_prefs = await memory.recall("preferences")
    # ...

# ❌ Bad: グローバルメモリ（Context Pollution）
global_memory = MemoryManager()  # Don't do this

Context Engineering視点:

Write Context: コンテキストウィンドウ外に情報を保存
Context Scoping: スコープを明示的に管理
効果: 長時間の対話でもコンテキストが維持される

パターン6: Context Compression（RFC-024実装中）

# Phase 2実装後の推奨パターン
@agent(
    enable_memory=True,
    compression_policy=CompressionPolicy(
        strategy="smart",  # 重要イベントを保持
        max_tokens=4000,
        trigger_threshold=0.8  # 80%で圧縮開始
    )
)
async def assistant(query: str, memory: MemoryManager) -> str:
    """
    Context Strategy: Compress Context
    - 自動的にトークン使用量を削減
    - 重要な情報は保持
    """
    # 圧縮は自動実行
    pass

Context Engineering視点:

Compress Context: トークン使用量を削減
Smart Compression: 重要情報を保持しつつ圧縮
効果: 長時間の会話が可能になる

開発効率の改善

ドキュメント・テスト作成の効率化

従来の開発では、ドキュメントとテストコーディングが開発時間の60%を占めることも。Issue-Driven AI Developmentで、この時間を削減できました。

戦略1: テスト生成の半自動化

Issueに期待する動作を記述:

## 期待する動作（Context Definition）
- `@agent`デコレータは型ヒントを解析
- Pydanticモデルの場合は自動パース
- エラー時はValidationErrorを投げる

## テスト要件（Context Specification）
- 基本動作テスト
- 型ヒント解析テスト
- Pydanticモデルパーステスト
- エラーハンドリングテスト

↓ Claude Codeがテスト生成

def test_agent_parses_type_hints():
    """型ヒント解析のテスト"""
    @agent(prompt="test")
    def func(data: UserData) -> str:
        pass
    
    assert func.parser.model == UserData

def test_agent_pydantic_parsing():
    """Pydanticモデルパースのテスト"""
    @agent(prompt="test")
    def func(data: dict) -> UserData:
        pass
    
    result = func({"name": "test", "age": 30})
    assert isinstance(result, UserData)

def test_agent_error_handling():
    """エラーハンドリングのテスト"""
    @agent(prompt="test")
    def func(data: UserData) -> str:
        pass
    
    with pytest.raises(ValidationError):
        func({"invalid": "data"})

人間の役割: テストのレビューとエッジケースの追加

数値的成果:

テスト作成時間が約50%削減
テストカバレッジが平均95%以上を達成

戦略2: ドキュメントの段階的生成

kagura-aiでは、Phase 4（統合テスト段階）で一括生成する戦略を採用:

Phase 0-3: 実装に集中（ai_docs/のみ更新）
Phase 4: 実装からドキュメント自動生成
- docstringから APIリファレンス
- RFCからユーザーガイド
- 実装例からチュートリアル

Context Engineering視点:

Context Generation: 実装からドキュメントを生成
Context Synchronization: 実装とドキュメントの同期を保証

効果: ドキュメントと実装の乖離を防ぎ、作成時間も削減

コーディング規約

kagura-aiでは、Claude Codeが理解しやすい規約を設定しています。

命名規則（Context Convention）

- モジュール/パッケージ: `snake_case` (例: `kagura.core.agent`)
- クラス名: `PascalCase` (例: `AtomicAgent`, `LLMConfig`)
- 関数/変数: `snake_case` (例: `create_agent`)
- 定数: `UPPER_SNAKE_CASE` (例: `DEFAULT_MODEL`)
- プライベート: `_leading_underscore` (例: `_internal_state`)

型ヒント必須（Context Clarity）

# ❌ 型ヒントなしは禁止
def process_data(input_data, max_items=10):
    pass

# ✅ 正しい（pyright --strict でチェック）
def process_data(
    input_data: dict[str, Any],
    max_items: int = 10
) -> list[dict[str, str]]:
    pass

ドキュメント規約（Context Documentation）

def create_agent(name: str, model: str = "gpt-4o-mini") -> Agent:
    """エージェントを作成する

    Context:
        - デフォルトモデルは gpt-4o-mini
        - nameは空文字列不可

    Args:
        name: エージェント名
        model: 使用するLLMモデル

    Returns:
        作成されたAgentインスタンス

    Raises:
        ValueError: nameが空の場合
        
    Context Engineering:
        - Write Context: エージェント設定をメモリに保存
        - Select Context: モデル情報を動的に取得
    """
    pass

ツールチェーン

uv: 高速パッケージマネージャー
pytest: テストフレームワーク（カバレッジ90%以上）
pyright: 型チェッカー（strict mode）
ruff: 超高速リンター・フォーマッター
GitHub Actions: CI/CD
Codecov: カバレッジ可視化

# よく使うコマンド
pytest -n auto --cov=src/kagura --cov-report=html
pyright src/kagura/
ruff check --fix src/

まとめ

Issue-Driven AI Developmentをkagura-aiで実践した結果、以下の効果がありました:

✅ 実現できたこと

1. 安全な開発

スコープ境界でレガシーコードを保護（誤変更0件/60日）
Draft PRを前提に人間がレビュー
CI/CDで品質を自動保証（テストカバレッジ95%以上）

2. 効率的な開発

テスト生成の半自動化（作成時間50%削減）
ドキュメント作成の段階的生成
Issue作成時間60%削減（平均15分 → 6分）
GitHub Issue-Branch-PR連携による管理工数40%削減

3. 高品質なコード

型ヒント完備（pyright strict mode）
型エラーによるバグ70%削減
カバレッジ95%以上
Conventional Commits形式

4. 長期的な保守性

RFCによる機能仕様管理（24個のRFC）
Phase分割による段階的開発
完全なトレーサビリティ（Issue-PR-Commit）
Context Engineeringの4戦略実装

💭 Context Engineeringの本質

システムを自然言語で説明し抽象化することで、AIとのコンテキスト共有がより的確にできるようになります。

Context Engineering = コンテキストの設計・管理・最適化

従来のプロンプトエンジニアリングは「その場の指示」に依存していましたが、Context Engineeringは構造化された情報の体系的管理を実現します。

Issue-Driven AI Developmentでは、以下を実践しています:

Context Generation: CLAUDE.md、RFCでコンテキストを生成
Context Retrieval: ai_docs/から必要な情報を取得
Context Management: Issue-Branch-PRで履歴管理
Context Selection: 優先度に基づいて作業を選択
Context Compression: RFC-024で実装中
Context Isolation: モジュール分離、マルチエージェント

📊 数値的成果まとめ

指標	改善率	詳細
レガシーコードへの誤変更	100%削減	60日間で0件
型エラーによるバグ	70%削減	pyright strict mode導入
コードレビュー指摘	50%削減	型ヒント完備の効果
テスト作成時間	50%削減	半自動化による
Issue作成時間	60%削減	ai_docs/による背景共有
プロジェクト管理工数	40%削減	GitHub連携自動化
テストカバレッジ	95%以上	新規実装は100%

🚀 今後の展開

RFC-024（Context Compression）の完成:

Phase 2: Message Trimming（実装中）
Phase 3: Summarization（計画中）
Phase 4: Integration（計画中）

完成後、長時間の対話でもトークン制限を気にせず開発可能になります。

他のRFCの実装:

RFC-003: Personal Assistant
RFC-004: Voice Interface
RFC-009: Multi-Agent Orchestration

🎯 Issue-Driven AI Developmentの本質

開発においてドキュメント化（自然言語化）は重要なタスクですが、Issue-Driven AI Developmentでは開発しながらドキュメントを作成できます。これにより、設計・コーディング・コードレビューに開発者のリソースを集中できます。

Vibe Codingとして色々と課題はありますが、使い方と使いどころを抑えると強力なツールになるというのが現時点での感想です。

特に、Context Engineeringの原則を理解し、構造化されたコンテキスト管理を実践することで、AIとの協働開発が劇的に改善されます。

📚 参考リンク

Issue-Driven AI Development:

Context Engineering:

kagura-ai:

Issue-Driven AI Developmentは、Claude Codeを安全に、効率的に、高品質に運用するための優れた手法です。そして、その背景にあるContext Engineeringの原則を理解することで、さらに効果的なAI協働開発が可能になります。ぜひ実践してみてください！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up