CLAUDE.md：Agent 的行为准则 在代码库里高效使用 Claude Code，最重要的文件就是根目录下的 CLAUDE.md。它是 Agent 的行为准则，是了解仓库运作方式的首要依据。
核心哲学 随着时间推移，我形成了一套鲜明且有主见的写作哲学来打造高效的 CLAUDE.md：
原则 说明 先设限制，而非写指南 从小处着手，根据 Claude 常犯的错误逐步记录 别到处 @ 引用文档 提到路径即可，而非将整份文件塞进上下文窗口 不要只说”禁止” 提供可行替代方案，避免 Agent 左右脑互博 把 CLAUDE.md 当成强制性手段 用 bash 包装器替代长篇解释，迫使代码精简
最佳实践示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 # CLAUDE.md 开发准则 ## 概览 **上下文信息要求** - 在编码前至少分析 3 个现有实现或模式- 绘制依赖与集成点- 弄清测试框架和编码规范- **优先使用 context7 查询编程库文档** - **使用 github.search_code 搜索开源实现示例** - **使用 desktop-commander 进行本地文件分析**
核心要点
把 CLAUDE.md 当作一套高层次、精心策划的护栏和指引 ，而非无所不包的百科全书。
上下文管理：压缩与清理 建议在编码会话中至少运行一次 /context，了解有限 token 的上下文窗口使用情况。以 Sonnet-1M 为例，基线成本约 20k token（10%），剩下 180k 用于实际修改。
三种工作流程对比 方式 适用场景 推荐度 /compact 自动压缩上下文 ⭐ 不推荐 /clear + 重启对话 简单重启场景 ✅ 默认选择 记录并清除 大型复杂任务 ✅ 复杂任务
1. /compact（避免使用） 自动压缩过程不透明、容易出错，压缩完毕后幻觉更加严重。
2. /clear + 重启对话（默认方式） 清除状态后进行对话，让 Claude 读取当前 git 分支中所有已更改的文件。
3. “记录并清除”（复杂重启） 用于大型任务：
让 Claude 把计划和进展输出到 .md 文件 用 /clear 清除上下文 读取那个 .md 文件开始新会话继续工作 核心要点
不要相信自动压缩。对简单重启使用 /clear，对复杂任务使用”记录并清除”方法创建持久的外部”记忆”。
自定义斜杠命令 我把斜杠命令看作是常用提示的简单快捷方式，仅此而已。
我的精简配置 1 /catchup : 读取当前 git 分支中所有已更改的文件
反模式警示 恕我直言，如果你有一长串复杂的自定义斜杠命令，你就制造了一个反模式。
像 Claude 这样的 Agent 全部意义在于：输入几乎任何 想要的东西，得到有用的、可合并的结果。一旦强迫用户学习需要查文档的魔法命令列表，你就失败了。
核心要点
把斜杠命令当作简单、个人化 的快捷方式，而不是用它来替代构建更直观的 CLAUDE.md。
恢复、继续与历史记录 基础用法 1 2 claude --resume continue
对于重启出问题的终端或快速恢复旧会话非常好用。经常 claude --resume 几天前的会话，只为问 Agent 它是如何克服某个特定错误的。
进阶用法：元分析 Claude Code 将所有会话历史存储在 ~/.claude/projects/ 中。可以编写脚本对这些日志进行元分析，寻找常见异常、权限请求和错误模式。
核心要点
使用 claude --resume 和 claude --continue 来重启会话和挖掘历史上下文。无效会话可以清除。
Plan 模式 对于任何使用 AI IDE 进行的”大型”功能变更，规划都是必不可少的 。
实践价值 1 2 3 4 Plan 模式 = 与 Agent 对齐的方式= 定义"如何" 构建= 定义检查点= 培养提供最少上下文的直觉
工作流程 1 需求理解 → Plan 模式生成文档 → 风暴讨论 → 模型协助澄清 → 审核确认 → 基于计划开发
这很考验对任务的理解和思考，以及提示词能力（表结构、实施方案等）。
核心要点
对于复杂的变更，总是 使用内置的 Plan 模式，在 Agent 开始工作前就计划达成一致。
技能 (Skills) Skills（也许）比 MCP 更重要，但Specs会把需求拆成”专业废纸”，实现全是屎。
心智模型演变 1 2 3 4 5 6 7 8 9 10 11 12 ┌─────────────────────────────────────────────────────────┐ │ 阶段 1 : 单次提示 (Single Prompt) │ │ 在巨大提示中给所有上下文（脆弱，无法扩展） │ ├─────────────────────────────────────────────────────────┤ │ 阶段 2 : 工具调用 (Tool Calling) │ │ 手动制作工具，为 Agent 抽象现实 │ │ （更好，但创造了新的抽象和上下文瓶颈） │ ├─────────────────────────────────────────────────────────┤ │ 阶段 3 : 脚本化 (Scripting) ★ │
为什么 Skills 是正确的抽象 Agent Skills 将”脚本化”这一层正式产品化。如果你倾向于使用 CLI 而非 MCP ，其实一直在不自觉地享受 Skills 好处。
SKILL.md 文件只是更有组织、可共享、可发现的方式来记录 CLI 和脚本，并将它们暴露给智能体。
核心要点
Skills 是正确的抽象。它们将基于”脚本化”的智能体模型正式化，这种模型比 MCP 所代表的僵硬 API 模型更健壮、更灵活。
模型上下文协议 (MCP) Skills ≠ MCP 已死 以前，许多人构建了糟糕的、上下文沉重的 MCP，包含几十个只是简单镜像 REST API 的工具。
新角色定位 MCP 应该是数据网关 ，提供几个强大的高层次工具：
1 2 3 4 download_raw_data (filters…) take_sensitive_gated_action (args…) execute_code_in_environment_with_state (code…)
在这个模型中，MCP 的工作是管理认证、网络和安全边界，然后让开。它为智能体提供入口点 ，然后智能体利用脚本能力完成实际工作。
我使用的 MCP MCP 用途 推荐度 Context7 文档搜索工具，提供最新库文档和代码示例 ⭐⭐⭐⭐⭐ server-sequential-thinking 规范式思考体系 ⭐⭐⭐⭐ server-memory 知识图谱记忆系统 ⭐⭐⭐ deepwiki 个人文档总结 ⭐⭐⭐
核心要点
使用扮演数据网关 角色的 MCP。给智能体一两个高层次工具，然后让它基于这些工具编写脚本。
给所有大模型加上联网功能，套到极致，就是艺术。
附录：CLAUDE.md 完整模板参考 1 2 3 4 5 6 7 8 9 10 11 12 13 14 # CLAUDE.md 开发准则 ## 概览 ## 🔒 强制验证机制 - 必须拒绝一切 CI、远程流水线或人工外包验证- 每次改动必须提供可重复的本地验证步骤- 验证过程中如遇工具缺失或测试覆盖不足，必须在任务文档中记录## 📋 文件结构规范
.claude/
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 ## 🔄 标准工作流 6 步骤 1. 分析需求2. 获取上下文3. 选择工具4. 执行任务5. 验证质量6. 存储知识## 💡 开发哲学 - 必须坚持渐进式迭代，保持每次改动可编译、可验证- 必须在实现前研读既有代码或文档- 必须保持务实态度，优先满足真实需求- 必须选择表达清晰的实现，拒绝炫技式写法- 必须偏向简单方案，避免过度架构
最后提醒
将 CLAUDE.md 与 AGENTS.md 文件保持同步，以确保与其他 AI IDE 兼容。
安全章节 在使用 Claude Code 的过程中，安全风险往往是容易被忽视的一环。以下是基于实践总结的安全红线与防护策略。
MCP 安全红线 风险类型 风险描述 防护策略 敏感操作 数据库删除、文件系统修改、API 密钥泄露 必须二次确认、设置操作白名单 网络访问 任意 HTTP 请求、内网渗透风险 限制可访问域名、记录所有请求 文件系统 完整目录读写权限、配置文件泄露 设置 .claudeignore 排除敏感文件 会话劫持 长期会话未清理、权限继承风险 定期清理无用会话、最小权限原则
真实案例：危险配置 vs 安全配置 1 2 3 4 5 6 <!-- ❌ 危险配置示例 --># server-dangerous-mcp/server.py # 问题：提供完整 shell 执行权限，无任何限制 _command(args): import subprocess return subprocess.run(args, shell=True, capture_ output=True)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 <!-- ✅ 安全配置示例 --># server-safe-mcp/server.py # 改进：白名单限制、可审计日志、隔离执行环境 _COMMANDS = { 'git': ['status', 'log', 'diff'], 'npm': ['install', 'run', 'test'] } def execute_ command(command, args): if command not in ALLOWED_COMMANDS: raise SecurityError(f"命令 {command} 未授权") if args and any(a not in ALLOWED_COMMANDS[command] for a in args): raise SecurityError(f"参数 {args} 未授权") # 记录操作日志 audit_log.info(f"已授权命令: {command} {args}") # 在隔离环境中执行 return subprocess.run( [command] + args, capture_output=True, timeout=30, cwd='/sandbox/path' # 限制工作目录 )
CLAUDE.md 安全配置示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 ## ⚠️ 安全红线 **绝对禁止：** - 在任何情况下执行 `rm -rf /` 或类似危险命令- 读取或输出 .env、*.pem、* .key 等敏感文件内容- 调用未经审计的第三方 MCP- 在代码中硬编码 API Key、密码或 Token**必须遵守：** - 所有涉及生产环境的操作必须经过人工确认- `.claudeignore` 中必须排除：.env、secrets/、**/*.pem - 使用环境变量替代硬编码凭据
敏感操作二次确认机制 1 2 3 4 5 6 7 8 9 10 11 12 13 rm -rf` 或 `del /s` | 🔴 致命 | 使用安全删除脚本 |chmod 777` | 🟠 高 | 使用最小权限原则 |
核心要点
安全不是事后补救，而是设计阶段就需要考虑的因素。给 Agent 的权限越小，越安全。
CLAUDE.md 反模式集合 以下是实践中总结的常见反模式，以及对应的正确写法。
反模式 #1：纯负面约束 1 2 3 4 5 <!-- ❌ 反模式：只说「禁止」 -->## 禁止事项 - 绝对不要使用 --force 标志- 不要修改生产环境- 禁止使用 git reset
1 2 3 4 5 <!-- ✅ 正确写法：提供可行替代方案 -->## 操作规范 - **安全更新** ：使用 `--interactive` 或 `--preview` 进行预览- **生产环境修改** ：必须通过 PR 流程，单人不得直接操作- **版本回滚** ：使用 `git revert` 替代 `git reset` ，保留历史可追溯
反模式 #2：过度引用文档 1 2 3 4 5 6 <!-- ❌ 反模式：到处 @ 引用文档 -->## 参考资料
1 2 3 4 5 6 7 8 9 <!-- ✅ 正确写法：精准引用 + 场景说明 -->## 遇到以下情况时查阅文档 `docs/api.md#errors` | 错误码对照表 |`docs/db.md#migration` | 回滚步骤 |`docs/deploy.md#production` | 环境变量清单 |`docs/troubleshooting.md` | 最佳排查步骤 |
反模式 #3：模糊的约束 1 2 3 4 5 <!-- ❌ 反模式：语义不清，Agent 难以判断 -->## 编码规范 - 代码要整洁- 遵循最佳实践- 注意性能问题
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 <!-- ✅ 正确写法：具体可执行 -->## 编码规范 **代码风格（强制执行）：** - 使用 2 空格缩进- 使用单引号而非双引号- 每行最多 120 字符**性能要求：** - 循环内禁止同步网络请求- 批量操作必须使用事务- 任何 DB 查询必须有索引支持**代码质量门槛：** - 圈复杂度 > 10 的函数必须拆分- 重复代码 > 3 次必须抽象- 测试覆盖率必须 > 80%
反模式 #4：过度复杂的斜杠命令 1 2 3 4 5 6 7 <!-- ❌ 反模式：长串需要学习的命令 --># claude_commands.json { "/deploy-staging": "1. 切换分支 2. 运行测试 3. 构建镜像 4. 推送 Staging", "/deploy-production": "1. 创建 PR 2. 代码审查 3. 合并主分支 4. CI/CD 等待 5. 健康检查", "/rollback": "1. 确认回滚版本 2. 执行回滚 3. 验证功能 4. 通知团队" }
1 2 3 4 5 6 7 8 9 <!-- ✅ 正确写法：只保留最常用的快捷方式 --># 我的斜杠命令配置（仅 2 个） `/catchup` | 读取当前分支所有更改 | 接手新任务时 |`/test` | 运行单元测试并输出结果 | 代码提交前 |**原则** ：任何需要查文档才能记住的命令，都是失败的设计。
反模式 #5：缺少上下文化说明 1 2 3 4 5 <!-- ❌ 反模式：只说「要什么」，不说「为什么」 -->## 代码规范 - 使用 TypeScript- 使用 React Hooks- 使用 Styled Components
1 2 3 4 5 6 7 8 9 10 11 12 <!-- ✅ 正确写法：上下文 + 理由 -->## 代码规范 **技术栈选择：** - **TypeScript** ：项目从 2023 年起全面采用，提供类型安全- **React Hooks** ：函数式组件优先，类组件仅在必要时使用（见 `docs/legacy-react.md` ）- **Styled Components** ：保持元件样式封装，避免全局污染**为什么：** - TypeScript 减少了 60% 的运行时错误- Hooks 使逻辑复用更简单- Scoped Styles 避免了样式冲突
核心要点
好的 CLAUDE.md 应该是具体的、可执行的、有上下文的 ，而非模糊的道德规范或无所不包的百科全书。
实践检查清单 以下是开始任何开发工作前，应该执行的检查清单。
会话开始前检查 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 ## 会话开始前检查清单 ### 1. 环境检查 - [ ] 确认当前 git 分支正确- [ ] 确认没有未提交的紧急变更- [ ] 确认 .claudeignore 已配置- [ ] 确认目标 MCP 已启动并正常### 2. 上下文检查 - [ ] 运行 `/context` 了解当前 token 使用情况- [ ] 检查是否有残留的 `.claude/session-*` 需要清理- [ ] 确认 CLAUDE.md 是否需要更新（新仓库）### 3. 任务确认 - [ ] 清楚理解任务目标和验收标准- [ ] 识别任务复杂度（简单/中等/复杂）- [ ] 规划是否需要使用 Plan 模式
编码前检查 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 ## 编码前检查清单 ### 1. 上下文收集（强制） - [ ] 执行文件名搜索，找到 5-10 个候选文件- [ ] 执行内容搜索，找到关键实现位置- [ ] 深度阅读至少 3 个相似实现- [ ] 生成 `.claude/context-summary-[任务名].md` ### 2. 充分性验证 - [ ] 能说出至少 3 个相似实现的文件路径吗？- [ ] 理解项目的实现模式吗？- [ ] 知道有哪些可复用的工具函数吗？- [ ] 理解项目的命名约定和代码风格吗？- [ ] 知道如何测试这个功能吗？- [ ] 确认没有重复造轮子吗？- [ ] 理解这个功能的依赖和集成点吗？### 3. 设计确认 - [ ] 接口规格已定义- [ ] 边界条件已识别- [ ] 性能要求已明确- [ ] 测试标准已制定
代码提交前检查 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 ## 代码提交前检查清单 ### 1. 代码质量 - [ ] 所有自动化测试通过- [ ] 类型检查通过（TypeScript）- [ ] 格式化检查通过（Prettier/ESLint）- [ ] 没有 TODO 注释遗留### 2. 上下文记录 - [ ] 更新 `operations-log.md` - [ ] 验证报告已生成（`.claude/verification-report.md` ）- [ ] 复用了既有组件- [ ] 遵循了项目约定### 3. 安全检查 - [ ] 没有硬编码的 API Key 或密码- [ ] 敏感操作已记录日志- [ ] 没有绕过 .claudeignore 读取敏感文件
核心要点
检查清单不是负担，而是避免低级错误 的最后一道防线。
决策框架 在日常使用中，我们经常面临各种选择。以下框架可以帮助做出更好的决策。
1. 会话重启决策树 1 2 3 4 5 6 7 8 9 10 11 12 13 开始会话50 %50 -70 %，任务简单clear + 继续对话50 -70 %，任务复杂70 %，或出现幻觉clear + 重新开始
2. MCP 引入决策矩阵 问题 MCP 解决？ 自建 MCP？ CLI/Skills？ 需要访问外部 API ✅ 是 ⚠️ 评估 ❌ 不适用 需要执行敏感操作 ⚠️ 谨慎 ✅ 是 ❌ 不适用 只是一次性查询 ❌ 否 ❌ 否 ✅ 是 需要环境状态持久化 ⚠️ 复杂 ✅ 是 ❌ 否 简单的数据转换 ❌ 否 ❌ 否 ✅ 是
3. Plan 模式使用决策 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 ## 什么时候使用 Plan 模式？ ### 必须使用（复杂变更） - 新功能涉及 3 个以上模块- 数据库 schema 变更- API 破坏性变更- 涉及安全或权限修改- 团队协作项目### 可选使用（中等复杂度） - 单模块重构- 新增 1-2 个 API 端点- 样式或 UI 调整- 文档结构变更### 不需要（简单任务） - 修复明确的 bug- 添加单一测试用例- 更新文档错别字- 简单的配置调整
4. 上下文收集深度决策 任务复杂度 搜索范围 阅读数量 深度 简单 （单文件、<50 行）本目录 1-2 个 浅 中等 （多文件、<200 行）整个 src 3-5 个 中 复杂 （架构级、>200 行）跨目录 + 外部 5+ 个 深
核心要点
决策框架的价值不在于给出标准答案，而在于避免在选择上浪费过多认知资源 。
常见问题解决方案 Q1：Agent 无视 CLAUDE.md 约束 症状 ：明确写了「不要使用某种方式」，但 Agent 仍然使用。
原因分析 ：
约束语义不清，Agent 理解错误 没有提供替代方案 约束与其他规则冲突 解决方案 ：
1 2 3 <!-- ❌ 问题配置 -->## 约束 - 不要使用 shell=True
1 2 3 4 5 <!-- ✅ 解决方案配置 -->## 约束 - **网络请求** ：使用 `requests` 库而非 shell 命令- **文件操作** ：使用 Python 的 `pathlib` 而非 `os.system` - **任何子进程** ：必须指定 `shell=False` ，禁止使用 shell 注入
验证方法 ：观察 Agent 连续 3 次任务后是否遵守。
Q2：上下文窗口爆炸 症状 ：对话进行到一半，Agent 开始产生幻觉或忘记之前的约束。
原因分析 ：
读取了过多文件到上下文 历史对话记录累积 没有定期清理 解决方案 ：
1 2 3 4 5 6 7 8 9 10 11 echo "node_modules/" >> .claudeignoreecho "*.log" >> .claudeignoreecho "dist/" >> .claudeignoreecho ".git/" >> .claudeignore
预防策略 ：
不要一次性让 Agent 读取整个项目 使用 .claudeignore 排除 node_modules、dist、.git 等 每完成一个子任务，主动 /clear Q3：MCP 权限过大 症状 ：Agent 使用 MCP 执行了预期外的操作（如删除文件、发送请求）。
原因分析 ：
MCP 配置时没有设置权限限制 没有二次确认机制 缺少操作日志 解决方案 ：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 class PermissionMiddleware :def __init__ (self ):r'rm\s+-rf' ,r'drop\s+table' ,r'delete\s+from' ,r'exec\s*\(' ,async def check_permission (self, action: str ) -> bool :for pattern in self.sensitive_patterns:if re.search(pattern, action, re.IGNORECASE):return False return True if not await middleware.check_permission(request.action):raise PermissionDenied("敏感操作需要人工确认" )
Q4：Session 混乱 症状 ：多个项目同时开发，Session 混在一起，不知道在哪个项目上下文中。
原因分析 ：
没有区分不同项目的会话 Session 名称不明确 长期积累的无效会话 解决方案 ：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 ls -la ~/.claude/projects/"项目A-功能X-2025-12-25" type d -mtime +30 | \"active" | \rm -rf
Q5：生成代码与现有风格不一致 症状 ：Agent 生成的代码缩进风格、命名规范与现有代码库不同。
原因分析 ：
没有在 CLAUDE.md 中明确风格规范 Agent 读取的文件不够多 没有指定格式化工具 解决方案 ：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 # CLAUDE.md 中添加 ## 代码风格规范 **格式要求：** - 缩进：4 空格（禁止 Tab）- 引号：单引号优先- 分号：JavaScript 必须使用，Python 不需要- 行尾：LF（禁止 CRLF）**命名规范：** - 变量/函数：camelCase- 类名：PascalCase- 常量：UPPER_SNAKE_ CASE- 文件夹：kebab-case**文件头：** - 所有 .ts/.js 文件必须有 @fileoverview 注释
具体配置示例 以下是几个可以直接复制使用的配置示例。
示例 1：完整的 .claudeignore 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 log env env .*.local
示例 2：JavaScript 项目的 CLAUDE.md 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 # CLAUDE.md ## 概览 ## 技术栈 - **运行时** ：Node.js 18+- **语言** ：TypeScript 5.0+- **框架** ：Express 4.18+- **ORM** ：Prisma 5.0+- **测试** ：Jest + Supertest## 代码规范 **格式与风格：** - 缩进：2 空格- 引号：单引号- 分号：必须- 行尾：LF**命名约定：** - 变量/函数：camelCase- 类/接口：PascalCase- 常量：UPPER_SNAKE_ CASE- 文件：kebab-case**文件结构：**
src/
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 ## 数据库操作 **禁止事项：** - ❌ 禁止直接写 SQL（使用 Prisma ORM）- ❌ 禁止在代码中硬编码连接字符串- ❌ 禁止使用 `any` 作为类型**正确做法：** - 使用 `prisma.client.ts` 中的实例- 配置通过 `config/` 读取- 类型必须明确定义## API 响应格式 ```typescript // 成功响应 { success: true, data: T, message?: string } // 错误响应 { success: false, error: { code: string, message: string } }
测试要求 所有 API 端点必须有集成测试 业务逻辑必须有单元测试 测试文件命名：*.spec.ts 或 *.test.ts 部署注意事项 生产环境变量必须通过环境变量注入 数据库迁移：npm run db:migrate 服务启动：npm run start1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 function claude-start local project=$(basename $(pwd ))local task=${1:-"开发任务"} local date =$(date +%Y-%m-%d)echo "🚀 启动新会话：$project - $task - $date " "$project -$task -$date " function claude-resume local session=$1 if [ -z "$session " ]; then echo "📋 可用会话：" ls -ct ~/.claude/projects/ | head -10return fi "$session " function claude-cleanup local days=${1:-30} echo "🧹 清理 $days 天前的会话..." type d -mtime +$days -exec rm -rf {} \; 2>/dev/nullecho "✅ 清理完成" function claude-status echo "📊 Claude Code 状态" echo "" echo "最近会话：" ls -ct ~/.claude/projects/ 2>/dev/null | head -5echo "" echo "活跃 MCP：" '{print $2, $11}' cat << EOF Claude Session Manager 使用方法： claude-start <任务名> 启动新会话 claude-resume <会话名> 恢复会话（不带参数则列出最近会话） claude-cleanup [天数] 清理旧会话（默认 30 天） claude-status 查看状态 示例： claude-start "支付模块重构" claude-resume "电商-支付模块-2025-12-20" EOF
示例 4：安全 MCP 模板 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 """ 安全 MCP 服务器模板 提供最小权限、可审计、隔离执行的 MCP """ import asyncioimport jsonimport loggingfrom pathlib import Pathfrom typing import Any , Dict , List , Optional from datetime import datetime"safe-mcp" )class SafeMCPServer :"""安全 MCP 服务器基础类""" def __init__ (self, allowed_operations: List [str ] ):set (allowed_operations)List [Dict ] = []"/tmp/mcp-sandbox" True , exist_ok=True )def _audit (self, operation: str , args: Dict , result: Any ):"""记录操作审计日志""" "timestamp" : str (datetime.now()),"operation" : operation,"args" : str (args),"result" : str (result)[:500 ] f"[AUDIT] {operation} with {args} " )def _check_permission (self, operation: str , args: Dict ) -> bool :"""权限检查""" if operation not in self.allowed_operations:f"[BLOCKED] 未授权操作: {operation} " )return False return True async def execute (self, operation: str , args: Dict ) -> Dict :"""安全执行操作""" if not self._check_permission(operation, args):return {"error" : "未授权的操作" , "operation" : operation}if not self._validate_args(operation, args):return {"error" : "参数验证失败" , "operation" : operation}try :await self._execute_safe(operation, args)return {"success" : True , "result" : result}except Exception as e:f"[ERROR] {operation} 失败: {e} " )return {"error" : str (e), "operation" : operation}def _validate_args (self, operation: str , args: Dict ) -> bool :"""子类实现参数验证""" return True async def _execute_safe (self, operation: str , args: Dict ) -> Any :"""子类实现具体操作""" raise NotImplementedErrorclass ReadOnlyFileMCP (SafeMCPServer ):"""只读文件 MCP - 只允许读取，禁止写入""" def __init__ (self, root_path: str = "." ):super ().__init__(["read_file" , "list_directory" , "search_files" ])if not self.root_path.exists():raise ValueError(f"根路径不存在: {root_path} " )def _check_permission (self, operation: str , args: Dict ) -> bool :"""路径安全检查""" if not super ()._check_permission(operation, args):return False if operation == "read_file" :"path" , "" ))if not str (full_path).startswith(str (self.root_path)):f"[BLOCKED] 目录遍历尝试: {file_path} " )return False ".env" , ".pem" , ".key" , "secrets" ]if any (p in str (full_path).lower() for p in sensitive_patterns):f"[BLOCKED] 敏感文件访问尝试: {file_path} " )return False return True async def _execute_safe (self, operation: str , args: Dict ) -> Any :"""安全执行""" if operation == "read_file" :"path" ]return {"content" : path.read_text(encoding="utf-8" )}elif operation == "list_directory" :"path" , "." )return {"files" : [f.name for f in path.iterdir()]}elif operation == "search_files" :"pattern" , "*" )list (self.root_path.rglob(pattern))return {"matches" : [str (f.relative_to(self.root_path)) for f in files]}if __name__ == "__main__" :import sys1 ] if len (sys.argv) > 1 else "." print (f"🚀 安全文件 MCP 已启动，根目录: {mcp.root_path} " )print (f"✅ 只读模式，禁止敏感文件访问" )print (f"📝 所有操作将被审计记录" )
核心要点
配置示例的价值在于可直接复制落地 ，而非「看起来很厉害」。以上示例均经过实践验证，可放心使用。
文档生成时间：2025-12-25 版本：2.0（增强版）