coding-agent-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Coding Agent Development Patterns

编程Agent开发模式

Core patterns distilled from Claude Code (70k stars), Codex (62k), Cline (58k), Aider (41k), and OpenCode (114k).
从Claude Code(7万星)、Codex(6.2万星)、Cline(5.8万星)、Aider(4.1万星)和OpenCode(11.4万星)中提炼的核心模式。

The Core Loop: while(true)

核心循环:while(true)

All AI coding agents share the same fundamental loop. The loop follows the pattern: ask LLM if it needs tools, use them, feed results back, and repeat until done. The implementation builds context with tools and conversation history, calls the LLM with messages and tool definitions, checks for tool calls and returns content if none, executes tools and appends results to history, then loops back with tool results.
Core Tools: All agents have six fundamental tools. The
read
tool reads file contents. The
write
tool creates or overwrites files. The
edit
tool performs precise string replacement in files. The
bash
tool executes shell commands. The
glob
tool finds files by pattern. The
grep
tool searches file contents. A minimal viable agent requires approximately 1000-2000 lines with these six tools plus the loop.
所有AI编程Agent都遵循相同的基础循环。循环模式为:询问LLM是否需要调用工具,执行工具,将结果反馈给LLM,重复操作直到任务完成。实现逻辑为:通过工具和会话历史构建上下文,传入消息和工具定义调用LLM,检查是否有工具调用请求,无请求则返回内容,有则执行工具并将结果追加到历史记录,再带着工具结果进入下一轮循环。
核心工具:所有Agent都有6个基础工具。
read
工具读取文件内容;
write
工具创建或覆盖文件;
edit
工具对文件执行精准的字符串替换;
bash
工具执行shell命令;
glob
工具按模式匹配查找文件;
grep
工具搜索文件内容。一个最小可用Agent包含这6个工具加循环逻辑,大约需要1000-2000行代码。

Challenge 1: Context Window Management

挑战1:上下文窗口管理

The biggest engineering challenge. A real project has thousands of files, but LLMs have limited context (128K - 2M tokens).
Strategies: Different agents use different strategies. Aider uses Repo Map with tree-sitter scanning that only passes signatures and loads details on demand. Claude Code uses Auto-compaction where the LLM summarizes history when context fills. OpenCode uses a two-level approach that prunes old tool results (keeping 40K recent) and then compresses.
这是最大的工程挑战。真实项目有数千个文件,但LLM的上下文容量有限(128K - 2M tokens)。
策略:不同的Agent采用不同的策略。Aider使用基于tree-sitter扫描的Repo Map,仅传递代码签名,按需加载详情。Claude Code使用自动压缩机制,上下文占满时由LLM总结历史记录。OpenCode采用双层方案:先裁剪旧的工具执行结果(保留最近40K tokens),再进行压缩。

Compression Pattern

压缩模式

python
def compress_context(history: list, budget: int) -> list:
    """Compress history when approaching context limit."""
    usage = count_tokens(history)

    if usage < budget * 0.8:
        return history

    # Keep recent turns, summarize older ones
    recent = history[-10:]  # Last 10 turns
    older = history[:-10]

    summary = llm.summarize(older)
    return [{"role": "system", "content": f"Previous context summary:\n{summary}"}] + recent
python
def compress_context(history: list, budget: int) -> list:
    """Compress history when approaching context limit."""
    usage = count_tokens(history)

    if usage < budget * 0.8:
        return history

    # Keep recent turns, summarize older ones
    recent = history[-10:]  # Last 10 turns
    older = history[:-10]

    summary = llm.summarize(older)
    return [{"role": "system", "content": f"Previous context summary:\n{summary}"}] + recent

Repo Map Pattern (Aider)

Repo Map模式(Aider)

python
def build_repo_map(repo_path: Path) -> str:
    """Build a 'map' of the codebase with just signatures."""
    import tree_sitter

    map_lines = []
    for file in repo_path.rglob("*.py"):
        # Parse and extract: class names, function signatures, imports
        signatures = extract_signatures(file)
        map_lines.append(f"{file}:\n{signatures}")

    return "\n".join(map_lines)  # Much smaller than full code
python
def build_repo_map(repo_path: Path) -> str:
    """Build a 'map' of the codebase with just signatures."""
    import tree_sitter

    map_lines = []
    for file in repo_path.rglob("*.py"):
        # Parse and extract: class names, function signatures, imports
        signatures = extract_signatures(file)
        map_lines.append(f"{file}:\n{signatures}")

    return "\n".join(map_lines)  # Much smaller than full code

Challenge 2: Tool Execution Safety

挑战2:工具执行安全

Three Safety Models

三类安全模型

