工欲善其事必先利其器。本章搭建一个可工作 + 可沉淀的环境：从 L1 补全到 L3 Agent harness，从单一工具到多工具协作，附带一份让你能直接照抄的"五文件起手配置"。

8.1 起手目标

本章结束，你应有：

  • 一个能跑 Claude Code / OpenCode 的终端
  • 一个支持 OpenAI / Anthropic 互换的 model 后端配置
  • 一份 AGENTS.md / CLAUDE.md / OPENCODE.md (按你选择的工具)
  • 一份 .opencode/skills/ 或 .claude/skills/ 目录（即使空着）
  • 一份 SECURITY.md 兜底
  • 一个本地运行的开发日记脚本：记录你今天回到了哪些 prompt

8.2 选 L1：先架 IDE 这层

选项 A：VS Code + Copilot / Continue

# 安装 VS Code（如未）
winget install Microsoft.VisualStudioCode     # Windows
brew install --cask visual-studio-code         # macOS

# 装 GitHub Copilot 扩展 → 登录 → 默认开启 Tab 补全
# 或 安装 Continue（开源替代） → 配置自托管后端

优点：稳、所有 AI 协作出现兼容性的起点 缺点：还是要靠你切换工具

选项 B：Cursor（all-in-one）

# 直接装 Cursor；它本身是 VS Code fork
# 一次 import 你 VS Code 的 settings / extensions

优点：内置 chat + agent 体验统一 缺点：默认比较激进——在长任务里你来不及 preview

8.3 选 L3：Agent harness 必装一个

至少要装一个 —— 后续课程大量出现。

8.3.1 Claude Code（最快上手）

npm i -g @anthropic-ai/claude-code
claude-code          # 直接进入 REPL
  • 需 Anthropic API key（或走 Claude.ai 订阅）
  • 创建 CLAUDE.md 项目级 system prompt

8.3.2 OpenCode（开源 / 可二开 / 本课程默认）

# 走官方 install script / binary
# macOS/Linux
curl -fsSL https://opencode.ai/install | bash

# Windows PowerShell（你是 OK）
irm https://opencode.ai/install.ps1 | iex

配置 opencode.json/opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-opus-4-5",
  "provider": {
    "anthropic": { "models": { "claude-opus-4-5": {} } }
  },
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

关键选项：

  • "permission.edit": "ask" 表示改文件先问你；高自由度任务设 "auto"（在主线任务里少用）
  • "permission.bash": "ask" 同上

8.3.3 Codex CLI（OpenAI 派）

npm i -g @openai/codex

跟 Claude Code 类似，模型不同。Continuous 装二开版本（LazyCodex 等）会更顺手。

8.4 一份"五文件起手包"

任何项目，我建议从一开始就有这 5 份文件 —— 它们是你跟模型共享的"项目宪法"。

your_project/
├── AGENTS.md          ← 主文档：所有 L3 工具都认
├── SECURITY.md        ← 安全红线
├── .gitignore         ← 必须忽略 .env / .opencode/ / .claude/
├── README.md          ← 项目自我介绍
└── .opencode/         ← 沉淀 Skill 目录（Claude Code 用 .claude/）
    └── skills/        ← 后面 Skill 篇逐步填满

8.4.1 AGENTS.md 模板

# AGENTS.md

## 项目概览
<一句话：是什么、面向谁、当前阶段>

## 技术栈
- 主语言: <e.g. Python 3.13>
- 后端: <FastAPI / Hono / 内嵌>
- 测试: pytest，运行 `pytest -x`
- Lint: ruff + basedpyright

## 强约束（NEVER）
- 不接受 `as any` / `@ts-ignore` / `# type: ignore`
- 不引入新依赖而不在 README 标 license
- 不在 prompt / Skill 里嵌真实 secret，统一走 `os.getenv`
- 不修改 public API 的签名而不加 PATCH 纪录

## 协作偏好
- 给 diff 优先于整段重写
- 不超过 250 行 PR
- 任何长任务在 30s 内能看到一个结果
- 失败 2 次必须停下来诊断，而不是再试

## 常用脚本
- 测试: `pytest -x`
- 类型: `basedpyright src/`
- 构建: `task build` 或 `task hugo-build`（此项目用 taskfile）

8.4.2 SECURITY.md 模板

# SECURITY.md

## 受限信息
- API token / 密钥 / 真实用户数据 一律走 `os.getenv`，不入 git
- `.env` 永不 commit，靠 `.gitignore` 兜底

## 受限操作
- 不修改生产数据；任何"看似 demo"的删除要做 dry-run
- 不替换 license / 不裁剪 license 标识
- 不引入未知 license 的第三方包不加白名单审批

## 评审重点
- SQL 拼接（所有 query 必须参数化）
- 路径穿越（Path 入参必须 normalize + bound check）
- 命令执行（os.system 的字符串拼接一律拒绝）

8.4.3 把这两份"上链"

OpenCode / Claude Code 等都自动加载项目根 AGENTS.md。如果两个都用，开 symlink：

ln -s AGENTS.md CLAUDE.md      # macOS / Linux
New-Item -ItemType SymbolicLink -Path CLAUDE.md -Target AGENTS.md    # Windows

8.5 预算自检：你今天烧了多少 token

最容易踩的坑：忘了配 max_tokens / 不读 usage 日志。

# Anthropic API 用量从 web 控制台抓
# OpenCode 在 ILogger 默认开日志，看一下 .opencode/log

写一个小脚本：每晚 cron 跑一下当天 AI 改动次数和单次 PR 大小，超过阈值就 warning——别让"放任型 vibe coding"今晚就烧光月配额。

8.6 起步验证清单

□ 我能在一个命令里启动 Claude Code 或 OpenCode
□ 项目根有 AGENTS.md，且工具能 grep 到它的内容
□ .opencode/skills/ 目录存在（可以为空）
□ .gitignore 含 .env, *.key, .opencode, .claude
□ SECURITY.md 里写了 secret / 路径 / 命令 三条红线
□ `pytest` / `task build` / 主入口能跑通

全勾上后的"工作完成感"在 2026 年是真实进度感的——不是"我今天打了多少行"，是"我的环境准备好下一周承接 30 篇 vibe coding"。

8.7 小结

  • L1（Copilot / Cursor）必装，L3（Claude Code / OpenCode）至少装一个
  • 五文件起手包：AGENTS.md / SECURITY.md / .gitignore / README / .opencode/skills/
  • 用 symlink 把 AGENTS.md 上链到 CLAUDE.md，让工具跨平台/工具协作

下一篇：《09 Agent 概念：从助手到自治》——进入 Agent 篇，开始让 AI 不只是回话，而是去做事。

Summary: 五文件起手包 + Claude Code / OpenCode 二选一，搭好后续 22 篇 vibe coding 的舞台。