Claude Code 规则守护
🧠 Claude Code 规则守护
claudemd-guard 完整配置 · 强制规则守护
🛡️ claudemd-guard (规则守门员)
🛡️ claudemd-guard —— 规则强制守门员
claudemd-guard 是专为解决长对话中 CLAUDE.md 规则被遗忘问题而设计的 PreToolUse 钩子工具。
✅ 核心优势
- AI驱动验证：使用本地Claude CLI校验，无需额外API Key
- 自动规则收集：向上/向下遍历目录自动查找CLAUDE.md
- fail-open设计：验证出错时不阻塞开发
- 冷却机制：支持设置验证间隔，避免频繁调用
- 开源免费：MIT协议，一条命令完成安装
⚠️ 注意事项
- 需Node.js ≥ 22.0.0
- 验证需要几秒延迟（冷启动时）
- 过于严格的规则可能导致误拦截
- 依赖本地Claude CLI（确保已安装）
⚙️ 2. 完整配置流程（逐步骤 + 验证）
前置条件：Node.js ≥ 22.0.0，已安装 Claude Code（npm install -g @anthropic-ai/claude-code）。
🛡️ 2.1 安装 claudemd-guard（规则强制守护）
# 全局安装 npm install -g claudemd-guard # 安装钩子到 Claude Code（自动修改 ~/.claude/settings.json） claudemd-guard install
可选配置（环境变量）：
# 设置冷却时间（秒），避免频繁验证 export CLAUDEMD_GUARD_COOLDOWN=10 # 指定验证模型 export CLAUDEMD_GUARD_MODEL=claude-sonnet-4-20260514 # 临时禁用守护 export CLAUDEMD_GUARD_DISABLED=false
✔️ 验证配置成功：
- 在项目根目录创建
CLAUDE.md，写入规则如“禁止删除src目录” - 在Claude Code中尝试让AI删除文件，应被拦截并显示“🚫 根据CLAUDE.md文件中的规则，删除src目录被明确禁止”
- 终端执行
claudemd-guard status查看钩子激活状态
模型配置方式
方式一：环境变量（推荐）
# Linux/macOS
export CLAUDEMD_GUARD_MODEL="claude-sonnet-4-6"
export CLAUDEMD_GUARD_COOLDOWN=5 # 可选：冷却时间(秒)
# Windows PowerShell
$env:CLAUDEMD_GUARD_MODEL="claude-sonnet-4-6"
$env:CLAUDEMD_GUARD_COOLDOWN=5
方式二：持久化配置
创建配置文件 ~/.claudemd-guard/config.json：
{
"CLAUDEMD_GUARD_MODEL": "claude-sonnet-4-6",
"CLAUDEMD_GUARD_COOLDOWN": 5,
"CLAUDEMD_GUARD_DISABLED": false
}
方式三：项目级配置（.env 文件）
在项目根目录创建 .env：
CLAUDEMD_GUARD_MODEL=claude-sonnet-4-6
CLAUDEMD_GUARD_COOLDOWN=5
验证配置是否生效
# 方法1：检查环境变量
echo $CLAUDEMD_GUARD_MODEL
# 方法2：查看 claudemd-guard 状态
claudemd-guard status
# 方法3：启动 Claude Code 后观察
# 触发一次规则校验，看是否有错误
claudemd-guard 安装后，会自动在 ~/.claude/settings.json 中注入以下钩子配置
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write|Bash",
"hooks": [
{
"type": "command",
"command": "node C:\\Users\\xxx\\claudemd-guard.js"
}
]
}
]
}
}matcher 字段说明
| 工具 | 触发场景 | 典型危险操作示例 |
|---|---|---|
| Edit | 修改现有文件 | 删除代码、修改配置、变更敏感文件 |
| Write | 创建新文件 | 生成未授权的文件、覆盖重要文件 |
| Bash | 执行系统命令 | rm -rf、ALTER TABLE、DROP DATABASE |
这三种工具覆盖了大部分需要规则约束的危险操作，完整工作流程图如下：
┌─────────────────────────────────────────────────────────────────────────┐ │ Claude Code 会话 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 用户: "修改 database.py，删除 users 表" │ │ ↓ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Claude Code: 决策执行 Edit 工具 │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ╔═══════════════════════════════════════════════════════════════════╗ │ │ ║ 🔔 PreToolUse 钩子触发 ║ │ │ ║ │ ║ │ │ ║ ↓ ║ │ │ ║ 📂 claudemd-guard 读取 CLAUDE.md： ║ │ │ ║ · 项目根目录/CLAUDE.md: "禁止删除 users 表" ║ │ │ ║ · backend/CLAUDE.md: "使用 Alembic 迁移" ║ │ │ ║ │ ║ │ │ ║ ↓ ║ │ │ ║ 🤖 AI 校验：操作【删除 users 表】违反规则【禁止删除 users 表】 ║ │ │ ║ │ ║ │ │ ║ ↓ ║ │ │ ║ 🚫 判定：违规 → exit code 2 ║ │ │ ║ │ ║ │ │ ║ ↓ ║ │ │ ║ 📢 输出：🚫 [claudemd-guard] 操作违反 CLAUDE.md！ ║ │ │ ╚═══════════════════════════════════════════════════════════════════╝ │ │ ↓ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ ❌ Edit 工具被阻止执行 │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ ↓ │ │ 用户看到拦截提示，修正操作：使用 Alembic 生成迁移文件 │ │ │ └─────────────────────────────────────────────────────────────────────────┘
总结
| 问题 | 答案 |
|---|---|
| 触发哪个钩子 | PreToolUse |
| 在哪个阶段触发 | Claude Code 准备执行工具时，实际执行之前 |
| 监听哪些工具？ | Edit、Write、Bash |
| 如何读取 CLAUDE.md | 向上遍历到根目录 + 向下遍历整个项目树 |
| 为什么能强制遵守 | PreToolUse 可返回 exit code 2 阻止操作，不依赖上下文窗口 |
| 为什么需要这个 | 长对话中 CLAUDE.md 会被推出上下文窗口，模型再也"看不见"规则 |
核心结论：claudemd-guard 通过 PreToolUse 钩子在操作执行前临时阻断 + 双向目录遍历主动读取 CLAUDE.md，绕过了上下文窗口限制，实现了真正的"强制规则遵守"。
📁 2.3 项目级 CLAUDE.md 配置模板
# 全栈项目规则 ## 项目结构 project-root/
├── backend/
│ ├── app.py
│ ├── routes/
│ ├── models/
│ ├── services/
│ └── tests/
├── frontend/
│ ├── src/
│ │ ├── components/
│ │ ├── views/
│ │ ├── common/
│ │ ├── stores/
│ │ ├── api/
│ │ └── tests/
│ └── public/ ## 项目概览 - **后端**： - 主框架：FastAPI（用于高性能 API） - 辅助框架：Flask（用于轻量级服务或遗留模块） - 语言：Python 3.10+ - 数据验证：Pydantic v2 - 异步支持：async/await 全面启用 - **前端**： - 框架：Vue 3（Composition API） - 语言：TypeScript（严格类型检查） - 构建工具：Vite - 状态管理：Pinia - 路由：Vue Router - UI 库：Element Plus 或 Naive UI（按组件需求选择） - **架构**：前后端分离，RESTful API 通信，JWT 认证 ## 开发偏好 - ✅ 优先使用 TypeScript 编写前端逻辑，禁止 any 类型 - ✅ 后端接口必须包含 Pydantic 模型定义和 OpenAPI 文档 - ✅ 组件命名采用 PascalCase（如 `UserCard.vue`） - ✅ API 路径统一以 `/api/v1/` 为前缀 - ✅ 错误处理需包含统一格式：`{ code: number, message: string, data?: any }` - ❌ 不要自动生成大量注释，除非关键逻辑复杂 - ❌ 避免在 Vue 模板中使用内联复杂表达式 ## 安全与部署 - 前端构建产物（`dist/`）仅包含压缩混淆后的静态资源 - 后端敏感配置通过环境变量注入（`.env` 不提交） - 启用 CORS 但限制来源（开发环境可放宽） ## 特别说明 - 本项目已启用 `claudemd-guard`：任何 AI 生成的代码必须符合上述规范，并经过人工审查后方可合并。 - 若不确定技术选型，请优先参考现有代码风格，而非引入新依赖。 > 请始终以“协作开发者”身份参与，而非“全自动编码器”。
📁 2.4 项目级 OpenSpec + Superpowers CLAUDE.md 配置模板
# AI 开发工作流规范（强制执行，优先级最高）
**本文件定义了所有 Agent 必须遵守的绝对规则，覆盖任何插件或技能的默认行为。**
## 0. 规则文件层级与生效机制
本文件（CLAUDE.md）被 **claudemd-guard** 强制守护，每次工具调用前自动校验。
### claudemd-guard 工作原理
- **触发时机**：每次 Edit、Write、Bash 操作执行前
- **校验内容**：当前操作是否违反本文件中的"禁止操作"
- **拦截效果**：违规操作被实时拦截，并提示正确做法
- **冷却机制**：相同规则连续触发时，冷却期内不再重复校验
### 规则优先级
1. 本文件（CLAUDE.md）中的规则 > 所有其他配置
2. claudemd-guard 拦截权限 > 任何插件或技能的默认行为
3. 禁止操作 > 允许操作
### 规则编写规范
- 使用 `- ❌ 禁止...` 格式定义禁止操作
- 禁止操作必须具体、可验证、不可模糊
- 每条禁止操作建议附带正确做法
## 1. 开发流程铁律
本项目采用 **OpenSpec + Superpowers** 双引擎模式：
- **OpenSpec** 负责定义"做什么"（需求、设计、任务清单）。
- **Superpowers** 负责"怎么做"（拆解计划、TDD、双重审查）。
### 禁止行为（claudemd-guard 强制拦截）
- ❌ 禁止在没有 OpenSpec 提案（proposal.md + tasks.md）的情况下编写任何业务代码。
- ❌ 禁止跳过 `/opsx:verify <变更名>` 就声称任务完成。
- ❌ 禁止使用 OpenSpec 自带的 `apply` 命令（已禁用）。代码实现必须走 Superpowers 流程。
### 强制流程
1. **提案**：`/opsx:propose [变更名或需求描述]` → 生成 proposal.md、specs/、tasks.md。
2. **细化**：`/superpowers:write-plan` → 拆解任务。
3. **执行**：`/superpowers:subagent-driven-development` → 并行开发 + 双重审查。
4. **验证**：`/opsx:verify <变更名>` → 检查实现是否符合规范。
5. **归档**：`/opsx:archive <变更名>` → 将 `changes/<变更名>/specs/` 下的 **Delta Specs** 合并到 `openspec/specs/` 主规范库，然后完整变更目录移至 `changes/archive/`。
> 提示：对于复杂需求，可先执行 `/opsx:explore` 探索澄清，再执行 `/opsx:propose [变更名或需求描述]`。
## 2. 角色分工
- **产品经理**：负责 `/opsx:propose [变更名或需求描述]` 中的 proposal.md 和 specs/。
- **架构师**：负责 design.md。
- **前后端开发**：负责实现，必须遵循 TDD（先写测试）。
- **QA**：编写测试并执行 `/opsx:verify <变更名>`。
- **文档工程师**：根据归档更新文档。
## 3. 技术栈
| 层级 | 技术 | 版本要求 |
|------|------|----------|
| 后端框架 | Python + Flask | Python ≥ 3.10 |
| 数据库 | Sqlite3 + PyMySQL | - |
| 前端框架 | Vue 3 | Composition API |
| 前端语言 | TypeScript | strict: true |
| 构建工具 | Vite | - |
| HTTP客户端 | Axios | - |
| 后端测试 | Pytest | 覆盖率 ≥ 80% |
| 前端测试 | Jest | 覆盖率 ≥ 70% |
### 禁止行为（claudemd-guard 强制拦截）
- ❌ 禁止在 Python 代码中使用 `print()` 替代 logger
- ❌ 禁止在 Vue 组件中直接操作 DOM（使用 ref 代替）
- ❌ 禁止在 TypeScript 中使用 `any` 类型
- ❌ 禁止在 Flask 中写异步函数
- ❌ 禁止在前端硬编码 API 地址（使用环境变量）
- ❌ 禁止提交包含 `console.log` 或 `debugger` 的代码
- ❌ 禁止使用 Options API（统一使用 Composition API + `<script setup>`）
## 4. 目录结构
├── backend/
│ ├── app.py
│ ├── routes/
│ ├── models/
│ ├── services/
│ └── tests/
├── frontend/
│ ├── src/
│ │ ├── components/
│ │ ├── views/
│ │ ├── common/
│ │ ├── stores/
│ │ ├── api/
│ │ └── tests/
│ └── public/
├── openspec/
│ ├── specs/
│ └── changes/
├── .claude/
├── skills/
└── scripts/
### 禁止行为（claudemd-guard 强制拦截）
- ❌ 禁止将业务代码放在项目根目录
- ❌ 禁止前端组件文件使用 `.js` 后缀（必须使用 `.vue` 或 `.ts`）
- ❌ 禁止测试文件与源文件混放
## 5. 完成定义（Definition of Done）
一个任务被认为"完成"必须满足：
- [ ] 所有相关代码已实现并通过测试。
- [ ] 所有禁止操作均未被触发（claudemd-guard 零拦截记录）
- [ ] `/opsx:verify <变更名>` 返回无错误。
- [ ] 已执行 `/opsx:archive <变更名>`（对于整个变更）。
- [ ] 文档已更新（至少 README 和 API 文档）
- [ ] 代码已通过 lint 检查（ruff + ESLint）
- [ ] TypeScript 类型检查无报错
### 禁止行为（claudemd-guard 强制拦截）
- ❌ 禁止在测试未通过时声称任务完成
- ❌ 禁止在文档未更新时执行归档
- ❌ 禁止在 claudemd-guard 有拦截记录时跳过修复
## 6. 违规处理
如果任何 Agent 违反上述规范（例如直接写代码而没有 tasks.md），用户会要求重新按规范执行。Agent 必须立即纠正，不得辩解。
### claudemd-guard 拦截后的正确流程
1. 阅读拦截提示中的违规规则
2. 根据提示中的建议做法修改操作
3. 重新执行符合规范的操作
4. 确认无拦截后继续
### 多次违规的后果
- 第1次：收到警告提示
- 第2次：操作被拦截，需手动确认
- 第3次及以上：操作被强制拒绝，必须重新规划
🔧 3. 高级功能与维护调优
🛡️ claudemd-guard 高级配置
# 设置更严格的验证（每次操作都验证） export CLAUDEMD_GUARD_COOLDOWN=0 # 使用 Anthropic API 直接调用（可选） export CLAUDEMD_GUARD_API_KEY=sk-ant-xxx export CLAUDEMD_GUARD_MODEL=claude-opus-4-20260514 # 强制使用系统 Claude CLI export USE_SYSTEM_CLAUDE=true
🔍 一次性自检清单
- 故意违反 CLAUDE.md 规则被 claudemd-guard 拦截并提示
- 长对话（30轮+）后 CLAUDE.md 规则依然生效
- 使用自然语言查询项目历史能返回准确结果
浙公网安备 33010602011771号