claude-foundation

claude-foundation 快速入门

一句话卖点: Claude Code 跑着跑着就偏了？claude-foundation 三把钩子锁死方向——north-star 定目标，re-anchor 拉回来，proof-gate 守质量

这是什么?适合谁?

claude-foundation 是一套可复用的防漂移 Claude Code 基础配置——包含 north-star、re-anchor、proof-gate 三个钩子机制，内置 Skills、知识 Wiki、状态栏。核心理念：Agent 在执行长任务时容易偏离原始目标（drift），claude-foundation 通过三层钩子机制防止这种情况。 三个钩子的分工：north-star 在任务开始时明确目标和成功标准；re-anchor 在任务执行中定期检查是否偏离目标，必要时拉回正轨；proof-gate 在任务完成前验证输出是否满足质量要求。 可作为 Claude Code 插件安装（install.sh 一键安装），也可手动集成到现有项目中。适合需要 Claude Code 执行长任务、多步骤复杂任务的开发者。不适合：简单的一次性问答场景。

准备工作

1. 安装 Claude Code
2. 了解 Claude Code Hooks 机制
3. 准备好需要防漂移的项目
4. （可选）了解 Claude Code 插件系统

3步快速上手

第1步: 安装 claude-foundation

作为 Claude Code 插件安装：

git clone https://github.com/waveriderai/claude-foundation.git
cd claude-foundation
./install.sh

或手动复制配置文件到项目的 .claude/ 目录。

第2步: 配置三个钩子

安装后在项目的 .claude/foundation/ 目录中配置： north-star（目标锚定）：

north-star:
goal: "重构用户认证模块，提高安全性"
success-criteria:
- 所有测试通过
- 无新增安全漏洞
- 代码覆盖率 ≥ 80%

re-anchor（中途校正）：

re-anchor:
check-interval: 5  # 每 5 步检查一次
drift-threshold: 0.3  # 偏离度阈值
corrective-action: "回顾 north-star 目标，调整方向"

proof-gate（质量门禁）：

proof-gate:
checks:
- type: test
command: "npm test"
- type: lint
command: "npm run lint"
- type: security
command: "npm audit"

第3步: 启动 Claude Code 并观察防漂移效果

正常使用 Claude Code 执行任务。claude-foundation 会在后台自动运行三个钩子：

• 任务开始时，north-star 注入目标和成功标准
• 每 5 步，re-anchor 检查偏离度
• 任务完成前，proof-gate 运行质量检查 状态栏会显示当前的防漂移状态：🟢 正常 / 🟡 轻微偏离 / 🔴 严重偏离。

常见踩坑

1. north-star 目标定义过于模糊——“提高代码质量”不如”将测试覆盖率从 60% 提升到 80%“有效
2. re-anchor 检查间隔设置不当——太频繁影响效率，太稀疏可能错过偏离时机
3. proof-gate 检查过多导致任务无法完成——选择 2-3 个关键检查即可
4. 与项目现有的 Hooks 可能冲突——检查是否有重复或矛盾的 Hook 定义
5. 首次使用建议在非关键任务上测试——熟悉防漂移机制后再用于重要任务

初级用法

1. 长任务防漂移：为超过 10 步的复杂任务启用防漂移
2. 重构安全网：重构代码时用 proof-gate 确保不引入回归
3. 新手引导：为 Claude Code 新手预设防漂移配置，减少误操作
4. 代码审查辅助：用 north-star 明确审查目标，re-anchor 保持审查方向
5. 文档生成：确保生成的文档覆盖所有 north-star 中定义的关键点

高级玩法

1. 自定义钩子逻辑：修改三个钩子的检查逻辑，适配项目特定需求
2. 多阶段 north-star：为复杂任务的不同阶段定义不同的 north-star
3. 漂移分析报告：收集 re-anchor 的偏离数据，分析 Agent 容易偏离的场景
4. 知识 Wiki 集成：将项目知识库集成到 north-star 中，提高目标精准度
5. 团队配置共享：将 claude-foundation 配置纳入团队模板，统一 Agent 行为标准

小技巧

1. north-star 用具体的、可验证的标准——“通过所有测试”比”代码没问题”好
2. re-anchor 的偏离阈值从 0.5 开始，根据实际效果调整
3. proof-gate 优先运行最快的检查——lint 比 test 快，先跑 lint
4. 状态栏颜色变化时主动查看偏离原因，不要等到任务结束
5. 将 claude-foundation 配置纳入 Git，团队共享防漂移经验

常见问题 FAQ

Q1: claude-foundation 和 Claude Code 内置的 Hooks 有什么区别？ Claude Code 内置 Hooks 是通用的事件钩子。claude-foundation 是专门针对”防漂移”场景设计的三层钩子体系，提供了开箱即用的防漂移策略。信息来源：GitHub README。

