Claude Code 学习总结与系统搭建记录#

📚 学习内容概述#

1. 核心文章学习#

  • 文章标题: “Effective harnesses for long-running agents”
  • 来源: Anthropic官方博客
  • 核心问题: AI代理在跨多个会话工作时如何保持上下文和持续进展
  • 解决方案: Initializer Agent + Coding Agent 双代理架构

2. 系统设计要点#

  • Initializer Agent: 初始化环境、创建特性列表、建立Git仓库
  • Coding Agent: 增量开发、一次一个特性、保持清洁状态
  • Feature List: JSON格式，防止误修改，包含50-200+个测试特性
  • Git工作流: 每个特性完成后提交，支持回滚和状态恢复
  • Progress Tracking: 详细的进度文件记录每个会话的工作

🛠️ 系统搭建过程#

1. 项目结构设计#

long-running-agent-harness/
├── src/
│   ├── agents/          # 代理实现（2个）
│   ├── core/            # 核心功能（4个模块）
│   ├── prompts/         # 提示词模板（2个）
│   └── main.py          # 主入口
├── docs/                # 文档（5个文件）
├── examples/            # 示例项目（2个）
└── tests/               # 单元测试

2. 核心模块实现#

  • FeatureManager: 特性列表管理（200+行）
  • ProgressTracker: 进度跟踪系统
  • GitManager: Git操作封装
  • SessionManager: 会话状态管理
  • InitializerAgent: 环境初始化
  • CodingAgent: 增量开发代理

3. 文档体系#

  • ARCHITECTURE_ANALYSIS.md: 架构分析（基于原文）
  • PROJECT_STRUCTURE.md: 项目结构设计
  • USER_GUIDE.md: 详细使用指南
  • README.md: 项目说明
  • SUMMARY.md: 完成总结

🔧 工具使用问题与优化#

1. Bash环境兼容性问题#

问题描述#

  • 在Windows环境下，Bash命令 find, wc, export 等经常报错
  • 系统Bash环境与用户MINGW64环境不一致
  • 路径格式兼容性问题

解决方案#

更新 ~/.claude/rules/tools.md，添加强制规则：

## 文件操作规则（强制）

**禁止使用Bash命令进行文件操作，必须使用专用工具：**

- ❌ 禁止：`cat`, `head`, `tail` → ✅ 使用：`Read` 工具
- ❌ 禁止：`find`, `ls` → ✅ 使用：`Glob` 工具
- ❌ 禁止：`grep`, `rg` → ✅ 使用：`Grep` 工具
- ❌ 禁止：`sed`, `awk` → ✅ 使用：`Edit` 工具
- ❌ 禁止：`echo >`, `cat <<EOF` → ✅ 使用：`Write` 工具
- ❌ 禁止：`wc -l` 统计文件 → ✅ 使用：`Glob` 然后计数

2. GitHub工具对比#

gh CLI 优点#

  • ✅ 显示完整信息（包括私有仓库）
  • ✅ 可以直接筛选复刻仓库（--fork）
  • ✅ 格式清晰，易读
  • ✅ 速度快

GitHub MCP 问题#

  • ❌ 搜索结果不完整
  • ❌ 无法直接筛选复刻仓库
  • ❌ 返回数据冗长
  • ⚠️ 需要先用ToolSearch加载

使用建议#

# 优先使用gh CLI
gh repo list --limit 20
gh repo list --fork --limit 30

# 不推荐使用MCP（除非必须）
# mcp__github__search_repositories（结果不完整）

3. 专用工具优势#

  • 跨平台一致性: 在所有平台都稳定工作
  • 错误处理更好: 提供更清晰的错误信息
  • 性能更优: 通常比bash命令更快
  • 兼容性更强: 不受Shell环境限制

📋 使用示例#

1. 初始化新项目#

# 创建待办事项应用
python -m src.main "创建一个简单的待办事项应用" "./todo_project"

2. 继续开发#

# 进入项目目录
cd todo_project

# 继续开发
python -m src.main

3. 运行示例#

# 待办事项应用示例
python examples/todo_app_example.py

# API服务示例
python examples/api_service_example.py

🎯 系统特点#

1. 完整复刻#

  • ✅ 双代理架构（Initializer + Coding Agent）
  • ✅ Feature List系统
  • ✅ Git工作流集成
  • ✅ Progress Tracking
  • ✅ Session Management

2. 四种失败模式解决方案#

  • ✅ 防止过早宣布完成
  • ✅ 保持环境清洁状态
  • ✅ 充分测试后才标记完成
  • ✅ 标准化启动流程

3. 项目统计#

  • Python文件: 18个
  • 文档文件: 5个Markdown文档
  • 代码行数: 约2000+行
  • 模块数: 4个核心模块

🔍 优化建议#

1. 工具使用规范#

  • 始终使用专用工具（Glob, Grep, Read, Edit, Write）
  • 避免使用bash命令进行文件操作
  • 优先使用gh CLI而不是GitHub MCP

2. 环境配置#

  • 如果必须使用bash，确保在正确的Shell环境中
  • 考虑设置环境变量（如 SHELL=/usr/bin/bash）
  • 在Windows下注意路径格式兼容性

3. 代码质量#

  • 遵循PEP 8规范
  • 添加充分的错误处理
  • 保持模块化和可扩展性

📝 总结#

本次学习完整复刻了Anthropic的长时间运行代理系统，解决了AI代理跨会话开发的核心问题。通过严格的工具使用规范和优化，确保了系统的稳定性和跨平台兼容性。

关键收获:

  1. 双代理架构是解决长时间运行问题的有效方案
  2. 专用工具比bash命令更可靠
  3. gh CLI比GitHub MCP更实用
  4. 良好的文档和示例对项目成功至关重要

创建者: Claude Code Agent 创建时间: 2026-02-21 最后更新: 2026-02-21