posts

从 Claude Code 到 Pi：传统 CC 用户的避坑与进阶指南

2026年7月29日 3 min read

作为一个习惯了 Claude Code (CC) 的用户，当你转向 Pi 时，最大的感受会是：从「全自动黑盒保姆」变成了「手动挡极客赛车」。本文整理了思维转换指南、CC 用户最容易踩的坑，以及 Pi 独有的杀手锏技巧。

作为一个习惯了 Claude Code (CC) 的用户，当你转向 Pi 时，最大的感受会是：从"全自动黑盒保姆"变成了"手动挡极客赛车"。

CC 是 Anthropic 官方出品的"新手套装"，自带 1.5 万 tokens 的庞大系统预设、严密的权限护栏和丰富的内置工具；而 Pi 的核心系统提示词不到 1000 tokens，只有 4 个基础工具，一切透明可控。

以下是为你整理的思维转换指南、CC 用户最容易踩的坑，以及 Pi 独有的杀手锏技巧。

一、核心差异与思维转换 (Mindset Shift)

对比维度 Claude Code (CC) Pi Agent 思维转换建议
系统预设 庞大（~1.5万 tokens），隐式注入大量规则 极简（<1000 tokens），完全透明 别再指望模型"天生懂规矩"，规矩要靠你自己写在 AGENTS.md 里。
权限管理 严格（Yolo 模式 vs 每次确认），有 Allowlist 相对粗放，依赖 bash 工具本身或外部沙箱 Pi 默认可能很"野"，执行危险命令前必须自己做好 Git 提交或使用 Docker 沙箱。
工具生态 丰富（内置 Bash, Read, Write, WebSearch, Memory 等） 极简（仅 read, write, edit, bash） 忘记 CC 的 /search 或内置 Memory。在 Pi 里，一切高级功能要么用 bash 代理，要么自己写 TS 扩展。
上下文管理 自动压缩（Auto-compact），黑盒 手动/半自动压缩（/compact），树形分支 习惯使用 /tree 和 /fork 来管理上下文，而不是依赖 CC 的自动遗忘机制。
模型绑定 深度绑定 Claude（虽支持第三方，但最优是 Claude） 模型无关（随时切换 OpenAI, Gemini, 本地 Ollama） 利用多模型优势：复杂架构用 Claude，简单重构切便宜的 GPT-4o-mini 或本地模型省 Token。

二、CC 用户迁移到 Pi 最容易踩的 5 个"坑"

坑 1：以为 Pi 也有 CLAUDE.md 的自动记忆机制

  • CC 体验：CC 会自动读取 CLAUDE.md，甚至能在对话中主动提议"把这条规则加入记忆"。
  • Pi 现实：Pi 使用 AGENTS.md，但它不会自动帮你写进去。
  • 避坑技巧：在 AGENTS.md 中明确写入指令："每次任务结束时，如果发现了新的项目约定或踩坑经验，请使用 edit 工具将其追加到本文件的 ## 经验教训 章节中。" 让模型通过 edit 工具自己维护记忆。

坑 2：习惯了 CC 的 /init 和开箱即用的项目分析

  • CC 体验：输入 /init，CC 会扫描项目并生成一份漂亮的 CLAUDE.md。
  • Pi 现实：Pi 没有 /init。它启动时只会静默读取当前目录的 AGENTS.md。
  • 避坑技巧：你需要自己编写第一版 AGENTS.md。可以通过 Pi 的 -p (print) 模式让模型帮你生成： 
    pi -p "分析当前项目结构，生成一份详细的 AGENTS.md 草案，包含启动命令、目录说明和代码规范，输出为 Markdown 格式" > AGENTS.md

坑 3：对 Bash 工具的"裸奔"感到恐慌

  • CC 体验：CC 执行 rm -rf 或 git push --force 时会疯狂弹窗警告，或者被 Allowlist 拦截。
  • Pi 现实：Pi 的 bash 工具默认非常直接，模型如果"幻觉"了，可能会直接执行危险命令。
  • 避坑技巧：
    1. Git 护体：养成习惯，在给 Pi 布置大任务前，先 git commit。
    2. 系统级 Alias：在你的 shell 配置中，将 rm alias 为 rm -i，或者使用 trash-cli 替代 rm。
    3. 使用沙箱：如果项目敏感，使用 Docker 或 Nix flake 启动一个隔离环境再运行 Pi。

