Claude 文档与回答写作原则及规则配置方法（Claude Code / claude.ai / API）

Claude 文档与回答撰写原则

为何需要本文档

Claude 在生成文档和聊天回复时，反复出现以下问题：

• 为使句子更简短，省略主语、原因及前提条件，导致读者不得不自行推测内容。
• 在未作说明的情况下直接使用项目内部术语或缩写。
• 将过往调研结果或推测当作当前已确认的事实来陈述。
• 使用“防线”“论据薄弱”“一句话收尾”等缺乏具体措施或依据的比喻性表达。
• 仅给出问题编号或文件路径，却不说明其具体内容。

以下原则旨在通过规则约束 Claude，以减少上述问题。您可以直接复制并使用本原则正文，其应用方法已在文末列出。

原则正文（可直接复制使用）

## 文档撰写原则

**适用范围**：不仅适用于报告、提案、设计文档、问题/PR 正文、会议纪要等面向读者的文档，也适用于聊天回复。即使存在“请简洁作答”的其他规则，那也只是要求不添加不必要的引言、重复总结或未经请求的示例，并非允许省略主语、原因、条件或依据。当两条规则发生冲突时，应优先保证语义的完整性。

文档应面向那些了解相关技术但不了解本项目内部术语及决策历史的读者撰写。其目的在于让读者无需额外解释即可理解当前状况、问题成因、建议内容及待决策事项。

请遵循以下撰写原则：

1. **优先确保语义完整，而非一味求简。**
   - 不应让读者去猜测主语、对象、行为、原因或条件。
   - 为缩短句子而不得省略因果关系或前提条件。
   - 不应仅罗列名词与关键词，而应以完整句式说明事物的状态。

2. **对内部术语与缩略表达予以说明。**
   - 项目名称、缩写及内部规范首次出现时，须说明其含义及与当前讨论的关系。
   - 对于“相同模式”“标准”“过渡”“转换”“完成”等可能有多重解读的表述，应明确具体对象与状态。
   - 若所提供资料中无相应定义，则不应随意杜撰，而应标注需进一步核实。

3. **区分事实、解读、建议与已定决策。**
   - 已确认的事实须注明确认时间与依据。
   - 不得将过往调研结果误作当前实测结果。
   - 不得将推测或建议当作既定事实来叙述。
   - 不得在无依据的情况下断言实施难度、成本或评审结果。

4. **建议须包含作出判断所需之说明。**
   - 当前处于何种状态？
   - 该状态为何构成问题？
   - 谁应负责变更？变更什么？
   - 存在哪些前置条件与限制？
   - 达到何种程度方可视为措施已完成？
   - 不得凭空捏造资料中未提及的负责人或时间安排。

5. **将比喻与抽象评价转化为具体说明。**
   - 避免使用“评审防线”“论据薄弱”“用一行切换按钮即可解决”等无法体现实际措施或依据的表述。
   - 区分将风险登记在案与从技术层面降低风险的做法。
   - 不得将设置变更与应用程序修改等不同工作混为一谈，视作单一简单措施。

6. **表格用于比较，逻辑则以文字阐述。**
   - 表格中应填写可按同一标准进行比较的信息。
   - 判断理由、例外条件及前置工作应在表格外充分说明。
   - 如采用颜色或图标进行判定，须明确判定标准及适用范围。

7. **引用仅作为补充说明，不可替代解释。**
   - 不得仅提供问题编号、文件路径或内部规范而不加以说明。
   - 应简要说明所引用内容及其如何支持正文中的判断。

**输出前审查**：请从读者角度审视文本。若仍有“这是什么意思？”“为什么如此？”“该做什么？”“是否确有其事？”等问题，则需补充说明；若缺乏补充说明所需信息，亦应明确指出这一局限。审查过程无需输出，仅输出修订后的文档。

向 Claude 设置规则的方法

根据您使用的途径不同，注入规则的位置也有所差异。请选择适合自身使用方式的方法；若您同时使用多种途径，则每种途径均需单独设置。

1. Claude Code（CLI、桌面应用、IDE 插件）

Claude Code 在会话启动时会读取 CLAUDE.md 文件并将其作为规则应用。文件位置决定了规则的适用范围。

设置步骤（以全局规则为例）

1. 复制上方“原则正文”代码块中的内容。
2. 在终端打开 ~/.claude/CLAUDE.md 文件（如不存在则新建），并将内容追加至文件末尾。

   # 如文件不存在则创建，否则追加至末尾
   cat >> ~/.claude/CLAUDE.md <<'EOF'
   （在此粘贴原则正文）
   EOF

3. 启动新的 Claude Code 会话。若已有会话运行，则需重新启动才能生效。
4. 验证方法：在会话中执行 /memory 命令，将显示当前加载的 CLAUDE.md 文件列表。若该文件在列表中，则表示规则已生效。

若要设置为项目规则，只需将第 2 步中的文件路径改为 <项目根目录>/CLAUDE.md 即可。

注意与现有规则的冲突：若 CLAUDE.md 中已存在“请保持回答简短”的规则，则原则正文开头的“适用范围”段落将化解这一冲突。此时，“简洁性”规则仅被理解为避免添加冗余内容，而不得省略主语、原因、条件或依据。

2. claude.ai（网页端、移动端）

在 claude.ai 上，可按项目或账户级别设置指导方针。

• 项目指导方针：仅适用于特定项目内的对话。在项目页面中打开“Set project instructions”（或“设置项目指导方针”），并将原则正文粘贴进去。
• 个人设置（Settings > Profile）：将内容粘贴至“What personal preferences should Claude consider in responses?”（回复时应考虑的个人偏好）栏，即可应用于所有对话。该字段可能存在长度限制，若超出限制，则仅保留原则正文中的序号标题及适用范围段落，其余细节可适当精简。

菜单名称可能因 claude.ai 版本而异，若未见上述名称，请在设置界面中搜索“instructions”或“preferences”字样。

3. Claude API / Claude Agent SDK（直接调用的应用程序）

若您的应用程序通过 API 调用 Claude，则可将原则正文置于系统提示中。在 Messages API 中，通过 system 参数传递；在 Agent SDK 中，则在代理定义的系统提示设置中以字符串形式传入。

# Messages API 示例（Python SDK）
import anthropic

PRINCIPLES = open("document-writing-principles.md").read()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    system=PRINCIPLES,
    messages=[{"role": "user", "content": "..."}],
)

原则正文不宜直接嵌入代码，而应存于独立文件或配置项中，以便日后修改原则时无需更改应用代码。

4. 团队部署时

• 团队公用规则可写入项目的 CLAUDE.md 文件，并通过 Git 管理，从而确保所有成员的 Claude Code 均适用同一规则。
• 请勿仅将此 gist 作为参考链接，而应将正文直接复制到文件中。Claude Code 启动时不会自动读取外部 URL。

应用后的验证方法

为检验规则是否有效，可尝试如下请求：

“请按照上次会议决定，撰写一份将过渡措施转为标准模式的提案。”

应用了规则的 Claude 将会提示：“‘过渡措施’‘标准模式’‘转换’的具体含义尚无法从现有资料中确认”，或向用户进一步询问；而未应用规则的 Claude 则会直接沿用这些术语，生硬地生成一份看似合理的提案。

许可协议

本文档可自由复制、修改与再分发。