Q2: 防漂移会影响 Claude Code 的性能吗？ 三个钩子在关键节点运行（任务开始、每 N 步、任务结束），对整体性能影响很小。re-anchor 的检查间隔可以调整以平衡性能和防漂移效果。信息来源：GitHub README。

Q3: 可以只使用部分钩子吗？ 可以。三个钩子独立工作，你可以只启用 north-star + proof-gate，或只用 re-anchor。根据任务需求灵活组合。信息来源：GitHub README。

Q4: 适合所有类型的 Claude Code 任务吗？ 最适合多步骤、长时间运行的复杂任务。对于简单的单轮问答，防漂移机制可能过度设计。信息来源：综合评估。

Q5: 和其他 Claude Code 插件兼容吗？ claude-foundation 设计为独立插件，使用标准的 Claude Code Hooks 接口，通常与其他插件兼容。但如果有多个插件修改相同的 Hook 点，可能需要手动协调。信息来源：GitHub README。

产品特性与使用场景

claude-foundation 的核心价值在于解决 Claude Code 长任务中的「目标漂移」问题——Agent 在执行多步骤任务时逐渐偏离原始目标，产出与预期不符。三层钩子机制提供了完整的防漂移闭环：

• north-star（目标锚定）：每次新会话或 resume 时自动注入 north-star.md，明确目标定义和成功标准。支持多阶段目标拆分，每个阶段可配置独立的验收条件。
• re-anchor（中途校正）：每 10 个 prompt（可调）强制执行 checkpoint，检查当前执行方向与 north-star 目标的偏离度。偏离超过阈值时，自动注入校正提示拉回正轨。
• proof-gate（质量门禁）：拦截 git push / gh pr merge / npm publish 等破坏性操作，要求本会话已跑过测试才能放行（同命令再跑一次可绕过，保留有意识 override 空间）。

除三钩子外，还内置 7 个 Skill（new-project / validate-idea / ingest-source / learn-from-thinkers / optimize-prompt / design-taste / deep-research）和 deep-research 工作流（Scope→Search→Fetch→verify→synthesize）。状态栏实时显示防漂移状态（🟢 正常 / 🟡 轻微偏离 / 🔴 严重偏离），让开发者无需主动检查即可感知 Agent 执行健康度。

典型使用场景包括：重构大型代码库时确保不引入回归、迁移数据库 Schema 时保持目标一致性、给已有项目批量生成文档时防止内容跑偏。对于需要 Claude Code 执行数小时长任务的开发者，claude-foundation 提供了「方向锁 + 质量门 + 状态感知」三重保障。

三钩子机制在真实项目中的应用案例

claude-foundation 的三层防漂移钩子在不同类型的项目中展现出不同的使用模式。以下通过三个典型案例说明三钩子如何在实际开发中协同工作，帮助开发者理解何时调整钩子参数以及如何根据项目特点定制配置。

案例 1：大型单体应用重构

场景：一个包含 12 万行代码的 Python Django 项目需要从 Django 2.x 升级到 4.x，同时清理遗留的技术债务。整个任务预计持续 2-3 周，涉及数百个文件的修改，Claude Code 需要分多个会话逐步完成。

north-star 的作用：在任务开始时，开发者编写 north-star.md 明确定义目标——“将 Django 从 2.x 升级到 4.x，保持所有现有功能正常，测试覆盖率不低于 75%“。每次 Claude Code 新建会话时，load-north-star 钩子自动注入这个目标，防止 Agent 在处理某个中间件兼容性问题时跑偏去重构无关的代码。在一个实际会话中，Claude 在修复 URL 路由废弃警告时开始”顺便”重构 admin 模块的模板系统——re-anchor 在第 10 个 prompt 时触发，检测到当前工作（重构 admin 模板）与 north-star 目标（Django 升级）偏离，自动注入校正提示，Agent 随即回到升级任务正轨。

re-anchor 的作用：Django 升级涉及大量中间件、ORM 查询语法、模板标签的变更。Claude Code 在连续处理多个文件后容易陷入”局部优化”——在某个文件的 URL pattern 迁移上反复修改却不推进其他文件。re-anchor 每 10 个 prompt 强制要求 Agent 用一句话重述当前目标和确认进展，这迫使 Agent 定期”抬头看路”而非沉溺于单个文件的细节。开发者反馈，将 REANCHOR_EVERY 从默认的 10 调整到 7（Django 升级中文件间依赖复杂，更频繁的检查更有效），显著减少了跑偏频率。

proof-gate 的作用：重构过程中开发者需要多次 git push 到升级分支。proof-gate 拦截 git push，要求本会话已运行过 python manage.py test。如果开发者跳过了测试直接 push，proof-gate 会提示”本会话未运行测试，请先执行测试”。这有效防止了”Django 升级改了一堆文件但测试从没跑过”的情况。proof-gate 的 conscious override 机制（同命令再跑一次即放行）在紧急情况下保留了灵活性。