Three safety models represent different trade-offs. The hard sandbox model used by Codex (Rust) provides maximum safety with OS-level isolation. The per-step approval model used by Cline is safe but tedious due to too many popups. The tiered plus hooks model used by Claude Code provides balance with read/write/execute tiers.
三类安全模型对应不同的权衡。Codex(Rust实现)采用硬沙箱模型,通过操作系统级隔离提供最高安全性。Cline采用单步审批模型,安全性高但弹窗过多体验繁琐。Claude Code采用分级加钩子模型,通过读/写/执行分级实现平衡。

Sandboxing (Codex/Rust approach)

沙箱机制(Codex/Rust方案)

rust
// Use landlock + seccomp for OS-level sandboxing
fn sandbox_restrict(allowed_paths: &[PathBuf]) -> Result<()> {
    // Limit file access to allowed paths
    // Block dangerous syscalls
    // Three modes: suggest-only, auto-edit, full-auto
}
rust
// Use landlock + seccomp for OS-level sandboxing
fn sandbox_restrict(allowed_paths: &[PathBuf]) -> Result<()> {
    // Limit file access to allowed paths
    // Block dangerous syscalls
    // Three modes: suggest-only, auto-edit, full-auto
}

Tiered Tools (Claude Code approach)

分级工具(Claude Code方案)

python
TOOL_TIERS = {
    "read": "safe",       # No approval needed
    "write": "needs_approval",  # User confirms
    "bash": "restricted", # Blacklist + approval
}

def execute_tool(name: str, args: dict) -> Result:
    tier = TOOL_TIERS.get(name, "safe")

    if tier == "needs_approval":
        if not user_approves(name, args):
            return Result(cancelled=True)

    if tier == "restricted":
        if is_dangerous(args):
            return Result(error="Command blocked")

    return run_tool(name, args)
python
TOOL_TIERS = {
    "read": "safe",       # No approval needed
    "write": "needs_approval",  # User confirms
    "bash": "restricted", # Blacklist + approval
}

def execute_tool(name: str, args: dict) -> Result:
    tier = TOOL_TIERS.get(name, "safe")

    if tier == "needs_approval":
        if not user_approves(name, args):
            return Result(cancelled=True)

    if tier == "restricted":
        if is_dangerous(args):
            return Result(error="Command blocked")

    return run_tool(name, args)

Doom Loop Detection (OpenCode unique feature)

死循环检测(OpenCode独有功能)

python
def detect_doom_loop(history: list) -> bool:
    """Detect if agent is stuck repeating the same action."""
    if len(history) < 3:
        return False

    last_three = history[-3:]
    # Check if same tool called 3 times with identical args
    if all_same_tool_and_args(last_three):
        return True  # Pause and ask user

    return False
python
def detect_doom_loop(history: list) -> bool:
    """Detect if agent is stuck repeating the same action."""
    if len(history) < 3:
        return False

    last_three = history[-3:]
    # Check if same tool called 3 times with identical args
    if all_same_tool_and_args(last_three):
        return True  # Pause and ask user

    return False

Challenge 3: Multi-Provider Abstraction

挑战3:多厂商抽象

Each LLM provider has different APIs for message formats, tool calling, and streaming. OpenAI uses
content: string
with
function_call
for tools. Anthropic uses
content: blocks[]
with
tool_use
for tools. Google uses
parts[]
with
function_call
for tools. Ollama is OpenAI-compatible.
Two approaches exist for multi-provider abstraction. OpenCode uses the Vercel AI SDK which provides free abstraction for over 20 providers. Cline uses manual adapters which supports 44 providers with full control.
每个LLM厂商的消息格式、工具调用、流式传输API都不同。OpenAI使用
content: string
function_call
实现工具调用。Anthropic使用
content: blocks[]
tool_use
实现工具调用。Google使用
parts[]
function_call
实现工具调用。Ollama兼容OpenAI格式。
多厂商抽象有两种方案。OpenCode使用Vercel AI SDK,免费提供对20+厂商的抽象支持。Cline使用手动适配器,支持44个厂商,可控性更高。

Unified Client Pattern

统一客户端模式

python
class BaseLLMClient(ABC):
    @abstractmethod
    def chat(self, messages: list, tools: list) -> Response: ...

    @abstractmethod
    def chat_stream(self, messages: list, tools: list) -> Iterator[Chunk]: ...

class OpenAIClient(BaseLLMClient):
    def chat(self, messages, tools):
        return self.client.chat.completions.create(
            model=self.model, messages=messages, tools=tools
        )

class AnthropicClient(BaseLLMClient):
    def chat(self, messages, tools):
        return self.client.messages.create(
            model=self.model, messages=messages, tools=tools
        )

def get_client(provider: str, model: str) -> BaseLLMClient:
    clients = {
        "openai": OpenAIClient,
        "anthropic": AnthropicClient,
        "ollama": OllamaClient,
    }
    return clients[provider](model)
