用途：为项目生成或修复 CLAUDE.md，只保留代理无法从代码推断的信息，并加入验证习惯，保护无法自行评估代理输出的使用者。适用场景：启动新项目、仓库没有 CLAUDE.md、现有文件超过约 60 行有效内容或已过时、为非专业开发者配置项目。
核心原则：只写代理读代码无法得知的内容。代理能读目录树、推断框架、看到类型，但不知道你的 Canvas 课程 id、部署需要某个踩坑才学会的参数、或哪个是重要的 staging 数据库。判断标准：删掉这行会不会导致错误？不会就删。
应包含：无法猜到的命令、环境变量与外部 id 和端点、耗费数小时的坑、验证命令、安全边界、当前重点与下一步。应排除：读代码可发现的内容、目录树与类型列表、通用框架文档（改为链接）、会过时的代码片段、空占位章节、模糊建议。
步骤：1. 检查现有文件，保留不可推断内容，不要丢弃踩坑经验。2. 根据 package.json、pyproject.toml、.md 等文件判断项目类型，使命令章节贴合实际。3. 将 assets/CLAUDE.md.template 复制到仓库根目录为 CLAUDE.md。4. 只填写有真实内容的章节，其余删除。5. 运行验证每条命令，不可用的构建命令比没有更糟。6. 原样加入护栏章节。7. 关键规则考虑做成 hook 或 CI 门禁，仅在 CLAUDE.md 中的规则在长会话中会被跳过。
保持简短：有效内容控制在 60 行以内，会话日志和路线图不计入。超长时通常应把部署步骤、架构说明、排障等内联手册移到 docs/<topic>.md，留五行摘要加链接；若 docs/ 是发布根目录，改用 internal/。
维护：只保留最近一条会话日志，旧日志归档或删除；在重复失败后追加规则，而非预先添加；删除代理已能自行遵守的指令；定期重新验证命令。
常见错误：写代理能自己生成的目录树；只记录顺利路径而漏掉真正耗时的坑；把硬性要求写成散文而非 hook；留下占位章节；从其他项目复制命令而未在本项目运行。