folder-specific-claude-and-agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Folder CLAUDE.md Creation

文件夹级CLAUDE.md创建

Generate a focused

CLAUDE.md

inside a target folder, plus an

AGENTS.md

symlink pointing at it. The file gives any future agent (Claude Code, Codex, etc.) the folder-specific context the global

CLAUDE.md

doesn't cover.

Background reference:

library/claude-code/claude-and-agents-md.md

在目标文件夹中生成聚焦的

CLAUDE.md

文件，同时创建指向它的

AGENTS.md

符号链接。该文件可为任何未来的Agent（Claude Code、Codex等）提供全局

CLAUDE.md

未覆盖的文件夹专属上下文信息。

参考背景文档：

library/claude-code/claude-and-agents-md.md

。

Process

流程

Step 1: Confirm the target folder + sanity-check it deserves a file

步骤1：确认目标文件夹并检查是否需要创建文件

Ask the user which folder. Use the absolute path under the user's workspace folder.

Only create a file if the folder has context needed across multiple sessions — active evolving work, specific conventions, ongoing decisions. A folder of static reference files does NOT need one (agents can read on demand). If unsure, ask the user.

询问用户目标文件夹路径，使用用户工作区文件夹下的绝对路径。

仅当文件夹存在跨会话所需的上下文信息时才创建文件——比如正在迭代的工作、特定约定、持续推进的决策。静态参考文件组成的文件夹不需要创建此类文件（Agent可按需读取）。若不确定，询问用户。

Step 2: Read every file in the folder IN FULL

步骤2：完整读取文件夹内的所有文件

Use
```
ls -la
```
first to enumerate files and subfolders.
Read every markdown, config, and key source file.
For large tldraw/Vite subprojects: read
```
package.json
```
,
```
src/App.tsx
```
, one representative module file, and the folder's own
```
module-details.md
```
-style files.
Do NOT skim. Do NOT skip. The user's later edits depend on you having full context.

先使用
```
ls -la
```
命令枚举文件和子文件夹。
读取所有markdown、配置文件及关键源码文件。
对于大型tldraw/Vite子项目：读取
```
package.json
```
、
```
src/App.tsx
```
、一个代表性模块文件，以及文件夹自身的
```
module-details.md
```
类文件。
不得略读，不得跳过。用户后续的编辑依赖于你掌握完整上下文。

Step 3: Draft a bullet list of candidate content

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

