AI编码工具:Claude Code、OpenCode与最新的开发指南

如果你还在从 ChatGPT 或 Claude.ai 复制代码到编辑器中，那你正在错过软件开发领域的一场根本性变革。现代 AI 编程工具不仅仅是回答问题——它们「直接与你的代码库交互」、读取文件、运行命令，并为你编写代码。

本指南将带你从完全新手成长为高级用户，涵盖以下内容：

• AI 编程工具是什么，以及它们为何重要
• 每个开发者必须理解的核心概念
• Claude Code：Anthropic 官方推出的终端助手
• OpenCode：具有多代理能力的开源替代方案
• 如何根据你的情况选择合适的工具
• 生产环境开发的高级技巧

「快速上手」：如果你更喜欢动手学习，可以把这个 gist 分享给你的 AI 编程工具：

Read this gist and set up my project: https://gist.github.com/senrecep/98d3583717581a4138bac62344261f6f

第一部分：基础知识

什么是 AI 编程工具？

AI 编程工具是基于终端的助手，能够：

• 「直接读写文件」到你的项目中
• 「执行命令」（构建、测试、部署）
• 「理解上下文」来自你的整个代码库
• 「生成、重构和调试代码」基于你的指令

与基于网页的 AI（ChatGPT、Claude.ai）不同，这些工具直接集成到你的开发环境中。

两大主流工具（2026年1月）

你应该知道的五大限制

在深入之前，先了解当前 AI 编程工具还不能完美做到的事情：

「1. 单代理问题」大多数工具使用一个通用 AI 处理所有任务。这就像要求一个人同时担任医生、律师和建筑师。

「2. 幻觉风险」AI 可能生成看起来合理但实际错误的代码——发明不存在的 API，或使用已弃用的模式。

「3. 上下文丢失」在长对话中，AI 会”忘记”之前的决定。你会发现自己需要重复架构选择。

「4. 质量差距」生成的代码不会自动经过测试。你必须手动验证安全性、类型和测试覆盖率。

「5. 工作流碎片化」需求 → 编码 → 测试 → 文档需要分开的对话。

第二部分：核心概念

CLAUDE.md —— 你的项目大脑

一个位于项目根目录的 markdown 文件，为 AI 提供上下文。「Claude Code 和 OpenCode 都会读取这个文件」。

黄金法则

1. 「保持 100 行以内」 —— 过长的文件会分散注意力
2. 「WHAT / WHY / HOW 结构」 —— 清晰的组织
3. 「解释 WHY」 —— 有上下文的 AI 能做出更好的决策
4. 「添加 NOT TO DO」 —— 防止已知的 AI 倾向
5. 「链接到详细文档」 —— 渐进式披露

CLAUDE.md 示例

# MyApp## WHAT - 项目概述React Native 应用，使用 NX 单体仓库。### 技术栈- TypeScript 5.8, React Native 0.79- UI: Tamagui | 状态: RTK Query## WHY - 架构决策Library-first，因为需要并行开发。## HOW - 约定- 使用 Tamagui 基础组件 — *跨平台一致性*- 禁止 console.log — *生产性能*## 边界- ✅ 必须：提交前运行测试- ⚠️ 先询问：新依赖- 🚫 绝不：提交密钥

上下文窗口 —— 关键的 20-40% 规则

「重要洞察」：质量不是在 100% 上下文时才下降——它从 「20-40%」 就开始下降。

当上下文使用超过 60% 后，AI 会：

• 忘记之前的指令
• 重复同样的错误
• 编辑错误的文件
• 生成更低质量的代码

最佳实践

1. 「一个对话 = 一个功能」
2. 「定期使用 /compact」
3. 「当上下文膨胀时用 /clear 清除」
4. 「更新 SCRATCHPAD.md 用于会话记忆」

危险信号

MCP（模型上下文协议）

连接 AI 工具与外部服务（数据库、API、文档）的标准。

「关键」：Claude Code 和 OpenCode 使用「不同的 MCP 格式」：