坑 4：找不到 WebSearch 和 Fetch 工具

  • CC 体验：CC 内置了联网搜索和抓取网页的能力，遇到不懂的 API 会自动去查。
  • Pi 现实：Pi 核心没有联网工具。
  • 避坑技巧：
    • 轻量级替代：写一个 20 行的 Pi Extension，调用 Tavily API 或 DuckDuckGo。
    • Bash 代理：直接在 AGENTS.md 中告诉 Pi："如果需要查阅最新文档，请使用 bash 工具执行 curl -s https://... 或 npx @anthropic-ai/claude-code-search ..." (利用现有的 CLI 工具)。

坑 5：线性对话的"死胡同"

  • CC 体验：CC 是线性的，如果模型在第 10 步走错了方向，你只能不断纠正，上下文越来越脏，最后只能 /clear 重开。
  • Pi 现实：Pi 拥有树形会话（Tree Session）。
  • 避坑技巧：这是 Pi 最大的杀手锏！当模型提出两种不同的重构方案时，不要让它在一个回复里写完。使用 /fork 命令，分叉出两个独立的会话分支，让模型在 Branch A 尝试方案一，在 Branch B 尝试方案二。最后通过 /tree 对比结果，保留更好的那个分支。

三、Pi 独有的进阶使用技巧（CC 里做不到的）

1. 上下文"透视眼" (Verbose Mode)

CC 是个黑盒，你不知道它到底喂给模型了什么。Pi 提供了极致的透明度。

  • 技巧：启动时加上 --verbose。Pi 会在终端侧边栏或日志中，精确显示当前 System Prompt 的内容、注入的 AGENTS.md 文本、以及每次 Tool Call 的原始 JSON。
  • 用途：当模型行为诡异时，立刻开 verbose 看看是不是上下文被截断了，或者是不是有奇怪的隐式注入。

2. 极致的 Token 成本控制 (Model Switching)

CC 默认全程使用昂贵的 Claude Sonnet/Opus。

  • 技巧：Pi 支持在会话中途或通过参数无缝切换模型。
    • 日常闲聊/简单脚本：pi --provider openai --model gpt-4o-mini (极便宜)
    • 复杂架构设计/核心算法：pi --provider anthropic --model claude-sonnet-4-20250514
  • 高阶玩法：写一个 Extension，监听 Pi 的事件流。当检测到用户输入包含"重构"、“架构"等关键词时，自动在底层切换为高级模型；当检测到"写个正则”、“改个 CSS"时，自动降级为廉价模型。

3. Headless 模式与 CI/CD 深度集成

CC 的 headless 模式相对较重。Pi 的 -p (print) 和 --mode json 是为自动化而生的。

  • 技巧：在 GitHub Actions 或 GitLab CI 中，将 Pi 作为一个"代码审查员"或"自动修复器”。 
    # 在 CI 中自动修复 Lint 错误
pi -p "运行 pnpm lint，如果有错误，请使用 edit 工具自动修复它们，并输出修复的文件列表" --provider anthropic --no-interactive
  • JSON 模式：使用 --mode json，Pi 会将所有的思考过程、工具调用以 JSONL 格式输出，你可以用 jq 轻松解析，提取出模型到底修改了哪些文件，用于后续的自动化部署。

4. 自定义系统提示词的"手术刀"

CC 的系统提示词你改不动。Pi 允许你像做手术一样精确控制。

  • 技巧：
    • --system-prompt "你是一个严苛的 Rust 编译器，任何 unsafe 代码都必须给出详细理由" (完全替换默认提示词)
    • --append-system-prompt "当前时间是 2026 年，请使用最新的 React 19 语法" (追加提示词)
    • -nc (no-context-files)：禁用所有 AGENTS.md 的加载，让模型在"纯净"状态下执行一次性脚本。

四、总结：给 CC 用户的最终建议

  1. 不要试图把 Pi 变成 CC：如果你想要 CC 那种无微不至的照顾和严密的安全护栏，请继续使用 CC。Pi 的魅力在于它的底层逻辑完全向你敞开。
  2. 拥抱 AGENTS.md：在 Pi 里，AGENTS.md 就是你的"灵魂"。你写得越详细、越结构化，Pi 的表现就越接近甚至超越 CC。
  3. 善用 /fork 和 /tree：这是你摆脱线性对话泥潭、进行 A/B 测试和并行探索的最强武器。
  4. 从小扩展开始：不要一开始就试图接入复杂的 MCP。先尝试写一个 10 行的 TS 扩展，比如"每次执行 bash 后自动运行 prettier 格式化代码"，你会发现 Pi 的扩展系统比 CC 的 Hooks 简单得多。

💡 一句话总结：Claude Code 是一辆装满电子辅助系统的自动挡豪华车，而 Pi 是一辆没有空调、没有助力转向，但引擎盖完全透明、你可以随时更换零件的 F1 赛车。适应它，你就能跑出 CC 跑不出的极限圈速。