在 Claude Code 中为 API 模块编写目录级 Memory以 claude-howto 的 directory-api-CLAUDE.md 为模板【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto导读本文以开源仓库 claude-howto 的 zh/02-memory/directory-api-CLAUDE.md 为骨架讲解如何为src/api/这类子目录编写目录级 MemoryCLAUDE.md让 Claude Code 在处理 API 代码时自动加载模块专属规范。读完本文你将掌握 Memory 文件的拼接concatenate机制、API 模块六大规范校验、认证、响应格式、分页、限流、缓存的完整写法以及如何把这个模板直接复制进自己的项目目录使用。一、什么是目录级 MemoryCLAUDE.md 的按需加载机制claude-howto 的 Memory 体系将CLAUDE.md按作用范围分为多个层级见 zh/02-memory/README.md层级作用范围典型内容受管策略组织级合规、安全、统一流程项目记忆单个项目架构、编码标准、工作流目录记忆子目录模块约束、局部规范用户记忆单个用户个人偏好、默认设置directory-api-CLAUDE.md就是目录记忆层的典型代表。它的第一段说明了两条关键机制拼接而非覆盖目录级文件是对根目录CLAUDE.md的补充根目录规则依然生效。Claude Code 会在读取/src/api/下的文件时按需加载这份目录级 memory。按路径触发该文件只作用于/src/api/下的所有内容是典型的渐进式披露——大项目不必把全部规则塞进一个巨型文件而是按目录拆分成多个局部规则文件。这一设计理念在仓库的 zh/03-skills/claude-md/SKILL.md 中得到了印证该 Skill 明确指出目录级 CLAUDE.md 应该更聚焦且系统提示词会告诉 Claude CLAUDE.md 可能相关也可能不相关——因此目录级文件只写该目录独有的、高影响的约束能显著降低上下文噪音。安装与验证按 zh/README.md 中的安装示例把模板复制到目标项目即可# 目录记忆作用于目标项目的 src/api/ 子树 cp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md验证是否生效参照 zh/02-memory/README.md重新打开 Claude Code 会话检查src/api/CLAUDE.md是否被自动加载用一条明显会受 memory 影响的提示词测试例如在src/api/下新增一个用户列表接口请遵循模块规范。二、请求校验Zod Schema 与字段级错误目录级规范的第一条硬性要求是输入校验使用Zod做 schema 校验始终校验输入包括合法业务路径的输入不只是边界条件校验失败时返回HTTP 400提供字段级别的错误详情。Zod 是 TypeScript 生态最主流的运行时 schema 校验库之一它能把类型声明与运行时校验统一起来。配合下面的响应格式一节校验失败的响应应形如{ success: false, error: { code: VALIDATION_ERROR, message: 用户可读消息, details: { email: 无效的邮箱格式, age: 必须为 0-120 之间的整数 } }, timestamp: 2025-11-06T10:30:00Z }details字段承载字段级别的错误映射字段名 → 错误原因这是客户端能直接展示给用户的最小可用信息结构。规范要求始终校验也意味着不要因为参数来自内部服务就跳过校验所有进入 API 层的输入都走同一套 schema。三、认证JWT Refresh Token 机制所有端点都必须通过认证规范定义如下所有端点都需要JWT tokentoken 放在Authorizationheader中标准形式为Authorization: Bearer tokentoken24 小时后过期实现 refresh token 机制避免用户每 24 小时重新登录一次。24 小时的短期访问令牌access token配合 refresh token是兼顾安全性与体验的通行做法短期令牌缩小了令牌泄露的暴露窗口refresh token 则允许客户端在令牌过期后静默续期。若 token 缺失、过期或非法错误响应的error.code可约定为UNAUTHORIZEDHTTP 状态码使用 401。四、统一响应格式成功与错误的结构约定所有响应必须遵循同一结构这是整个 API 最容易产生分歧、也最值得在 memory 中固化的约定。成功响应{ success: true, data: { /* 实际数据 */ }, timestamp: 2025-11-06T10:30:00Z, version: 1.0 }错误响应{ success: false, error: { code: VALIDATION_ERROR, message: 用户可读消息, details: { /* 字段错误 */ } }, timestamp: 2025-11-06T10:30:00Z }几个约定要点success布尔值让客户端无需解析 HTTP 状态码即可判断结果错误响应用机器可读的code如VALIDATION_ERROR配合用户可读的message便于程序化处理与展示details仅在需要字段级错误时填充timestamp使用 ISO 8601 UTC 格式如2025-11-06T10:30:00Z避免时区歧义version标记 API 响应版本方便客户端做兼容判断。这个统一信封envelope结构意味着任何 handler 都不应裸返回业务数据而必须经过统一的响应包装层。五、分页基于 Cursor 而非 Offset分页规范是一份明确的不要用老办法的约定使用基于 cursor 的分页而不是 offset响应中包含hasMore布尔值单页最大数量限制为 100默认页大小20。Cursor 分页相对 offset 分页的核心优势在于数据在分页过程中发生变化时不会产生重复或遗漏offset 分页在新增/删除行时会出现偏移错乱且 cursor 通常对应数据库索引深翻页性能更稳定。与统一响应格式结合典型的分页响应如下{ success: true, data: { items: [ /* 当前页数据最多 100 条 */ ], nextCursor: eyJpZCI6MTAwMn0, hasMore: true }, timestamp: 2025-11-06T10:30:00Z, version: 1.0 }请求端携带?cursoreyJpZCI6MTAwMn0limit20获取下一页当hasMore为false时即到达末尾。客户端应能处理limit 缺省为 20、最大 100这两个边界。六、限流配额、429 与 retry-afterAPI 必须有明确的流量配额规范给出的默认值为已认证用户每小时1000次请求公开端点每小时100次请求超出时返回HTTP 429Too Many Requests响应中包含retry-afterheader告知客户端等待秒数。这一节的价值在于把限流阈值这种最容易在团队中产生分歧的常量写死进 memoryClaude 在生成或评审 API 代码时就会自动按此实现中间件而不是凭感觉给一个数字。retry-after是 HTTP 标准 header客户端可以据此做指数退避或简单等待重试。七、缓存Redis 会话缓存与失效策略缓存约定直接指定了技术选型与策略使用Redis做会话缓存缓存时长默认 5 分钟写操作时失效缓存保证读写一致性用资源类型给缓存键打标签。写操作时失效缓存是缓存一致性的核心策略任何创建、更新、删除操作发生后立即删除对应资源类型的缓存键避免客户端读到陈旧数据。缓存键带资源类型标签例如cache:user:id、cache:product:id一方面便于按资源批量清理另一方面也方便在 Redis 中按前缀排查问题。八、模块规范的组织方式目录级 Memory 的最佳实践directory-api-CLAUDE.md展示了编写高质量目录级 memory 的几个要点这些要点与 zh/03-skills/claude-md/SKILL.md 的黄金法则完全一致只放该目录专属的、影响行为的信息——校验、认证、响应格式、分页、限流、缓存都是 API 模块每行代码都会涉及的约定属于每次会话都适用的内容用可执行的数值写死约定——24 小时过期、1000 次/小时、页大小 20/上限 100、缓存 5 分钟全部是可直接实现的常量避免风格指南与实现细节——缩进、命名这类交给 prettier/eslint不要写进 memory这正是 claude-md Skill 反复强调的不要把 Claude 当成 lint 工具目标长度短小——整个 API 模块规范不到 60 行符合目录级 CLAUDE.md 应该更聚焦的指导。九、配套模板与进阶阅读claude-howto 的 02-memory 模块 还提供了另外两类模板可与目录级 memory 组合成完整的分层记忆体系项目级 memory 模板project-CLAUDE.md保存团队规范、架构、Git 工作流、测试要求等全项目通用规则个人级 memory 模板personal-CLAUDE.md保存个人偏好、沟通风格与工具链安装到~/.claude/CLAUDE.md。关于文件位置与安装速查可参考 zh/QUICK_REFERENCE.md其中明确了src/api/CLAUDE.md即目录级 memory 的标准位置关于 CLAUDE.md 内容策略WHAT/WHY/HOW、渐进式披露与反模式清单可进一步阅读 zh/03-skills/claude-md/SKILL.md。仓库根目录的 CLAUDE.md 则展示了项目级 memory 的实际写法可作为对照参考。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考