案例 2：多模块微服务 API 开发

场景：一个 SaaS 平台需要新增支付模块，涉及 4 个微服务（订单服务、支付服务、通知服务、日志服务）的改动，每个服务独立仓库，需要在 5 天内完成开发和联调。

north-star 在此场景中的价值在于多阶段目标拆分。开发者在 north-star.md 中定义三个阶段目标：第 1-2 天完成订单服务和支付服务的核心 API、第 3 天完成通知服务对接、第 4-5 天联调和端到端测试。每次开始新阶段时手动更新 north-star.md，load-north-star 自动注入当前阶段的目标。这比单一模糊的”开发支付模块”目标有效得多——Claude Code 在处理通知服务时不会跑回去改订单服务的代码。

re-anchor 在微服务场景下的作用尤为突出。跨服务开发时，Claude 容易在处理服务间通信（如 gRPC 调用、消息队列消费）时陷入”解决一个序列化问题然后开始重构整个 protobuf 定义”的链条。re-anchor 的 checkpoint 机制让 Agent 定期确认”当前在处理哪个服务的问题、是否偏离了本阶段目标”。

proof-gate 配置了多服务检查：不仅要求运行当前服务的单元测试，还检查是否运行了跨服务的集成测试。通过在 proof-gate 的 checks 中添加多个 type: test 条目覆盖各服务的测试命令。这比仅检查单服务测试更能防止”局部正确但全局断裂”的问题。

案例 3：文档批量生成与知识库维护

场景：一个开源项目需要为 30 个 API 端点生成完整的 API 文档，同时更新项目的知识库 Wiki。任务以文档生成为主，不涉及代码修改。

north-star 定义文档质量标准而非代码标准：“为 30 个 API 端点生成文档，每个端点包含请求示例、响应示例、错误码说明、参数约束。文档风格与现有文档一致。“load-north-star 确保每次新会话时 Claude 知道文档的具体要求，不会在生成第 15 个端点文档时忘记”参数约束”这一要求。

re-anchor 在文档生成场景中防止”内容漂移”——Claude 在连续生成多个端点文档后可能开始添加不必要的”最佳实践建议”或”架构说明”章节。re-anchor 的定期检查让 Agent 确认当前文档是否仍包含 north-star 要求的四要素（请求示例、响应示例、错误码说明、参数约束），防止文档风格逐渐跑偏。

proof-gate 在纯文档场景中可配置为检查文档完整性而非代码测试：将 checks 改为检查文档文件是否覆盖所有 30 个端点、是否包含必需章节。这展示了 proof-gate 的灵活性——它不限于代码测试，可以适配任何”完成前验证”场景。

与其他 Claude Code 配置方案的对比

Claude Code 生态中存在多种配置和扩展方案，claude-foundation 是其中一种”防漂移专用”的 opinionated 框架。以下对比几种主要方案，帮助开发者根据自身需求选择。

对比 obra/superpowers

obra/superpowers（★246k）是当前 Claude Code 生态中最大规模的 Skill 合集，包含 14+ 个 Skill（brainstorming、writing-plans、executing-plans、subagent-driven-development、test-driven-development、systematic-debugging、requesting-code-review 等）。它是一个”全栈方法论”——从需求梳理到代码实现到质量保障全流程覆盖。

claude-foundation 与 superpowers 的核心差异在于设计哲学：superpowers 通过 Skill 扩展能力边界（让 Agent 学会更多方法论），claude-foundation 通过 Hooks 守护行为底线（防止 Agent 偏离目标）。superpowers 的 Skill 是”你调用才生效”（/brainstorming、/tdd 等手动触发），claude-foundation 的 Hooks 是”安装即自动运行”（load-north-star 每次新会话自动注入、re-anchor 每 10 个 prompt 自动检查、proof-gate 拦截危险操作）。

两者并非互斥：superpowers 提供能力（“怎么做”），claude-foundation 提供约束（“做对的事”）。理论上可以同时安装——superpowers 的 Skill 处理具体方法论，claude-foundation 的 Hooks 守护方向。但实际使用中需要注意 Hook 冲突：如果 superpowers 也有 SessionStart hook，可能与 load-north-star 的注入逻辑冲突，需要手动协调。

superpowers 的跨平台支持显著优于 claude-foundation：支持 Claude Code、Codex、Cursor、Kimi Code、OpenCode、Pi 等 6+ 个平台，每个平台都有独立的 marketplace manifest。claude-foundation 仅支持 Claude Code，且依赖 bash + Python3 环境。

对比 anthropics/skills