Before writing the file, give the user a bullet list grouped by section — let them react first. Candidate sections (skip any that don't apply):

Product / Purpose — what this folder/project is, current state, key metrics
Avatar / Audience — who it's for (if applicable)
Essential Files — one-line role for each important file, including cross-folder references (use
```
@path/file.md
```
import syntax)
Constraints (MUST NOT) — explicit hard negatives. Highest-ROI content in the file.
Conventions — the user's lingo, status emojis (✅ 🟡), naming patterns, "usually do" patterns
Locked Decisions — things agreed + dated, must not re-litigate
Context — history, authority, credibility that frames the work
How to work with the user — collaboration style for this specific folder
Marketing Angles / Positioning — if public-facing
Top Insights — 3-5 most glaring signals from research (if research exists)

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

产品/用途——此文件夹/项目的定位、当前状态、关键指标
受众——面向的用户群体（如适用）
核心文件——每个重要文件的单行说明，包括跨文件夹引用（使用
```
@path/file.md
```
导入语法）
约束条件（严禁）——明确的硬性禁止项，是文件中ROI最高的内容
约定规范——用户的术语、状态表情符号（✅ 🟡）、命名模式、「通常做法」
已锁定决策——已达成共识并标注日期的事项，不得重新讨论
背景上下文——支撑工作的历史、权限、可信度信息
与用户协作方式——针对此文件夹的特定协作风格
营销角度/定位——若面向公众
核心洞察——从研究中提炼的3-5个最显著结论（如有研究）

Step 4: Iterate with the user

步骤4：与用户迭代优化

Keep answers short. The user will edit directly in the IDE.
When the user edits the file, RE-READ it and flag: contradictions, typos, missing rules, wrong categorization.
Do not revert the user's edits unless asked.

回复保持简洁。用户将直接在IDE中编辑文件。
当用户编辑文件时，重新读取并标记：矛盾点、拼写错误、缺失规则、分类错误。
除非用户要求，否则不要回滚用户的编辑。

Step 5: Write the file

步骤5：编写文件

Path:
```
<folder>/CLAUDE.md
```
Start with a one-line header explaining the file's purpose.
Subdir file marker: if this is a subdirectory file (parent folder already has its own CLAUDE.md), open with
```
Apply root CLAUDE.md first, then this file.
```
Use
```
##
```
section headers matching the sections the user approved.
Bullets over prose. Short bullets.
Cross-folder references: use
```
@relative/path/file.md
```
import syntax, not prose mentions.
Heavy reference docs: annotate with
```
**Read when:**
```
triggers (e.g. "Read when: writing offer copy"). Prevents loading every session.

路径：
```
<folder>/CLAUDE.md
```
开头用一行标题说明文件用途。
子目录文件标记：如果这是子目录文件（父文件夹已有自己的CLAUDE.md），开头需添加
```
先应用根目录CLAUDE.md，再应用此文件。
```
使用与用户认可章节匹配的
```
##
```
级标题。
优先使用项目符号，且保持简短。
跨文件夹引用：使用
```
@relative/path/file.md
```
导入语法，而非文字描述。
重度参考文档：标注
```
**读取时机：**
```
触发条件（例如「读取时机：撰写推广文案时」），避免每次会话都加载。

Step 6: Create the AGENTS.md symlink

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

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

Verify with

ls -la CLAUDE.md AGENTS.md

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

使用

ls -la CLAUDE.md AGENTS.md

命令验证。

Step 7: Commit only when asked

步骤7：仅在用户要求时提交

Do NOT stage or push unless the user says to. When they do:

git add -A

, commit with a

Day N:

style message, push.

除非用户指示，否则不要暂存或推送代码。当用户要求时：执行

git add -A

，使用

Day N:

格式的提交信息，然后推送。

Rules

规则

Never invent content. Every bullet must trace back to something you read in the folder or something the user said. No generic boilerplate.
Brevity wins. The user edits aggressively to make things shorter. Start tight.
Folder-scoped only. Don't duplicate the global
```
CLAUDE.md
```
(personality, dates, ports, etc.). Only include what's specific to this folder.
No file trees, no directory dumps, no stack details the code already shows. Anything an agent can derive from
```
ls
```
or
```
grep
```
rots fast and wastes tokens. Pin decisions, rules, and context — not structure.
Constraints vs Conventions. Hard "MUST NOT" rules go in Constraints (explicit negatives). "Usually do X" patterns go in Conventions. Splitting these improves adherence.
No absolute ALWAYS/NEVER without explicit exceptions. Edge cases make absolute rules get ignored. "Never commit secrets EXCEPT
```
.env.example
```
" beats "never commit secrets."
Never summarize or auto-shorten the file. Context collapse degrades it. Grow deliberately, prune manually. If the user asks to trim, do it by hand.
Maintenance loop. When the user corrects the agent on something this file should have prevented, add the rule to the file immediately. Don't wait.
No emojis unless the user uses them (status markers ✅ 🟡 are the exception — they're already conventions).
Symlink, not copy.
```
AGENTS.md
```
must be a symlink so edits stay in sync.
Flag gaps honestly. If the user's edits introduce contradictions (e.g. "sell X" in one section and "never sell X" in another), call it out before they ask.

禁止编造内容：每个项目符号必须源自你在文件夹中读取的内容或用户的表述，不得使用通用模板。
简洁至上：用户会主动编辑以精简内容，初始版本需紧凑。
仅限文件夹范围：不得重复全局
```
CLAUDE.md
```
中的内容（如个性设置、日期、端口等），仅包含此文件夹的专属信息。
禁止文件树、目录转储、代码已体现的栈细节：Agent可通过
```
ls
```
或
```
grep
```
获取的信息会快速过时且浪费token。重点记录决策、规则和上下文，而非结构。
区分约束与约定：硬性「严禁」规则放入约束条件（明确禁止项），「通常做法」放入约定规范。拆分后可提升合规性。
无明确例外时，禁止使用绝对的总是/从不：边缘情况会导致绝对规则被忽略。例如「除
```
.env.example
```
外，严禁提交机密信息」优于「严禁提交机密信息」。
禁止自动总结或缩短文件：上下文丢失会降低文件价值。需刻意扩展，手动精简。若用户要求删减，需手动操作。
维护循环：当用户纠正了本应被此文件避免的错误时，立即将规则添加到文件中，不得拖延。
除非用户使用，否则禁止添加表情符号（状态标记✅ 🟡除外——它们已属于约定规范）。
使用符号链接而非复制：
```
AGENTS.md
```
必须是符号链接，确保编辑内容同步。
如实标记漏洞：若用户的编辑引入矛盾（例如某部分写「售卖X」，另一部分写「严禁售卖X」），需在用户询问前指出。