企业官网建设流程全解析

在 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/这类子目录编写"目录级 Memory"（CLAUDE.md），让 Claude Code 在处理 API 代码时自动加载模块专属规范。读完本文，你将掌握 Memory 文件的拼接（concatenate）机制、API 模块六大规范（校验、认证、响应格式、分页、限流、缓存）的完整写法，以及如何把这个模板直接复制进自己的项目目录使用。

一、什么是目录级 Memory：CLAUDE.md 的按需加载机制

claude-howto 的 Memory 体系将CLAUDE.md按作用范围分为多个层级（见 zh/02-memory/README.md）：

directory-api-CLAUDE.md就是"目录记忆"层的典型代表。它的第一段说明了两条关键机制：

1. 拼接而非覆盖：目录级文件是对根目录CLAUDE.md的补充，根目录规则依然生效。Claude Code 会在读取/src/api/下的文件时，按需加载这份目录级 memory。
2. 按路径触发：该文件只作用于/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 token；
• token 放在Authorizationheader中（标准形式为Authorization: Bearer <token>）；
• token24 小时后过期；
• 实现 refresh token 机制（避免用户每 24 小时重新登录一次）。

24 小时的短期访问令牌（access token）配合 refresh token，是兼顾安全性与体验的通行做法：短期令牌缩小了令牌泄露的暴露窗口，refresh token 则允许客户端在令牌过期后静默续期。若 token 缺失、过期或非法，错误响应的error.code可约定为UNAUTHORIZED，HTTP 状态码使用 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" }

请求端携带?cursor=eyJpZCI6MTAwMn0=&limit=20获取下一页；当hasMore为false时即到达末尾。客户端应能处理"limit 缺省为 20、最大 100"这两个边界。

六、限流：配额、429 与 retry-after

API 必须有明确的流量配额，规范给出的默认值为：

• 已认证用户：每小时1000次请求；
• 公开端点：每小时100次请求；
• 超出时返回HTTP 429（Too Many Requests）；
• 响应中包含retry-afterheader，告知客户端等待秒数。

这一节的价值在于把"限流阈值"这种最容易在团队中产生分歧的常量写死进 memory，Claude 在生成或评审 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 的黄金法则完全一致：

1. 只放该目录专属的、影响行为的信息——校验、认证、响应格式、分页、限流、缓存都是 API 模块每行代码都会涉及的约定，属于"每次会话都适用"的内容；
2. 用可执行的数值写死约定——24 小时过期、1000 次/小时、页大小 20/上限 100、缓存 5 分钟，全部是可直接实现的常量；
3. 避免风格指南与实现细节——缩进、命名这类交给 prettier/eslint，不要写进 memory（这正是 claude-md Skill 反复强调的"不要把 Claude 当成 lint 工具"）；
4. 目标长度短小——整个 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