writing-claude-directives

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Claude Directives

编写Claude指令

Core Principles

核心原则

1. Claude is smart. Only write what it doesn't already know. Challenge each line: does this justify its token cost?

2. Positive > Negative framing. "Don't do X" triggers thinking about X (pink elephant problem). Say what TO do, not what to avoid.

markdown

undefined

1. Claude 很智能。只需要编写它不知道的内容。对每一行都要斟酌：这部分内容是否值得消耗对应的Token？

2. 正面表述 > 负面表述。"不要做X"会触发对X的思考（粉红大象效应）。要说明应该做什么，而不是避免什么。

markdown

undefined

Bad: triggers the behavior

反面示例：会触发对应的行为

Don't create duplicate files

Good: directs to correct behavior

正面示例：引导正确行为

Update existing files in place


**3. Context motivates compliance.** Explain WHY, not just WHAT. Claude generalizes from motivation.

```markdown

Update existing files in place


**3. 上下文能提升合规性**。解释原因，而不只是说明要求。Claude会从动机中进行归纳。

```markdown

Less effective

效果较差

NEVER use ellipses

More effective

效果更好

Your response will be read aloud by a text-to-speech engine, so never use ellipses since the TTS engine cannot pronounce them.


**4. Placement matters.** Instructions at prompt start and end receive higher attention. Critical rules go at boundaries.

**5. ~150 instruction limit.** More instructions = uniform degradation across ALL rules. Prune ruthlessly.

**6. Repetition enforces critical rules.** For high-stakes requirements, repeat with different framings.

你的回复会被文本转语音引擎朗读，因此请勿使用省略号，因为TTS引擎无法正确发音省略号。


**4. 位置很重要**。位于提示词开头和结尾的指令会获得更高关注度。关键规则应放在提示词的首尾位置。

**5. 指令数量限制约150条**。指令越多，所有规则的执行效果都会均匀下降。请严格精简指令。

**6. 重复强化关键规则**。对于高风险要求，用不同表述重复说明。

Token Efficiency

Token 效率

Targets:

Frequently-loaded directives: <200 words
Skills/CLAUDE.md: <500 lines total
Reference --help instead of documenting flags
Cross-reference other skills instead of repeating

Progressive disclosure: Main file is overview + links. Reference files load on-demand.

目标：

频繁加载的指令：<200词
Skills/CLAUDE.md：总内容<500行
参考--help文档而非在指令中记录参数
交叉引用其他Skill而非重复内容

**渐进式披露：**主文件仅包含概述和链接，参考文件按需加载。

Discovery (for Skills)

发现优化（针对Skills）

The

description

field determines if Claude finds your skill.

Format: Start with "Use when..." + specific triggers + what it does.

Write in third person. Injected into system prompt.

yaml

undefined

description

字段决定Claude能否发现你的Skill。

**格式：**以"Use when..."开头 + 具体触发场景 + 功能说明。

使用第三人称。该内容会被注入系统提示词。

yaml

undefined

Bad: vague, first person

反面示例：模糊，第一人称

description: I help with async testing

Good: triggers + action, third person

正面示例：触发场景+功能，第三人称

description: Use when tests have race conditions or timing dependencies - replaces arbitrary timeouts with condition polling


**Keywords:** Include error messages, symptoms, tool names Claude might search for.

description: Use when tests have race conditions or timing dependencies - replaces arbitrary timeouts with condition polling


**关键词：**包含Claude可能搜索的错误信息、症状、工具名称。

Compliance Techniques

合规技巧

Claude 4.x models are highly responsive to instructions. Lead with context and motivation; reserve imperatives for critical boundaries.

Claude 4.x模型对指令响应度很高。先说明上下文和动机；仅在关键边界使用命令式语气。

Primary: Context + Motivation

主要方法：上下文 + 动机

Explain WHY the rule exists. Claude generalizes from the explanation:

markdown

undefined

解释规则存在的原因。Claude会从解释中进行归纳：

markdown

undefined

Instead of raw authority

不要仅使用生硬要求

You MUST run tests before committing.

Provide motivation

提供动机

Run tests before committing. Untested commits break CI for the whole team and block other developers from merging their work.

undefined

提交前请运行测试。未测试的提交会破坏整个团队的CI流程，阻碍其他开发者合并工作。

undefined

Secondary: Structural Enforcement

次要方法：结构化约束

Use structure to make compliance the path of least resistance:

Pattern	Example
Workflow steps	Numbered steps with verification gates
Task tracking (TaskCreate/TaskUpdate)	Checklists without tracking = skipped steps (TodoWrite in older versions)
Forced commitment	"Announce: I'm using [skill]"
Explicit blocking	"If X happens, stop and do Y instead"

通过结构设计让合规成为最简便的选择：

模式	示例
工作流步骤	带验证关卡的编号步骤
任务跟踪（TaskCreate/TaskUpdate）	无跟踪的检查清单会被跳过（旧版本TodoWrite存在此问题）
强制声明	"Announce: I'm using [skill]"
显式阻断	"If X happens, stop and do Y instead"

