Claude Code Vibe Coding初体验
hutusi约 15 分钟本期周刊介绍 Claude Code 的使用方法，使用 Claude Code 完成特定编程任务的探索，及 CLAUDE.md 的相关实践。
0. 准备
按照官网上的指导安装，MacOS 推荐用 HomeBrew (brew install claude) 安装即可。在终端上输入 claude 命令进入 Claude Code 交互界面，输入 /login 命令登录，有两种模式，一种是 Claude.ai 订阅，一种是配置Claude API Key，前者按月付订阅费，后者按使用Token计费。我使用的是订阅模式，选择该模式登录后会引导到 Web 端登录。Claude 有两档订阅付费选择: Claude AI Pro 和 Claude AI Max, 前者每月约20美元左右，后者则是每月100美元起步。普通开发订阅 Pro 版本就够了。
不过，订阅 Pro 只是第一步。由于 Claude 的公司 Anthropic 创始人对中国态度极不友好（找个机会单独写一下），Claude 会经常封禁来自中国IP的账号，并且在使用 Claude Code 时也会检测所属 IP, 所以在跳转网页登录成功后，终端命令行上报 403 forbidden 的错误。后来搜了下网上经验，发现是终端没有穿墙，执行 curl ipinfo.io显示 IP 地址为国内城市。在尝试了若干方法后，发现 MacOS 上需要安装 ClashX Pro, 然后打开 Proxy Mode(Global) + System Proxy + Enhanced Mode 几个组合选项，终于实现终端上穿墙，才得以通过 Claude Code 的登录验证。
登录后便可以在 Claude Code 终端交互界面上执行命令，Claude Code 的命令以 / 开头，可以通过 /models 选择模型，默认是 Haiku 4.5, 一个轻量但快速的模型，想要更强悍的能力，可以选择 Sonnet 4.5, 或最新推出的 Opus 4.5 (需要 Max 订阅账户)。
1. 工作尝试
1.1 任务一：全新创建 Nextra 文档网站（模型：Haiku 4.5）
1、初始化并创建 CLAUDE.md
首先我创建了一个空的目录，里面没有任何文件，然后在 Claude Code 上输入: /init, Claude 便开始分析当前的codebase:
> /init is analyzing your codebase…
⏺ I'll analyze this codebase and create a CLAUDE.md file. Let me start by exploring the repository structure and understanding the project.
Claude 调用 git, find, ls 等工具搜索当前文件夹里的文件。由于这是个空目录，Claude发现没有历史记录，也没有任何文件，于是表示它无法生成 CLAUDE.md, CLAUDE.md是一个文档文件，用来描述代码仓的架构、构建命令、测试准备和项目工程相关信息，不包含实际的代码。
如果想要完成初始化并创建 CLAUDE.md，Claude给出三个选择：
先往当前目录代码仓中添加代码，有了代码，Claude便可以根据代码理解来生成 CLAUDE.md.如果这是个计划中的项目，那么告诉 Claude 这个项目的相关信息，比如语言、框架等。 重新指向一个已知项目，里面包含代码等信息。
我告诉 Claude 生成网站的指令，让它直接生成网站代码及 CLAUDE.md
2、根据指令生成网站
我告诉Claude想要生成一个文档网站，使用最新版本的 Next.js, Nextra, 并使用 pnpm 作为包管理器，优先使用 TypeScript.
> I want to create a documentation website using the latest version of Next.js and Nextra, using pnpm as the package manager, Prefer using TypeScript.
Claude 开始理解指令并分解任务。Claude 拆解得比较细，分了：
创建项目初始文件：包括 package.json,tsconfig.json,next.config.ts,theme.config.tsx,.eslintrc.json, 等，这些是 Next.js 项目的基础配置文件。生成 Nextra 网站页面文件：如 pages/_app.tsx,pages/_document.tsx等，还有一些mdx,_meta.json文件等。根据所生成代码形成的 codebase 创建 CLAUDE.md文件并写入生成内容，CLAUDE.md里面详细记录了该项目使用到的技术栈、项目结构、关键功能、工程脚本等信息。
做完这些事情后，Claude 更新了 TODO list, 然后做了一个文字小结，并给出了下一步要做的事情，安装依赖包、启动开发环境调试、定制网站等。
3、增强网站内容
我让 Claude 继续完成整个网站：
> Please make this website completely.
因为我蹩脚的英语，Claude 理解成做一个全面的网站，于是 Claude 来劲了，它准备生成一个架构全面、带自定义组件、且内容丰富的文档网站。
⏺ I'll create a comprehensive documentation website with a complete structure, custom components, and rich content. Let me build this out.
⏺ Let me start by creating a rich homepage and expanding the documentation structure:
... (以下生成内容略)
这还不够，Claude 紧接着又生成了 案例、API 指南、高级话题等内容。并更新了 CLAUDE.md. Claude 时刻不忘更新 CLAUDE.md.
不过一开始生成复杂内容（大多数为Fake）的网站并不是好实践，这会影响后续的重构。
3、调试&bugfix
当我打开 Claude 生成的网站，报错了：
我将错误信息告知 Claude:
> When run this website in dev mode, it prompts error: [Error: Support of "_meta.json" was removed, use "_meta.{js,jsx,ts,tsx}" instead. Refactor following file "pages/_meta.json".]
Claude便开始定位问题，认识到要将 json 转成js或ts文件，考虑到前面要求优先使用 TypeScript，因此它改为 ts 文件：
⏺ I need to fix the _meta.json files to use the newer Nextra format. They should be .ts or .tsx files instead. Let me update all of them:
改写成 ts 文件并删除原 json 后，Claude 提示我说它已经解决了问题。但当我打开网站时，新的问题出现了：
Validation of "_meta" file has failed.
The field key "api" in `_meta` file refers to a page that cannot be found, remove this key from "_meta" file.
我把这个新问题抛给 Claude Code, 报错是说 _meta 文件中关键字api所提及的文件找不到，于是 Claude 先到 api 目录中查是否存在 _meta文件，然后又在整个 pages 目录里查找，如此检查了一番之后。Claude 一副胸有成竹的样子说它知道问题所在了，是新版本的Nextra使用了不同格式的meta文件，这语气像个十足老登程序员：我做项目那会还是什么什么，现在新版本都改成这样了……
⏺ I see the issue. The newer version of Nextra uses a different format for meta files. Sections with folders need to be defined differently. Let me check the Nextra documentation format and fix this properly:
修改完 _meta.ts 文件后，还非常谨慎的又改了其他相关文件，然后Claude启动服务，启动失败报错，不过 Claude 自己又去定位问题并解决，最后成功启动服务，这里我就不把过程贴出来了。Claude 自信满满的说完美：
⏺ Perfect! ✅ Fixed and Running!
The development server is now running successfully without errors!
服务器运行虽然没有问题，但访问网站时又报错，还是原来的错误，我把错误信息发给 Claude 打了它一脸。这次 Claude 不再傲娇了，而是谨慎地开始检查文件结构：
⏺ The issue is that Nextra is looking for actual page files. Let me check what the error is more carefully and adjust. The problem might be that each folder needs to either have an index.mdx or the _meta.ts needs to reference it differently. Let me check the actual file structure:
接下来又检查了文件内容和报错日志输出信息。根据报错日志的输出信息，Claude 先尝试了将 api 从_meta.ts 文件中删除，删除后可以正常加载的，但页面报了验证错误，于是 Claude 又改回去。
⏺ The issue is specifically with the "api" key. Let me check if there's something wrong with the api folder. Maybe I need to look at how Nextra expects the structure. Let me try removing "api" from the _meta.ts temporarily to see if the server works:
......(修改文件略)
⏺ Good! It's now showing GET / 200 which means the page loaded! But there's still a validation error. Let me add the api back and check the api/_meta.ts file to see if there's an issue there:
......(修改文件略)
改回后又得到了 500 服务器错误，再检查文件内容没什么问题后，Claude 觉得有可能是因为 api 是 Next.js 的保留字，于是尝试将它改名：
⏺ I see it's returning 500 errors. This is a Nextra validation issue. The problem might be that the api folder exists but Nextra can't resolve it properly. Let me try renaming it or restructuring.
⏺ The files look fine. The issue might be that api is a reserved word in Next.js (it's used for API routes in the /pages/api directory). Let me rename the api folder to api-reference:
同步修改其他相关文件后，重启服务并验证访问页面返回状态码，得到 200 后还不放心，检查终端输出是否有错误信息。
⏺ Excellent! I see GET / 200 which means it's working now! The errors in stderr are just warnings but the page is loading. Let me check the full output to see if there are any new error messages:
终端上有一些错误输出，Claude 觉得应该是 cache的问题，于是清理 Next.js 的cache, 重启服务：
⏺ I see - the error is still referencing "api" from the old file. The cache needs to be cleared. Let me kill the server, clear the Next.js cache, and restart ...
在检查完页面和终端都没有报错后，Claude 宣布它终于解决了问题：
⏺ Perfect! ✅ Fixed and Running Successfully!
The website is now running without any validation errors!
我打开浏览器，试用了下，问题确实都解决了。
任务二：升级依赖包及迁移 Next.js 路由模式（模型：Sonnet 4.5）
网站运行和操作都没有什么问题，我打开代码看了一下，初略一看发现有两个问题，一个是 package.json 里依赖的 Next.js 和 Nextra 包都比较老旧，第二个问题是路由模式采用的是 Next.js 已不再推荐的 pages 模式。因此，我打算让 Claude Code 重构一下，解决这两个问题。
在重构之前，我想先换下模型，在任务一的时候我没有换模型，采用的是安装 Claude Code 后默认的 Haiku 模型，该模型响应快，但能力稍弱。从这个任务开始，我换成了 Sonnet 4.5 模型。
切换模型后，我让 Claude 升级 Next.js 和 Nextra:
> please update next.js to 16, and update nextra to 4.6
Claude 接到任务，它便开始分析项目里的组件版本及依赖，经过一系列分析之后，它发现了一个问题。当前不能直接升级 Nextra 版本，因为当前项目使用的 Next.js 路由模式为 Pages 而非 App, 而新版本的 Nextra 已经不支持 Pages 路由。
⏺ I've discovered a critical compatibility issue: Nextra 4 only supports
Next.js App Router and has dropped support for the Pages Router. Your
project currently uses the Pages Router (with the pages/ directory
structure).
Claude 于是让我选择是否将当前的路由模式重构成 App Router, 在我确认后，Claude 便开始做重构迁移了。具体的过程我就不再追溯，总之经过了几个问题的定位处理后，Claude 最终将路由模式迁移成功，也将 Next.js 和 Nextra 的依赖包版本升级到了新版本。
任务三：重构代码（模型：Sonnet 4.5）
文档网站基本成型，但仔细看项目代码，还是有些不太满意的地方。比如，文档页面都以 JSX 的格式放在 app 目录下，这显然还是 Next.js 网站的设计方式，而不是 Nextra 文档站点的推荐设计。Nextra 推荐将文档从 app 中分离出来，以 MDX 格式放在 content 目录下，做到文档内容与页面样式分离，这样就像一些静态博客框架（如 Jekyll）的设计一样，博客内容是博客内容，网站样式是网站样式，二者解耦，后续当用户想换网站风格了，无需修改内容页面。
由于互联网上 Next.js 的资料远远大于 Nextra, 所以我觉得大模型本身可能会偏向于 Next.js 的设计，于是我在指示 Claude Code 重构时，明确指出让它参考并学习 Nextra 的文档。
> learn this: https://nextra.site/docs/file-conventions/content-directory , and refactor this repository.
Claude 表示它将学习 Nextra 的文档并以最佳实践来重构代码仓。
⏺ I'll learn about Nextra's file conventions from the documentation and then refactor the repository to follow best practices.
⏺ Fetch(https://nextra.site/docs/file-conventions/content-directory)
⎿ Received 279.8KB (200 OK)
⏺ Fetch(https://nextra.site/docs/file-conventions)
⎿ Received 220.5KB (200 OK)
......(其他查找搜索内容省略)
Claude 不但获取了我要求它参考的页面，还主动获取了上级目录等其他信息，并阅读了本地代码仓的内容，然后理解了当前代码结构存在的问题，对比 Nextra 的最佳实践，并给出了重构策略。不得不说，Claude 理解和总结能力挺强，这要在大厂妥妥的火车头。
Refactoring Plan
Current Structure Issues:
- Using app/page.mdx pattern (Next.js App Router convention)
- Content files scattered in app/ directory with subdirectories
- Mixing content with routing configuration
Nextra Best Practice (Content Directory Pattern):
- Create a content/ directory for all MDX files
- Use simple naming: content/index.mdx, content/getting-started.mdx, content/guide.mdx
- Create a gateway file at app/[[...mdxPath]]/page.jsx to route to content
- Move _meta files to the content directory
- Cleaner separation between routing and content
Benefits:
- ✅ No server restart needed when editing content
- ✅ Better hot reloading
- ✅ Simpler file organization
- ✅ Follows Nextra recommended patterns
Let me implement this refactoring:
......（重构过程省略）
重构结束后运行报了一个 500 服务器错误，告诉它后，Claude 自己调试了一会，然后就解决了问题，重构完成。
任务四：定位并解决问题（模型：Sonnet 4.5）
现在网站从呈现效果和代码结构都可用了，不过实际交互时发现了一个bug: 在点击搜索框搜索时提示报错：
Failed to load search index. Search isn't available in development because Nextra 4 uses Pagefind package, which indexes built '.html' files instead of '.md'/'.mdx'.
我将这个报错信息告知 Claude Code, 并让它解决这个问题。Claude 便开始分析代码文件并很快有了答案。
⏺ I can see the issue. Nextra 4 uses Pagefind for search, which only works on built HTML files, not in development mode. Let me investigate the current search configuration and help you set it up properly.
......(分析过程及解决方案略)
Claude 认为搜索组件 Pagefind 依赖编译后的 HTML 文件，便给了一些修复选项，并建议在生产模式而非开发模式下使用搜索。我采用此建议发现原先的报错没有了，但又有新的错误：
Failed to load search index. TypeError: failed to fetch dynamically imported module: http://localhost:3000/_pagefind/pagefind.js
在告诉 Claude 报错后它开始定位问题，并搜索 Pagefind 的配置方法等信息，在过程中它请我允许它执行 pnpm buildpnpm start 等命令自己编译并调试，最终得以解决问题。
最后页面效果如下。
2. 与同类工具对比
在试用 Claude Code 的同时，我也用同样的指令对 Codex (模型： gpt-5.1-codex-max)和 Gemini Cli(模型： gemini-2.5-pro). Codex 在大部分任务能够顺利完成，但有些时候就会犯傻，怎么也生成不了或解决不了问题。而 Gemini Cli 在我让它生成网站的任务就没有走通过，只好放弃。所以后来 Claude Code 和 Claude.ai 成了我每天都用的工具，而 Codex 甚至是一直用的 ChatGPT 也被我疏远了。
无论从功能、体验还是任务完成度来看，Claude Code 都远超同类产品。而这种用户体验很大程度归功于背后的模型能力，无论是一开始我尝试的 Haiku-4.5, 还是 Sonnet-4.5，都能够圆满的完成我给 Claude Code 下发的编码任务。而后当 Opus-4.5 也开放给 Pro 用户后，我体验下来更是觉得强悍。尽管网上评测号称 gemini-3-pro 和 gpt-5.2 在代码能力上超过 opus-4.5, 但从我实际的感受来看并非如此，Claude Code + Opus-4.5 的编码能力是最强的。
3. 有关 CLAUDE.md
除了模型能力，Claude Code 的工程能力也是很强的，在这方面 Anthropic 一直领头羊，从 MCP 到 Agent Skills, Anthropic 提出的这些工程实践最终都成为了行业标准。本期周刊我简单聊一下 CLAUDE.md.
CLAUDE.md 是专门的规则文件，用来管理 Claude Code 的记忆。因为大模型是没有状态记忆的，所以 Claude Code 在启动时会读取这些文件从而加载到上下文中给到大模型。可以理解为是写给 Claude 看的 README.md 文件，给 Claude 提供上下文信息和操作指南。一般的 Code Agent 都提供了类似的机制，在 Gemini Cli 中该文件叫 GEMINI.md, 而 Codex、Cursor 等其他 Code Agent 则叫 AGENTS.md. AGENTS.md 也已经成为 AAIF (Agentic AI Foundation) 的一个标准项目。
CLAUDE.md 示例如下：
# 前端项目
## bash命令
- `npm run build`：构建项目
- `npm run typecheck`：运行类型检查
## 代码风格
- 使用ES模块语法（`import/export`），而非CommonJS（`require`）
- 尽可能使用解构导入（例如：`import { foo } from 'bar'`）
## 工作流程
- 完成一系列代码修改后，务必进行类型检查
- 出于性能考虑，优先运行单个测试，而非整个测试套件
CLAUDE.md 有几种方式，最常见的是放在项目的根目录下，还可以存放在系统目录或用户目录下，其作用范围也不同。Claude 官网做了如下解释(以下表格中位置当前目录为项目文件夹)：
| 系统目录下 | |||
CLAUDE.md 的写作原则是精简而清晰，过多的指令只会让大模型的效率变得低下，这也是为什么 Agent Skills 设计三层抽象的原因（后续再谈）。在 Writing a good CLAUDE.md 这篇博文里，作者建议 CLAUDE.md 不要超过60行。
另外，该文作者还提到，不要使用 /init 命令来自动生成 CLAUDE.md, 这点建议恰巧同官方博客文章相悖，在 Using CLAUDE.md files: Customizing Claude Code for your codebase 里 Anthropic 建议使用 /init 来自动生成 CLAUDE.md, 这也是我当前经常采用的方式。无论哪种建议，还是得根据实际情况来决定是否采纳。
值得一提的是，Claude 有时会忽略 CLAUDE.md 文件，这是因为有时候 Claude Code 会在提示词中针对 CLAUDE.md 追加一句系统提示：该上下文与任务可能有关也可能无关，除非与任务高度相关才响应该上下文。
<system-reminder>
IMPORTANT: this context may or may not be relevant to your tasks.
You should not respond to this context unless it is highly relevant to your task.
</system-reminder>
所以 Claude 如果判断该上下文与当前任务无关的话则会忽略它。
4. 下一步计划
下一步打算试验下 Claude Code 的 SubAgent、Skills 等能力，另外正在用 Claude Code 编写一个类 Claude Code 的 Agent.