folder-specific-claude-and-agents-md

文件夹 CLAUDE.md 创建

在目标文件夹中生成一份聚焦的 CLAUDE.md，并创建一个指向它的 AGENTS.md 符号链接。该文件为未来的 Agent（Claude Code、Codex 等）提供全局 CLAUDE.md 未涵盖的文件夹专属背景信息。

背景参考：library/claude-code/claude-and-agents-md.md。

流程

步骤 1：确认目标文件夹，并检查是否确实需要此文件

询问用户要选择哪个文件夹。使用 <workspace-root>/ 下的绝对路径。

仅当文件夹包含需要跨多个会话保留的背景信息时才创建文件——例如正在进行且不断演变的工作、特定约定或持续作出的决策。静态参考文件夹不需要此文件（Agent 可按需读取）。如果不确定，询问用户。

步骤 2：完整读取文件夹中的每个文件

• 先使用 ls -la 列出文件和子文件夹。
• 阅读每个 Markdown、配置和关键源文件。
• 对于大型 tldraw/Vite 子项目：阅读 package.json、src/App.tsx、一个有代表性的模块文件，以及文件夹自身的 module-details.md 类文件。
• 不要略读。不要跳过。用户之后的修改有赖于你完整掌握背景信息。

步骤 3：草拟候选内容的项目符号列表

写入文件前，按章节分组向用户提供项目符号列表，先让用户反馈。可选章节（不适用时跳过）：

• 产品 / 目的 — 此文件夹/项目的用途、当前状态、关键指标
• 用户形象 / 受众 — 面向哪些人（如适用）
• 重要文件 — 每个重要文件的作用，包含跨文件夹引用（使用 @path/file.md 导入语法）
• 约束（绝对禁止） — 明确的硬性禁令。文件中投资回报最高的内容。
• 约定 — 用户的用语、状态表情符号（✅ 🟡）、命名模式、“通常采用”的做法
• 已确定的决策 — 已达成一致且注明日期的事项，不得重新讨论
• 背景 — 为工作提供背景的历史、权威性和可信度
• 如何与用户协作 — 针对此文件夹的协作方式
• 营销角度 / 定位 — 面向公众时适用
• 核心洞察 — 研究中最显著的 3–5 项信号（如果有研究）

步骤 4：与用户迭代

• 回答保持简短。用户会直接在 IDE 中编辑。
• 用户编辑文件后，重新阅读并指出：矛盾、错字、缺失规则、分类错误。
• 未经要求，不要撤销用户的修改。

步骤 5：写入文件

• 路径：<folder>/CLAUDE.md
• 以一行标题开头，说明文件用途。
• 子目录文件标记： 如果这是一个子目录文件（父文件夹已有自己的 CLAUDE.md），请以 Apply root CLAUDE.md first, then this file. 开头。
• 使用与用户批准的章节相对应的 ## 章节标题。
• 使用项目符号，少用段落。保持简短。
• 跨文件夹引用： 使用 @relative/path/file.md 导入语法，不要在正文中提及。
• 较长的参考文档： 使用 **Read when:** 触发条件进行标注（例如“编写优惠文案时阅读”）。避免每次会话都加载所有内容。

步骤 6：创建 AGENTS.md 符号链接

cd <folder> && ln -s CLAUDE.md AGENTS.md

使用 ls -la CLAUDE.md AGENTS.md 验证。

步骤 7：仅在收到要求时提交

除非用户提出要求，否则不要暂存或推送。用户提出要求时：执行 git add -A，使用 Day N: 格式的消息提交，然后推送。

规则

• 绝不编造内容。 每条要点都必须能追溯到你在文件夹中读到的内容或用户说过的话。不要写通用套话。
• 简洁为先。 用户会大幅删改内容。起草时就要简洁。
• 仅限文件夹范围。 不要重复全局 CLAUDE.md 中的内容（个性、日期、端口等）。只包含此文件夹特有的内容。
• 不要列出文件树、目录清单，也不要写代码中已有的技术栈细节。 Agent 可以通过 ls 或 grep 推导出的内容容易过时，还会浪费令牌。记录决策、规则和背景，而不是结构。
• 区分约束与惯例。 硬性“不得”规则（明确禁止事项）应放在约束中。“通常这样做”的模式应放在惯例中。分开编写有助于遵守。
• 除非明确说明例外，否则不要使用绝对的“始终”或“绝不”。 边界情况会导致绝对规则被忽视。“绝不提交机密，.env.example 除外”比“绝不提交机密”更好。
• 绝不概述或自动缩短文件。 上下文折叠会降低文件质量。应有计划地扩充，手动删减。如果用户要求精简，就手动处理。
• 维护循环。 当用户纠正了本文件本应避免的问题时，立即将规则添加到文件中。不要拖延。
• 除非用户使用表情符号，否则不要使用表情符号（状态标记 ✅ 🟡 除外——它们已经是惯例）。
• 使用符号链接，而非副本。 AGENTS.md 必须是符号链接，以便编辑内容保持同步。
• 如实指出矛盾。 如果用户的修改引入了矛盾（例如，一个章节写着“出售 X”，另一个章节写着“绝不出售 X”），应主动指出。