anthropics/skills（★158k）是 Anthropic 官方维护的 Skill 仓库，包含 PDF 处理、docx 生成、品牌规范等官方 Skill。它的定位是”官方工具箱”——提供经过 Anthropic 验证的标准能力扩展。

与 claude-foundation 的差异：anthropics/skills 是纯 Skill 集合，不包含任何 Hooks 或防漂移机制。它解决的是”Agent 不会做 X”（如生成 PDF），而非”Agent 做着做着跑偏了”。两者完全互补——可以用 anthropics/skills 扩展能力，用 claude-foundation 守护方向。

anthropics/skills 的权威性是 claude-foundation 无法比拟的：Anthropic 官方维护，文档结构化清晰，与 Claude Code 版本同步更新。claude-foundation 作为个人项目（★1，单一 committer），在可信度和维护持续性上存在天然劣势。

对比 addyosmani/agent-skills

addyosmani/agent-skills（★69k）是社区维护的跨平台 Skill 合集，包含 21 个 Skill（performance-optimization、accessibility、security-hardening 等）。纯 Markdown 定义，零运行时绑定，兼容 Claude Code / Cursor / OpenCode / Windsurf / Codex 全平台。

与 claude-foundation 的核心差异：agent-skills 是”能力扩展”（给 Agent 更多技能），claude-foundation 是”行为约束”（防止 Agent 跑偏）。agent-skills 不包含任何 Hooks 或自动运行机制，所有 Skill 需手动调用。claude-foundation 的三钩子是自动运行的”基础设施”，不需要开发者记得调用。

agent-skills 的跨平台兼容性是最大优势：纯 Markdown 文件，任何支持 SKILL.md 格式的 Agent 都能用。claude-foundation 因绑定 Claude Code Hooks + statusline + settings.json，仅能在 Claude Code 中使用。

对比手动配置 .claude/settings.json

许多 Claude Code 用户选择手动编写 .claude/settings.json + CLAUDE.md 来配置项目行为。这种方式灵活度最高，但需要开发者自己设计防漂移策略。

claude-foundation 的价值在于”开箱即用的防漂移策略”——开发者不需要自己设计 north-star 格式、re-anchor 检查逻辑、proof-gate 拦截规则，安装即获得经过验证的三层防漂移体系。手动配置的优势是可完全定制，但需要开发者对 Claude Code Hooks 机制有深入理解，且需要自行测试 Hook 逻辑的正确性。

对于初学者，claude-foundation 的预设配置比从零开始编写 Hook 更可靠。对于有经验的开发者，手动配置可以更精确地适配项目需求，但可以参考 claude-foundation 的三钩子设计作为起点。

选型建议

根据使用场景选择配置方案：

• 需要”全流程方法论”（从需求到实现到测试）→ obra/superpowers
• 需要”防止长任务跑偏”→ claude-foundation
• 需要”官方验证的标准能力”→ anthropics/skills
• 需要”跨平台纯 Skill 合集”→ addyosmani/agent-skills
• 需要”完全定制”→ 手动配置 .claude/settings.json
• 最佳实践：claude-foundation（方向守护）+ superpowers（方法论）+ anthropics/skills（官方能力）三者组合

各方案关键指标对照

从表中可以看出，claude-foundation 在”自动运行防漂移机制”这一维度上具有独特性——它是唯一一个开箱即用、安装即自动运行三层防漂移钩子的方案。superpowers 虽然也有 SessionStart hook，但其核心是通过 Skill 方法论引导 Agent 行为，而非通过 Hooks 强制约束。anthropics/skills 和 addyosmani/agent-skills 完全不含自动运行机制，需要开发者主动调用。

何时选择 claude-foundation 而非其他方案

以下场景中 claude-foundation 是最佳选择：

1. 团队中有多人使用 Claude Code，需要统一的防漂移行为标准——claude-foundation 的配置可以纳入 Git，团队成员 clone 仓库后 install.sh 即获得一致的防漂移配置。
2. 经常执行跨会话的长任务（如大型重构、迁移）——load-north-star 确保每次新会话都注入目标，防止”上个会话记得目标、下个会话忘了”。
3. 需要在 push/merge 前强制运行测试——proof-gate 拦截机制比人工自觉更可靠。
4. 希望状态栏实时显示防漂移状态——🟢🟡🔴 三色指示让开发者无需主动检查即可感知 Agent 执行健康度。

以下场景中其他方案更合适：

1. 需要跨平台（Cursor / Codex / Windsurf）使用 → superpowers 或 agent-skills
2. 需要 Anthropic 官方验证的能力 → anthropics/skills
3. 需要完全自定义 Hook 逻辑 → 手动配置
4. 简单的一次性任务，不需要防漂移 → 任何方案都行，甚至不需要安装额外配置