「Claude Code（~/.claude/mcp.json）：」

{"mcpServers": {"opencontext": {"command": "oc","args": ["mcp"]    }  }}

「OpenCode（~/.config/opencode/opencode.json）：」

{"mcp": {"opencontext": {"type": "local","command": ["oc", "mcp"],"enabled": true    }  }}

Skills —— 可复用的知识

Skills 是扩展 AI 能力的指令集。它们在 「Claude Code 和 OpenCode 之间共享」。

「目录搜索顺序（OpenCode）：」

「关键洞察」：这是「与提供商无关的」——无论你使用 Claude、GPT、Gemini 还是 GLM，工作方式都相同。

「建议」：使用 ~/.claude/skills/ 存放两个工具共享的 skills。

第三部分：Claude Code 精通

安装

# macOS/Linuxcurl -fsSL https://claude.ai/install.sh | bash# 验证claude --version

必备插件

# 工作流/plugin install commit-commands     # Git 自动化/plugin install code-review         # 质量审查# 集成/plugin install github              # GitHub 集成/plugin install firebase            # Firebase 工具# 分析/plugin install serena              # 语义代码导航/plugin install context7            # 库文档

插件分类

「LSP（语言服务器协议）：」

• csharp-lsp, typescript-lsp, pyright-lsp, gopls-lsp
• 让 Claude 理解类型、检测错误、建议导入

「开发工作流：」

• commit-commands — /commit, /commit-push-pr
• code-review — 质量和安全审查
• pr-review-toolkit — 静默失败检测、类型分析

「集成：」

• github, atlassian, notion, firebase, linear, figma

「浏览器自动化：」

• playwright — E2E 测试
• dev-browser — Claude 控制的浏览器用于验证

自定义代理

在 .claude/agents/ 中创建专门的 AI 助手：

---name: security-reviewerdescription: 专注于 OWASP 的代码审查tools: Read, Grep, Bashmodel: sonnet---你是专注于 OWASP Top 10 的安全审计员。## 方法1. 识别漏洞2. 评级严重程度（严重/高/中/低）3. 提供具体修复方案

Speckit 集成

用于复杂功能的结构化开发：

# 安装uv tool install specify-cli --from git+https://github.com/github/spec-kit.git# 初始化specify init . --ai claude

关键步骤：宪法分析

「对于现有项目，安装后立即运行：」

/speckit.constitution

这会分析你的代码库并提取：

• 代码模式和约定
• 架构决策
• 技术栈细节
• 命名约定

宪法保存到 .specify/memory/constitution.md，帮助 AI 理解你项目的风格。

功能开发工作流

/speckit.specify "user authentication"# 创建规范/speckit.clarify                         # 解决歧义/speckit.plan                            # 技术规划/speckit.tasks                           # 生成任务列表/speckit.implement                       # 执行实现

第四部分：OpenCode 精通

安装

curl -fsSL https://opencode.ai/install | bash# 验证opencode --version

认证

opencode auth login# 根据订阅选择提供商：# - Anthropic（如果有 Claude 订阅）# - OpenAI（如果有 ChatGPT Plus）# - Google（如果有 Gemini）

oh-my-opencode —— 多代理系统

oh-my-opencode 将 OpenCode 转变为多代理编排系统。

「订阅级别说明」

安装

# 示例：仅 ChatGPT Plus（OAuth 阻断后）npx oh-my-opencode install --no-tui \  --claude=no \  --openai=yes \  --gemini=no# 或交互式安装npx oh-my-opencode install

代理系统

Ultrawork 模式

触发并行代理执行：

ulw: implement authentication with tests and documentation

「警告」：”Token 熔炉”——每次会话可能花费 $50-100。

MCP 配置

「重要」：OpenCode 的 MCP 格式与 Claude Code 不同！

mkdir -p ~/.config/opencodecat > ~/.config/opencode/opencode.json << 'EOF'{"mcp": {"opencontext": {"type": "local","command": ["oc", "mcp"],"enabled": true    }  }}EOF