Escalation: Imperatives (Use Sparingly)

升级方法：命令式语气（谨慎使用）

For Claude 4.x, aggressive language ("YOU MUST", "CRITICAL") can cause overtriggering. Use normal language first:

markdown

undefined

对于Claude 4.x，强硬措辞（"YOU MUST"、"CRITICAL"）可能导致过度触发。优先使用常规语气：

markdown

undefined

Often sufficient for 4.x

对4.x版本通常足够

Use this tool when searching for files.

Reserve imperatives for true boundaries

仅在真正关键的边界使用命令式语气

Never commit secrets to version control.


Close loopholes when needed, but prefer context over authority:

```markdown

Never commit secrets to version control.


必要时填补漏洞，但优先选择上下文说明而非强硬要求：

```markdown

Good: context + loophole closure

优秀示例：上下文+漏洞填补

Write the test first. Code written before its test tends to test the implementation rather than the behavior, making refactoring harder later. If you find yourself with untested code, delete it and start with the test.

undefined

先编写测试用例。先写代码再写测试的话，测试往往针对实现细节而非业务行为，会导致后续重构更困难。如果发现自己编写了未测试的代码，请删除并从测试开始。

undefined

By Skill Type

按Skill类型区分

Type	Approach
Discipline (TDD, verification)	Context + structural enforcement + loophole closure
Technique (patterns, how-to)	Clear steps, "we want quality" framing
Reference (documentation)	Clarity only, no persuasion needed

类型	方法
纪律类（TDD、验证）	上下文+结构化约束+漏洞填补
技巧类（模式、操作指南）	清晰步骤，以"追求高质量"为表述框架
参考类（文档）	仅保证清晰，无需说服

Structure Patterns

结构模式

XML for Directives and Format Control

用于指令和格式控制的XML

Claude parses XML effectively. Use for multi-part directives:

xml

<task>What to accomplish</task>
<constraints>Hard requirements</constraints>
<output_format>Expected structure</output_format>
<examples>Input/output pairs</examples>

XML also works as format indicators:

xml

<smoothly_flowing_prose>Write report sections here</smoothly_flowing_prose>
<structured_data>JSON or tables here</structured_data>

XML outperforms markdown, JSON, or YAML for rule preservation in long prompts.

Claude能有效解析XML。可用于多部分指令：

xml

<task>要完成的任务</task>
<constraints>硬性要求</constraints>
<output_format>预期结构</output_format>
<examples>输入/输出示例</examples>

XML也可作为格式标识：

xml

<smoothly_flowing_prose>在此处编写报告章节</smoothly_flowing_prose>
<structured_data>在此处编写JSON或表格</structured_data>

在长提示词中，XML在规则保留方面的表现优于Markdown、JSON或YAML。

Match Prompt Style to Desired Output

匹配提示词风格与期望输出

The formatting style in your prompt influences Claude's response. Include markdown formatting in your prompts when you want markdown output. Remove markdown from prompts if you want plain text output.

提示词中的格式风格会影响Claude的响应。如果需要Markdown格式的输出，就在提示词中包含Markdown格式；如果需要纯文本输出，就移除提示词中的Markdown格式。

Workflows

工作流

Break complex tasks into checkable steps:

markdown

undefined

将复杂任务拆分为可检查的步骤：

markdown

undefined

Workflow

工作流

Feedback Loops

反馈循环

Validate → fix → repeat:

markdown

1. Generate output
2. Run validator
3. If errors: fix and go to step 2
4. Only proceed when validation passes

验证→修复→重复：

markdown

1. 生成输出
2. 运行验证器
3. 如果存在错误：修复并回到步骤2
4. 仅当验证通过后再继续

Degrees of Freedom

自由度匹配

Match specificity to fragility:

Task Type	Freedom	Style
Fragile operations	Low	Exact scripts, no modifications
Preferred patterns	Medium	Templates with parameters
Context-dependent	High	Principles and heuristics

根据任务的脆弱性调整指令的具体程度：

任务类型	自由度	风格
脆弱操作	低	精确脚本，不允许修改
推荐模式	中	带参数的模板
依赖上下文的任务	高	原则与启发式规则

Action Bias Templates

行动倾向模板

Proactive (Default to Action)

主动型（默认采取行动）

xml

<default_to_action>
By default, implement changes rather than only suggesting them. If the user's intent is unclear, infer the most useful likely action and proceed, using tools to discover any missing details instead of guessing. Try to infer the user's intent about whether a tool call is intended or not, and act accordingly.
</default_to_action>

xml

<default_to_action>
默认情况下，直接实施变更而非仅提供建议。如果用户意图不明确，推断最有用的可能行动并执行，使用工具发现缺失的细节而非猜测。尝试推断用户是否希望调用工具，并据此采取行动。
</default_to_action>

Conservative (Research First)