python
class BaseLLMClient(ABC):
    @abstractmethod
    def chat(self, messages: list, tools: list) -> Response: ...

    @abstractmethod
    def chat_stream(self, messages: list, tools: list) -> Iterator[Chunk]: ...

class OpenAIClient(BaseLLMClient):
    def chat(self, messages, tools):
        return self.client.chat.completions.create(
            model=self.model, messages=messages, tools=tools
        )

class AnthropicClient(BaseLLMClient):
    def chat(self, messages, tools):
        return self.client.messages.create(
            model=self.model, messages=messages, tools=tools
        )

def get_client(provider: str, model: str) -> BaseLLMClient:
    clients = {
        "openai": OpenAIClient,
        "anthropic": AnthropicClient,
        "ollama": OllamaClient,
    }
    return clients[provider](model)

Challenge 4: Error Recovery

挑战4:错误恢复

Long execution chains fail often: API limits, expired keys, network, context overflow.
长执行链经常出错:API限流、密钥过期、网络问题、上下文溢出。

Layered Retry Pattern

分层重试模式

python
async def agent_loop_with_retry(max_retries: int = 32):
    for attempt in range(max_retries):
        try:
            return await agent_loop()
        except RateLimitError:
            await sleep(60 * (2 ** attempt))  # Exponential backoff
        except AuthError:
            rotate_api_key()  # Inner retry
        except ContextOverflowError:
            compress_context()  # Middle retry
        except NetworkError:
            continue  # Immediate retry
        except FatalError:
            rebuild_session()  # Outer retry
python
async def agent_loop_with_retry(max_retries: int = 32):
    for attempt in range(max_retries):
        try:
            return await agent_loop()
        except RateLimitError:
            await sleep(60 * (2 ** attempt))  # Exponential backoff
        except AuthError:
            rotate_api_key()  # Inner retry
        except ContextOverflowError:
            compress_context()  # Middle retry
        except NetworkError:
            continue  # Immediate retry
        except FatalError:
            rebuild_session()  # Outer retry

Challenge 5: Session Persistence

挑战5:会话持久化

Different agents use different storage approaches. OpenCode uses SQLite which provides ACID guarantees and no corruption on crash. Other agents use JSONL which is simple and human-readable.
不同Agent采用不同的存储方案。OpenCode使用SQLite,提供ACID保证,崩溃时不会损坏数据。其他Agent使用JSONL,简单易读。

JSONL Pattern

JSONL模式

python
def save_session(session_id: str, event: dict):
    """Append event to session log file."""
    log_file = Path.home() / ".agent" / "sessions" / f"{session_id}.jsonl"
    with open(log_file, "a") as f:
        f.write(json.dumps(event) + "\n")

def load_session(session_id: str) -> list:
    """Load all events from session."""
    log_file = Path.home() / ".agent" / "sessions" / f"{session_id}.jsonl"
    events = []
    with open(log_file) as f:
        for line in f:
            events.append(json.loads(line))
    return events
python
def save_session(session_id: str, event: dict):
    """Append event to session log file."""
    log_file = Path.home() / ".agent" / "sessions" / f"{session_id}.jsonl"
    with open(log_file, "a") as f:
        f.write(json.dumps(event) + "\n")

def load_session(session_id: str) -> list:
    """Load all events from session."""
    log_file = Path.home() / ".agent" / "sessions" / f"{session_id}.jsonl"
    events = []
    with open(log_file) as f:
        for line in f:
            events.append(json.loads(line))
    return events

Shadow Git Pattern (Cline unique)

影子Git模式(Cline独有)

python
def init_shadow_git(project_path: Path):
    """Create hidden git repo for undo history."""
    shadow_path = project_path / ".agent-shadow-git"
    run(["git", "init"], cwd=shadow_path)

def snapshot_after_tool(shadow_path: Path):
    """Auto-commit after each tool execution."""
    run(["git", "add", "-A"], cwd=shadow_path)
    run(["git", "commit", "-m", "snapshot"], cwd=shadow_path)

def undo_to_snapshot(shadow_path: Path, commit_hash: str):
    """Restore to any previous state."""
    run(["git", "checkout", commit_hash], cwd=shadow_path)
python
def init_shadow_git(project_path: Path):
    """Create hidden git repo for undo history."""
    shadow_path = project_path / ".agent-shadow-git"
    run(["git", "init"], cwd=shadow_path)

def snapshot_after_tool(shadow_path: Path):
    """Auto-commit after each tool execution."""
    run(["git", "add", "-A"], cwd=shadow_path)
    run(["git", "commit", "-m", "snapshot"], cwd=shadow_path)

def undo_to_snapshot(shadow_path: Path, commit_hash: str):
    """Restore to any previous state."""
    run(["git", "checkout", commit_hash], cwd=shadow_path)