或使用 CLI：

opencode mcp add opencontext --command"oc mcp"opencode mcp list

规则系统

两种方法：

1. 项目根目录的 「CLAUDE.md」（简单）
2. 「.opencode/rules/」 目录（模块化）

两者都有效。OpenCode 也会读取 CLAUDE.md 文件。

第五部分：正面比较

性能（真实测试）

基于 Opus 4.5 的社区基准测试：

「注意」：OpenCode 的 UX 被广泛称赞为更优秀。

功能比较

质量观察

「Claude Code 优势：」

• 更好的指令遵循
• 需要更少的修正
• 更快的完成速度

「OpenCode 优势：」

• 编写更多测试
• 更好的 UX
• 模型灵活性

「OpenCode 常见问题」：导入 bug —— 持续无法添加导入，以为已经添加了。

第六部分：选择你的工具

快速决策矩阵

基于场景的建议

AI 编程新手

「推荐」：OpenCode

原因：

• 免费开始
• 试验不同模型
• 无需财务承诺即可学习
• 庞大的社区支持

专业开发者

「推荐」：Claude Code

原因：

• 官方支持
• 更好的指令遵循
• 更快的执行
• 企业 SLA 可用

注重成本的团队

「推荐」：OpenCode + ChatGPT Plus

原因：

• 每位开发者 $20/月
• GPT-4.1 质量良好
• 无供应商锁定

质量关键项目

「推荐」：Claude Code

原因：

• 最佳代码质量
• 更好的指令遵循
• 需要更少的修正

多模型实验

「推荐」：OpenCode

原因：

• 75+ 提供商
• 轻松切换模型
• 比较输出

第七部分：同时使用两个工具

自动共享的内容

「结果」：~/.claude/skills/ 中的 skills 自动适用于两个工具。

需要手动同步的内容

MCP 同步脚本

# Claude Code → OpenCode（带格式转换）jq '{  mcp: (.mcpServers | to_entries | map({    key: .key,    value: {      type: "local",      command: ([.value.command] + .value.args),      enabled: true    }  }) | from_entries)}' ~/.claude/mcp.json > ~/.config/opencode/opencode.json# OpenCode → Claude Codejq '{  mcpServers: (.mcp | to_entries | map({    key: .key,    value: {      command: .value.command[0],      args: .value.command[1:]    }  }) | from_entries)}' ~/.config/opencode/opencode.json > ~/.claude/mcp.json

最佳实践

1. 「每个项目选择主要工具」 —— 在 .tool-preference 中记录
2. 「切换前同步」 —— 运行同步命令
3. 「为任务使用合适的工具」：

• Claude Code：Speckit、精确工作、GitHub 集成
• OpenCode：多代理、实验、本地模型

第八部分：高级主题

跨平台工具

这些工具在 「Claude Code 和 OpenCode」 上工作方式完全相同：

Speckit（规范驱动开发）

# 两个工具安装相同uv tool install specify-cli --from git+https://github.com/github/spec-kit.git# 初始化（唯一区别是 --ai 标志）specify init . --ai claude    # 用于 Claude Codespecify init . --ai opencode  # 用于 OpenCode# 命令在两个工具中工作相同/speckit.constitution/speckit.specify "feature"/speckit.implement

OpenContext（跨项目记忆）

# 相同安装npm install -g @aicontextlab/clioc init# MCP 配置因格式而异，但功能相同# 两个工具获得相同的上下文和记忆能力

「为什么重要」：你可以在工具之间切换而不会丢失工作流。规范、宪法和上下文是共享的。

自主模式（YOLO 模式）

❝

⚠️ 「极度谨慎使用」 —— 这些模式跳过所有权限提示。仅在受信任的隔离环境中使用。

❞

Claude Code

claude --dangerously-skip-permissions

「安全限制：」

• 不会以 root 或 sudo 运行
• 无人值守运行直到完成
• 无文件编辑或 bash 命令确认

OpenCode

