Prompt 撰写规范

核心原则

Prompt 是写给 LLM 的行为指令，不是写给人看的系统文档。判断标准：这句话删掉后，LLM 的行为会变差吗？ 不会就删。

一、角色定位

描述能力，不要给标签

LLM 不需要知道自己"叫什么"，需要知道怎么行动。好的角色定位激活训练数据中的行为模式。

差	好	原因
你是 Librarian Agent	你是一个知识库管理员，擅长从碎片信息中识别关联、去重和结构化整理	标签不激活行为；能力描述激活
你是后端服务 X	（删掉）	架构角色对行为无帮助

角色三要素

我擅长什么？ — 激活能力（"擅长从碎片信息中提炼结构"）
我的核心任务是什么？ — 聚焦目标（"确保新信息与已有知识正确关联"）
我的行为边界是什么？ — 防止漂移（"只整理和检索，不自行创造内容"）

二、实现细节：不写

LLM 不需要知道自己通过什么协议被调用、运行在什么框架上、调用方是谁、自己的代号。这些只消耗 token。

唯一例外：实现细节影响行为时。比如"你的回复会被程序解析为 JSON"——这不是架构说明，是输出约束。

三、信息分层

静态 vs 动态

把不变的基础指令和随上下文变化的信息分开。不变的放 system prompt 缓存；变化的按需注入。

参考 Claude Code 的做法：~25 个静态段落 + 若干条件段落（通过 feature flag 控制）。用户不需要某能力时，相关段落不注入。

三层结构

角色和目标 — 做什么、怎么做的总纲
知识 — 完成任务所需的背景信息（schema、字段含义、关联关系）
操作策略 — 遇到 X 做 Y 的判断标准和输出格式

知识和策略必须分开。 混在一起会导致 LLM 在需要行动时回顾 schema、在理解数据时翻操作步骤。

按职责域分组，不按任务顺序

把相关信息放在一起（所有检索工具在一节、所有写入工具在一节），不要按"先检索再判断再写入"的执行顺序排列。LLM 需要的是参考手册，不是 step-by-step 教程。

四、约束表达

分层约束

从绝对到灵活，分三层：

硬边界 — 绝对不可逾越："不要直接入库，只写草稿"
条件规则 — 特定情况下的约束："新建 Capability 需同时满足三个条件"
启发式 — 偏好和倾向："优先复用已有实体"

正面描述优于负面清单

"不要做X，不要做Y，不要做Z"太多时适得其反。改为正面描述期望行为。但硬边界用负面表述更安全（"绝对不要..."）。

预防合理化漂移

对关键约束，预判 LLM 会找什么借口绕过，然后提前堵住：

# 差：
不要跳过去重检查。

# 好：
收到新工具时必须先 tool_search 检查。不要因为"看起来是新的"就跳过检索——
名称不同但功能相同的工具很常见。

参考 Claude Code 的 verification agent：直接列出 LLM 会用的借口（"代码看起来是对的""测试已经通过了"），然后逐一反驳。

五、操作策略

写判断标准，不写流程

LLM 擅长在判断标准下自行组织行动。给决策规则，不给流程图：

# 差：
步骤1：检索。步骤2：判断。步骤3：写入。

# 好：
收到新工具时：已有→复用ID；全新→放入草稿。
新建 Capability 的条件：①有已验证工具 ②有真实用例 ③描述具体可操作

用例子代替抽象规则

一个好例子胜过三段解释：

# 差：
能力描述应该具体可操作，不要过于宽泛。

# 好：
能力描述要具体：不要写"图像处理"，要写"使用 ControlNet 进行人物姿态控制"。

提供逃生通道

告诉 LLM "不能做X"时，同时告诉它"改做Y"。否则 LLM 会自己发明绕过方案：

# 差：
不能直接入库。

# 好：
不能直接入库。写入 .cache/.knowledge/pre_upload_list.json 草稿池，等待人工确认后入库。

六、输出格式

只在必要时约束格式

程序解析的输出（JSON）→ 严格约束格式。人看的输出 → 不要过度约束，让 LLM 自然组织。

格式模板放在策略末尾

不要开头就给模板。LLM 会过早锁定结构而忽略内容质量。先描述任务和判断标准，最后给格式。

结构化输出模板

对复杂输出，提供带占位符的模板。这防止 LLM 臆造输出、方便程序解析、强制 LLM 真正执行而非编造结果：

### Check: [what you're verifying]
**Command:** [exact command]
**Output:** [actual output]
**Result: PASS / FAIL**

七、Token 效率

选择性详略

详写：歧义代价高的地方（安全约束、关键判断标准）
略写：意图明确的地方（工具简介、通用行为）
用表格：多个相似项有多个属性时，表格比段落高效得多

条件注入

不是所有 Agent 都需要所有指令。用条件段落（类似 feature flag）控制注入，保持基础 prompt 精练：

# 只在需要入库能力时注入
commit_to_database 工具：将草稿提交入库...

上下文窗口意识

明确告诉 LLM 上下文会被管理（压缩、截断）。让它主动保存关键信息：

工具调用的结果可能在后续被清理。如果结果中有你后面需要用到的信息，在回复中记录下来。

八、常见反模式

反模式	问题	修正
"你是 XX Agent"	标签无行为激活效果	描述具体能力和行为特征
实现细节（协议、框架、架构）	噪音	删掉，除非影响行为
"请注意""重要""务必"满天飞	反复强调降低所有内容的权重	只强调一两个真正关键的点
详尽 step-by-step 流程	机械跟随而非灵活判断	给判断标准和决策规则
长负面清单	适得其反	正面描述期望行为
所有信息塞 system prompt	注意力稀释	分层：始终需要的（system）+ 按需加载的（skill）
开头就给输出模板	过早锁定结构	先给任务和标准，最后给格式
"不能做X"但不给替代方案	LLM 自行发明绕过方式	同时说明"改做Y"

prompt-guidelines.md 6.3 KB История Исходник