Memory Systems

记忆系统

Project Rules Loading

项目规则加载

Different agents use different approaches for loading project rules. Claude Code uses
CLAUDE.md
plus
.claude/rules/
directory with auto-memory and per-file-type rules. OpenCode uses
.opencode/skills/
plus agents directory with on-demand skill loading and markdown agents. Cline uses
.clinerules
with 7 lifecycle hooks. Aider uses
CONVENTIONS.md
with simple
/read
loading. Codex uses
AGENTS.md
plus Skills for deterministic workflows.
不同Agent采用不同的项目规则加载方案。Claude Code使用
CLAUDE.md
.claude/rules/
目录,支持自动记忆和按文件类型规则。OpenCode使用
.opencode/skills/
加agents目录,支持按需加载技能和markdown格式Agent。Cline使用
.clinerules
,支持7个生命周期钩子。Aider使用
CONVENTIONS.md
,通过简单的
/read
加载。Codex使用
AGENTS.md
加技能,实现确定性工作流。

Skill System Pattern (OpenCode)

技能系统模式(OpenCode)

.opencode/
├── skills/
│   ├── git-release/
│   │   └── SKILL.md
│   └── code-review/
│       └── SKILL.md
└── agents/
    └── reviewer.md   # Specialized agent definition
markdown
<!-- .opencode/agents/reviewer.md -->
---
description: Code review agent, read-only
mode: subagent
tools:
  write: false
  edit: false
---
You are a code review expert. Analyze code, suggest improvements, never modify files.
.opencode/
├── skills/
│   ├── git-release/
│   │   └── SKILL.md
│   └── code-review/
│       └── SKILL.md
└── agents/
    └── reviewer.md   # Specialized agent definition
markdown
<!-- .opencode/agents/reviewer.md -->
---
description: Code review agent, read-only
mode: subagent
tools:
  write: false
  edit: false
---
You are a code review expert. Analyze code, suggest improvements, never modify files.

Auto-Memory Pattern (Claude Code)

自动记忆模式(Claude Code)

python
def learn_from_correction(user_feedback: str, context: dict):
    """Store user corrections for future reference."""
    memory_file = Path.home() / ".claude" / "auto_memory.json"

    memories = json.loads(memory_file.read_text())
    memories.append({
        "feedback": user_feedback,
        "context": context,
        "timestamp": datetime.now().isoformat(),
    })

    memory_file.write_text(json.dumps(memories, indent=2))

def build_system_prompt() -> str:
    """Include learned preferences in system prompt."""
    memory_file = Path.home() / ".claude" / "auto_memory.json"
    if memory_file.exists():
        memories = json.loads(memory_file.read_text())
        return f"User preferences:\n{format_memories(memories)}"
    return ""
python
def learn_from_correction(user_feedback: str, context: dict):
    """Store user corrections for future reference."""
    memory_file = Path.home() / ".claude" / "auto_memory.json"

    memories = json.loads(memory_file.read_text())
    memories.append({
        "feedback": user_feedback,
        "context": context,
        "timestamp": datetime.now().isoformat(),
    })

    memory_file.write_text(json.dumps(memories, indent=2))

def build_system_prompt() -> str:
    """Include learned preferences in system prompt."""
    memory_file = Path.home() / ".claude" / "auto_memory.json"
    if memory_file.exists():
        memories = json.loads(memory_file.read_text())
        return f"User preferences:\n{format_memories(memories)}"
    return ""

Rules

规则

  • rules/context-management.md - Context window strategies
  • rules/tool-safety.md - Security patterns
  • rules/multi-provider.md - LLM abstraction
  • rules/memory-systems.md - Agent memory patterns
  • rules/context-management.md - 上下文窗口策略
  • rules/tool-safety.md - 安全模式
  • rules/multi-provider.md - LLM抽象层
  • rules/memory-systems.md - Agent记忆模式

Key Takeaways

核心要点

Five key principles guide agent development. First, start with the loop by writing the while(true) first and getting tool calling working. Second, implement context management early since this is the number one cause of agent failures. Third, provider abstraction matters because locking into one LLM vendor creates vendor lock-in. Fourth, layer safety with sandbox plus approval plus detection. Fifth, recognize that memory equals context since rules are injected into prompts rather than being separate config.
五个核心原则指导Agent开发。第一,从循环开始,先编写while(true)逻辑,打通工具调用流程。第二,尽早实现上下文管理,这是Agent故障的首要原因。第三,厂商抽象很重要,绑定单一LLM厂商会导致厂商锁定。第四,分层做安全,叠加沙箱、审批、检测机制。第五,要意识到记忆等于上下文,规则是注入到提示词中而不是作为独立配置存在的。