保守型（先调研）

xml

<do_not_act_before_instructions>
Do not jump into implementation or change files unless clearly instructed. When the user's intent is ambiguous, default to providing information, doing research, and providing recommendations rather than taking action. Only proceed with edits when the user explicitly requests them.
</do_not_act_before_instructions>

xml

<do_not_act_before_instructions>
除非得到明确指示，否则不要直接开始实现或修改文件。当用户意图模糊时，默认提供信息、开展调研并给出建议，而非采取行动。仅在用户明确要求时才进行编辑。
</do_not_act_before_instructions>

Overengineering Prevention

过度工程预防

Claude 4.x tends to overengineer. Include this when needed:

markdown

Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.

Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.

Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.

Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow DRY.

Claude 4.x倾向于过度工程。必要时可加入以下内容：

markdown

避免过度工程。仅进行直接要求或明显必要的变更。保持解决方案简洁且聚焦。

不要添加未被要求的功能、重构代码或进行"优化"。修复bug无需清理周边代码。简单功能无需额外的可配置性。

不要为不会发生的场景添加错误处理、回退机制或验证逻辑。信任内部代码和框架的保证。仅在系统边界（用户输入、外部API）进行验证。当可以直接修改代码时，不要使用向后兼容的垫片。

不要为一次性操作创建辅助工具、实用程序或抽象层。不要为假设的未来需求进行设计。合适的复杂度是完成当前任务所需的最低复杂度。尽可能复用现有抽象层并遵循DRY原则。

Model-Specific Notes

模型特定说明

Opus 4.5: "Think" Sensitivity

Opus 4.5："Think"敏感度

When extended thinking is disabled, Opus 4.5 is sensitive to the word "think" and variants. Replace with:

"consider" instead of "think about"
"evaluate" instead of "think through"
"determine" instead of "think whether"

当禁用深度思考时，Opus 4.5对单词"think"及其变体敏感。可替换为：

用"consider"代替"think about"
用"evaluate"代替"think through"
用"determine"代替"think whether"

Naming (for Skills)

命名规范（针对Skills）

Gerund form (verb + -ing):

writing-skills

testing-code

debugging-errors

Name by action or insight:

condition-based-waiting

not

async-helpers

动名词形式（动词+-ing）：

writing-skills

testing-code

debugging-errors

按动作或核心功能命名：

condition-based-waiting

而非

async-helpers

Common Mistakes

常见错误

Mistake	Fix
Verbose explanations	Claude knows basics - omit
Multiple valid approaches	Pick one default, escape hatch for edge cases
Vague triggers	Specific symptoms: "tests flaky", "race condition"
Deeply nested references	Keep one level deep from main file
Windows paths	Always forward slashes
Aggressive language for 4.x	Lead with context, reserve imperatives for boundaries

错误	修复方法
冗长的解释	Claude了解基础知识——省略这些内容
多种有效方法	选择一种默认方法，为边缘情况保留例外通道
模糊的触发场景	使用具体症状："tests flaky", "race condition"
深层嵌套引用	主文件仅保留一层引用
Windows路径	始终使用正斜杠
对4.x使用强硬语言	先说明上下文，仅在关键边界使用命令式语气

Anti-Rationalization

反合理化

For discipline-enforcing directives, anticipate excuses:

markdown

undefined

对于纪律约束类指令，提前预判借口：

markdown

undefined

Red Flags - STOP

危险信号——停止

If you find yourself reasoning any of these, you're rationalizing:

"This is simple enough to skip"
"I already tested manually"
"The spirit not the letter"
"This case is different"

All mean: Follow the process.

undefined

如果你发现自己有以下任何想法，说明你在合理化：

"这个太简单了，可以跳过"
"我已经手动测试过了"
"遵循精神而非字面要求"
"这个情况不一样"

以上所有想法都意味着：请遵循流程。

undefined

Testing Directives

指令测试

Baseline: Run scenario WITHOUT directive, document failures
Apply: Add directive, verify compliance
Iterate: Find new loopholes → add counters → re-test

基准测试： 在不使用指令的情况下运行场景，记录失败情况
应用指令： 添加指令，验证合规性
迭代优化： 发现新漏洞→添加应对措施→重新测试

Long-Running Tasks

长期运行任务

For multi-context-window workflows and state management across sessions, see long-running-state-patterns.md in this directory.

关于跨多上下文窗口的工作流和跨会话状态管理，请查看本目录下的long-running-state-patterns.md。

Graphviz (for Process Flows)

Graphviz（针对流程流）

See graphviz-conventions.dot for flowchart style guide.

Use flowcharts for: Non-obvious decisions, process loops, "when to use A vs B"

Don't use for: Reference material (use tables), linear steps (use lists)

请查看graphviz-conventions.dot获取流程图风格指南。

适合使用流程图的场景： 非直观决策、流程循环、"何时使用A而非B"

不适合使用流程图的场景： 参考资料（使用表格）、线性步骤（使用列表）