// 在 opencode.json 中{"permission": {"*": "allow"  }}

或按工具：

{"permission": {"bash": "allow","edit": "allow"  }}

何时使用

✅ 「适当：」

• 隔离的 Docker 容器
• 一次性 VM
• 范围受控的 CI/CD 管道
• 自动化测试环境

❌ 「绝不使用：」

• 生产服务器
• 包含敏感数据的系统
• 共享开发机器
• 运行不受信任的提示时

最佳实践

# 在一次性容器中运行docker run -it --rm -v $(pwd):/app node:20 bashcd /app && claude --dangerously-skip-permissions

「记住」：一个错误的命令可以删除文件、暴露密钥或损坏你的系统。权限提示是为了保护你而存在的。

Hooks 与持续学习

Claude Code Hooks

Claude Code 通过 hooks 支持基于事件的自动化：

「示例：编辑后自动 lint」

{"hooks": {"PostToolUse": [{"matcher": "Edit|Write","hooks": [{"type": "command","command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""      }]    }]  }}

Claudeception：持续学习系统

「问题」：Claude 每次会话都重新开始。45 分钟的调试会话在下一次会话中被遗忘。

「解决方案」：Claudeception 自动提取非显而易见的发现，并保存为可复用的 skills。下次遇到同样的问题时，Claude 已经知道解决方案。

❝

另见：Production-Grade AI Development with Claude Code

❞

OpenCode：无原生 Hook 系统

「OpenCode 的变通方案」：使用外部自动化（shell 脚本、make 目标）或等待社区插件如 opencode-skillful。

社区资源

模板与 Skills

• aitmpl.com —— 代理、命令、模板
• skills.sh —— 200+ 可安装 skills
• Context7 CLI —— 跨平台 skills

「安装：」

npx skills add vercel/react-best-practicesnpx ctx7 skills install better-icons

附录：快速参考

命令比较

目录结构

# 全局（用户级别）~/.claude/├── CLAUDE.md           # 全局上下文├── mcp.json            # MCP 服务器├── settings.json       # Hooks、首选项└── skills/             # 共享 skills（也适用于 OpenCode）# 项目级别.claude/├── CLAUDE.md           # 项目上下文├── agents/             # 自定义代理│   ├── code-reviewer.md│   ├── security-auditor.md│   └── ios-developer.md├── commands/           # 自定义斜杠命令│   ├── git-pr.md│   └── speckit.*.md├── hooks/              # 自动化 hooks│   ├── post-edit-lint.sh│   └── validate-branch-name.py└── skills/             # 项目特定 skills~/.config/opencode/├── opencode.json       # 配置 + MCP├── oh-my-opencode.json # oh-my-opencode 配置├── rules/              # 全局规则├── skills/             # 全局 skills└── agents/             # 全局自定义代理    └── review.md# 项目级别（OpenCode）.opencode/├── agents/             # 项目特定代理│   └── ios-expert.md├── rules/              # 项目规则└── skills/             # 项目 skills

OpenCode 代理格式

---description: 代码审查专家mode: subagentmodel: anthropic/claude-sonnettemperature: 0.3permission:  edit: deny  bash: asktools:  write: false  edit: false---你是专注于...的代码审查员

结论

2026 年的 AI 编程领域提供了强大的选择：

• 「Claude Code」 用于官方支持、速度和质量
• 「OpenCode」 用于灵活性、成本优化和实验
• 「oh-my-opencode」 用于多代理自动化（有注意事项）

「从这里开始：」

1. 如果刚接触 AI 编程 → 尝试 OpenCode（免费）
2. 如果是专业/团队 → 从 Claude Code 开始
3. 随着成长 → 学习为不同任务使用两个工具

关键是理解这些工具相互补充。为每个任务选择合适的工具，你将成倍提高生产力。

❝

「注意」：对于企业级质量门禁和 TDD 工作流，MoAI-ADK 也值得探索。

❞

资源

官方

• Claude Code 文档
• OpenCode 文档
• oh-my-opencode