Vibe Codeing 实战：用 claude.md 与 subagent 搭建可复现的 TaoToken 配置骨架

1. 为什么 Vibe Coding 需要一个可复现的配置骨架Vibe Coding 的核心是「用自然语言描述需求让 AI 直接产出可运行代码」但真正落到日常开发里你会发现一个尴尬的现实每次新开一个项目Claude Code 的行为都不太一样。有时候它会主动问你技术选型有时候它直接替你拍板有时候它记得项目规范有时候它把上一轮的约定忘得一干二净。这不是模型不稳定而是你缺少一套可复现的配置骨架。我试过在三个不同项目里用同一套提示词结果产出的目录结构、命名风格、甚至依赖版本都各不相同。问题出在Claude Code 的「记忆」和「行为约束」分散在claude.md、settings.json、subagent 定义、hook 脚本这几个地方任何一个缺失整个工作流就会漂移。Vibe Coding 适合谁适合那些想用自然语言驱动开发、但又不想放弃工程可控性的开发者。它不适合完全不懂代码的人因为你需要能读懂 AI 生成的配置和脚本才能判断哪里出了问题。这篇内容要解决的就是把claude.md、subagent、hook 三者的协同关系固定下来给出一套可以直接复制、可以回滚、可以通过 TaoToken 统一 Key 通道接入的配置骨架。你跟着做完会得到一个「新项目 5 分钟内进入可开发状态」的模板。2. TaoToken 前置统一 Key 与 API 通道在配置骨架之前先把 API 通道固定下来。Claude Code 默认走官方通道但如果你同时用多个模型、多个项目Key 管理会变得很乱。TaoToken 的作用是提供一个统一的 API 入口你只需要在settings.json里配置一次后续所有 subagent、hook 触发的模型调用都走同一个通道。你需要先拿到 API Key。访问https://taotoken.net/api-keys带 utm 参数?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys创建一个 Key复制出来。注意这个 Key 只显示一次建议直接存到环境变量里不要硬编码进settings.json。TaoToken 的 API 地址是https://taotoken.net/api这个地址不加 UTM 参数直接作为 base URL 使用。它的接口格式与主流模型通道兼容所以 Claude Code 的配置里只需要改base_url和api_key两个字段。注意不要把 Key 提交到 git。后面我会在 hook 里加一个检查防止敏感信息泄漏。如果你还没决定用哪个模型可以先到模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels试一下不同模型的响应风格再决定claude.md里默认调用哪个。3. 可复制配置settings.json 与 claude.md 骨架3.1 settings.json 的完整骨架Claude Code 的配置文件通常放在项目根目录的.claude/settings.json或者用户级的~/.claude/settings.json。我建议项目级配置这样每个项目的通道和权限可以独立控制。{ api: { base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514, max_tokens: 8192, temperature: 0.3 }, permissions: { allow_file_write: true, allow_shell: true, allowed_commands: [git, npm, pnpm, python, pytest], deny_patterns: [*.env, *.pem, id_rsa*] }, hooks: { pre_commit: .claude/hooks/pre-commit.sh, post_tool_use: .claude/hooks/post-tool-use.sh }, subagents: { quality-engineer: .claude/agents/quality-engineer.md, tester: .claude/agents/tester.md, git-commit-agent: .claude/agents/git-commit-agent.md } }这里有几个关键点。api_key用${TAOTOKEN_API_KEY}引用环境变量避免明文。temperature设成 0.3是因为 Vibe Coding 需要一定的创造性但配置类任务需要稳定输出0.3 是一个平衡点。deny_patterns里把.env、.pem、id_rsa都列进去配合后面的 hook 做双重防护。环境变量这样设置export TAOTOKEN_API_KEY你的KeyWindows 用户可以用setx TAOTOKEN_API_KEY 你的Key然后重启终端。3.2 claude.md 的骨架结构claude.md是项目的「宪法」它决定了 Claude Code 在这个项目里的行为边界。我把它分成五个区块每个区块都有明确职责。# 项目宪法哈基咪记账 ## 1. 项目概述 - 名称哈基咪记账 - 目标平台Windows / macOS - 核心功能记录花销人民币支持二级分类 - 技术栈待决策见第 3 节 ## 2. 决策规则 - 任何技术选型必须向用户询问不得自行决定 - 任何依赖新增必须说明理由和替代方案 - 任何目录结构调整必须先在对话中确认 - 用户说「你决定」时才可自主决策但需列出决策依据 ## 3. 技术栈候选 | 方案 | 优势 | 劣势 | |------|------|------| | Electron React | 跨平台成熟生态丰富 | 包体积大内存占用高 | | Tauri Vue | 包体积小性能好 | Rust 学习曲线陡 | | Flutter Desktop | 一套代码多端 | 桌面端生态相对弱 | ## 4. 代码规范 - 每个函数必须有注释注释行数不少于代码行数的 30% - 注释必须与代码逻辑匹配禁止「复制粘贴式注释」 - 敏感信息禁止硬编码统一走环境变量 - 提交前必须通过单元测试和安全审计 ## 5. 工作流约定 - 每次会话开始先读本文件 - 上下文过长时使用 /compact 压缩 - 重要决策记录到 /memory - 回退使用双击 Esc 选择版本这个骨架的关键在于第 2 节「决策规则」。Vibe Coding 最容易失控的地方就是 AI 替你做了太多决定。把「必须询问」写成硬规则后面 subagent 和 hook 才有判断依据。3.3 subagent 定义quality-engineersubagent 是 Claude Code 里的「员工」每个员工有明确的职责和技能。在.claude/agents/quality-engineer.md里这样写# Subagent: quality-engineer ## 角色 质量工程师负责代码质量检查。 ## 技能 1. security-audit安全审计 - 检查密码、Token 等敏感信息泄漏 - 检查 SQL 注入、命令注入风险 - 检查配置文件中的明文敏感信息 - 检查其他安全隐患 2. comments-check注释检查 - 检查函数和核心代码是否有注释 - 检查注释与代码是否匹配 - 检查注释是否符合企业级规范 ## 输出要求 - 检查完成后生成 .claude/markers/quality-passed 标记文件 - 如果发现问题生成 .claude/markers/quality-failed 并列出问题清单 - 标记文件内容包含时间戳和检查项摘要对应的技能文件放在.claude/skills/security-audit.md和.claude/skills/comments-check.md内容就是具体的检查规则。你可以直接对 Claude Code 说「帮我创建一个 security-audit 技能检查以下内容……」它会自动生成技能文件。3.4 hook 配置git commit 拦截hook 是 Vibe Coding 工作流里的「门禁」。在.claude/hooks/pre-commit.sh里写#!/bin/bash set -e MARKER_DIR.claude/markers QUALITY_MARKER$MARKER_DIR/quality-passed TEST_MARKER$MARKER_DIR/test-passed # 检查标记文件是否存在 if [ ! -f $QUALITY_MARKER ]; then echo 质量检查未通过禁止提交 exit 1 fi if [ ! -f $TEST_MARKER ]; then echo 单元测试未通过禁止提交 exit 1 fi # 检查标记文件是否过期超过 30 分钟 QUALITY_AGE$(($(date %s) - $(stat -c %Y $QUALITY_MARKER 2/dev/null || stat -f %m $QUALITY_MARKER))) if [ $QUALITY_AGE -gt 1800 ]; then echo 质量检查标记已过期请重新运行 quality-engineer exit 1 fi echo 检查通过允许提交 exit 0这个脚本的逻辑是只有quality-engineer和tester都生成了通过标记且标记在 30 分钟内有效才允许 git commit。标记过期机制是为了防止「一次检查多次提交」的偷懒行为。3.5 git-commit-agent 的定义在.claude/agents/git-commit-agent.md里# Subagent: git-commit-agent ## 角色 提交代理负责协调测试、质量检查和 git 提交。 ## 工作流 1. 调用 tester subagent运行单元测试 2. 调用 quality-engineer subagent运行安全审计和注释检查 3. 检查 .claude/markers/ 下的标记文件 4. 如果全部通过调用 git-save 技能执行提交 5. 如果任一失败输出失败原因不提交 ## 约束 - 不得跳过任何检查步骤 - 不得手动创建标记文件 - 提交信息必须符合 conventional commits 规范4. 验证请求与成功结果配置写完后需要验证整条链路是否打通。按这个顺序操作第一步确认 API 通道可用。在终端里执行curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:ping}]}如果返回 JSON 里有choices字段说明通道正常。如果返回 401检查 Key 是否正确如果返回 404检查 base_url 是否写成了https://taotoken.net/api而不是带/v1的地址。第二步启动 Claude Code输入/memory查看记忆是否加载了claude.md。你应该能看到项目概述和决策规则被读取。第三步手动触发一次 quality-engineer/agent quality-engineer观察它是否生成了.claude/markers/quality-passed。如果没有生成检查 subagent 文件路径是否和settings.json里的配置一致。第四步测试 hook 拦截。先删除标记文件rm -f .claude/markers/quality-passed然后执行git commit -m test应该被拒绝并提示「质量检查未通过」。再运行一次 quality-engineer生成标记后再次提交应该成功。第五步测试回滚。双击 Esc选择之前的版本确认可以回退到配置修改前的状态。这一步验证的是「可回滚」能力。5. 本篇常见错排查报错一settings.json解析失败提示Unexpected token这是最常见的。JSON 不允许注释也不允许尾随逗号。检查你的settings.json里有没有//开头的行或者最后一个字段后面多了逗号。建议用jq . .claude/settings.json验证格式。报错二subagent 调用后没有生成标记文件先确认.claude/markers/目录存在。如果不存在手动创建mkdir -p .claude/markers然后检查 subagent 定义里的输出路径是否和 hook 脚本里的路径一致。我踩过的坑是 subagent 写的是markers/quality-passed而 hook 读的是.claude/markers/quality-passed路径差一层就找不到。报错三hook 脚本没有执行权限chmod x .claude/hooks/pre-commit.shWindows 用户如果用 Git Bash同样需要这个权限。如果用 PowerShell需要检查执行策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned报错四API 返回 429 限流TaoToken 的通道有速率限制。如果你在短时间内频繁调用 subagent可能会触发限流。解决方案是在settings.json里加一个重试配置{ api: { retry: { max_attempts: 3, backoff_ms: 1000 } } }报错五claude.md没有被读取Claude Code 默认读取项目根目录的claude.md。如果你的文件放在.claude/claude.md需要在settings.json里显式指定路径{ context: { project_file: .claude/claude.md } }报错六git commit 被拦截但标记文件存在检查标记文件的时间戳。如果超过 30 分钟hook 会认为过期。这是故意设计的防止你用旧的检查结果提交新代码。重新运行 quality-engineer 即可。6. 把配置骨架用起来下一步动作这套骨架的价值在于「可复现」。你可以把.claude/目录整个复制到新项目里改一下claude.md的项目概述和技术栈候选5 分钟内就能进入可开发状态。subagent 和 hook 不需要每次重写它们是通用的质量门禁。如果你在接入过程中遇到 API 通道问题优先检查 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys里的 Key 状态以及接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc里的 base_url 说明。如果你还在选模型模型对话页面可以快速对比不同模型在配置类任务上的表现。长期做 Vibe Coding 的话建议把 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan配好这样 subagent 和 hook 触发的调用会走统一的额度池不会因为单个 Key 限流导致整个工作流卡住。最后说一个实用技巧把.claude/markers/加到.gitignore里。标记文件是本地状态不应该提交到仓库。这样每个开发者在自己机器上跑检查互不干扰。