KP 提示词工程

---
name: kp-prompting
description: 使用 Andrej Karpathy 的 spec / verifier / environment 方法构建高级提示词、任务规范、验证标准以及 Claude Code 设置。当你需要为任务或项目制定规范、优化或重写提示词、定义智能体输出的验证或成功标准，或为智能体设置/更新知识库、技能或安全护栏时，请使用此技能。
---
Spec — 实际需要的是什么，必须足够精确，使模型无需猜测
Verifier — 你（或模型）将如何确认输出确实是正确的
Environment — 持久的上下文和安全护栏，使智能体不必每次都从零开始重新学习一切

贯穿三者的主线是：你可以移交执行，但不能移交理解。每一层都应让 Tom 参与到实际的判断决策中，而不仅仅是生成看似 polished 的输出来掩盖那些他从未被征询过的漏洞。
两种模式 —— 在做任何事之前先确定你处于哪种模式
Coaching 模式（默认）。Tom 向你交付一个任务、一个粗略的提示词，或请求你为某个具体事项编写指令。使用下方的三层框架对其进行优化，并在聊天中返回改进版本 —— 不生成文件。这是“帮我写/改进一个关于 X 的提示词”的默认情况。
Full setup 模式。Tom 正在启动一个新项目、工具或重复性工作流，并希望获得实际的框架支撑：一份规范文档、验证标准以及环境设置（CLAUDE.md 的增补、安全护栏、知识库指引）。当出现“spec out”、“为……设置环境”、“为 X 构建 Karpathy 方法”，或明确要求全部三个层次时，触发此模式。
如果确实无法判断适用哪种模式，提出一个快速问题而非猜测 —— 建错比提问更浪费时间。大多数情况下可以推断：手头有一个具体任务或提示草稿 → Coaching 模式；启动一个尚无提示词的新项目/功能 → Full setup 模式。

Layer 1: Spec
为何重要
Karpathy 的例子：要求一个前沿模型判断是开车还是步行去 50 米外的洗车店，它说步行 —— 忽略了显而易见的事实：车也得去那里。模型在可验证的任务上表现出色，但在现实世界中的判断决策上却意外地糟糕，因为判断决策正是训练数据中缺失的部分。Spec 的作用是将模型无法自行推断出的判断明确传递给它，使其不必靠猜测填补上下文。浅层的、高层级的“计划模式”式提示无法做到这一点 —— 它太单薄，承载不了真正的理解。
如何构建

找出真实目标，而不仅仅是任务。“写月末报告”是一个任务。目标则是该报告所要支持的决策。如果从 Tom 的表述中不明显，就提问 —— 此处几个快速问题能避免后续更大的返工。
以小检查点推进，而非一次性大块输出。一次性交付全部内容并只在最终结果时再会合，会让偏差悄然累积。将 spec 划分为足够小的部分以便每一步都能检查，尤其在存在真正模糊性的地方。
明确指出不应被假设的内容。Spec 中每个模糊词汇都会变成模型自行填补的假设 —— 且模型会自信地按统计上最可能的方向填补，而不一定是 Tom 真正想要的。应明确指出具体的判断点（命名规范、边界情况、数据冲突时的处理），而不是让其隐含。“标记你正在做出的任何假设，而不是默默选择一个”这样的语句在此处能发挥实际作用。

Spec 应包含的内容
目标（该任务服务的决策/结果，而不仅仅是任务本身）、范围边界（明确包含与不包含的内容）、应被标记而非默默解决的判断点，以及分为“不可协商”与“偏好”的约束条件。

Layer 2: Verifier
为何重要
Karpathy 的观点：这些模型更像“幽灵”而非动物 —— 它们是统计模拟器，而非有动机的智能体。对模型大喊大叫、恳求它或告诉它某事很重要，并不会提升输出质量。真正能提升输出质量的是是否存在可实际检查工作的机制。这也是为什么模型在代码和数学上表现超人（可清晰验证），而在品味和判断上不可靠（缺乏验证依据）—— 因此，某项任务的“完成得好”越明确、越可验证，其输出就越值得信赖，而非只能靠 reviewer 在疲劳中匆匆浏览。
如何构建

在提示词本身中提前设定通过/失败标准，而非事后判断。“让报告看起来好看”不可验证。“报告有三个部分，每个部分以建议结尾”则可以。将标准写成第二个读者（人类或模型）无需读懂 Tom 的心思就能检查的内容。
在成本低廉时，使用第二个模型作为批评者。用不同模型（或同一模型在新上下文中）根据 spec 评估第一个模型的输出，能捕捉到原始运行中会被合理化忽略的问题。
当存在真实的外部信号时，应将其引入。对于代码：它是否真的能部署？测试是否通过？对于非技术性工作：它是否符合已知优秀范例的格式或语气？仅检查内部一致性的验证器，弱于能够对照真实事物进行核对的验证器。

验证器应包含的内容  
具体的、可检查的通过/失败标准（而非主观感受），由谁或什么来进行检查（自我检查、第二个模型、部署/测试信号），以及在失败时采取什么措施（使用何种具体反馈重试，或升级给 Tom）。

第 3 层：环境  
为什么重要  
大多数人每次会话都从零重建上下文——重新解释项目、重复规则，寄希望于代理能记住哪些内容不可触碰。保留聊天历史并不等同于拥有一个真正的环境。相比每次访问都要重新讲解整个车间，一个工具已就位的工作坊要好得多。  
如何构建  

一个代理会自动读取的 CLAUDE.md 文件。内容涵盖：此工作区/仓库的用途、存在的自定义技能及其使用时机、各项资源的位置（知识架构），以及始终适用的规则。这是杠杆效应最高的单一组件，因为它会在每次提示时被读取，而无需 Tom 反复说明。  
一个个人知识库。用于存放结构化、可检索的参考资料，使代理能够直接调用，而非反复推导或产生幻觉。积累的资料构成护城河；良好的检索结构则会随着每次使用而不断增值。  
为任何重复性任务建立可复用的技能。如果 Tom 第二次执行某项操作，就应将其转化为一项技能，而非再次作为一次性任务重新描述。  
在工具层级而非仅在提示词层级强制执行护栏。仅通过提示词声明“未经允许不得修改面向客户的模板”只是一种建议，模型在压力下仍可能违背。若将相同规则设为实际的工具限制（路径封锁、权限闸门），则无法绕过。将规则分为三个层级：

始终执行 — 安全地自动运行，无需询问  
先询问 — 执行前需快速确认  
绝不执行 — 硬性阻止，不仅仅是不鼓励



环境设置应包含的内容  
建议新增的 CLAUDE.md 内容（或若无则提供完整的 CLAUDE.md）、一份简短清单说明哪些内容应纳入知识库而哪些可以省略、值得提取的新技能（如有），以及针对该项目填写完整的护栏层级。

输出格式  
辅导模式输出  
直接在聊天中返回改进后的提示词/指令，并置于易于复制的围栏代码块中。其下方附上一条简短的项目符号说明（最多 3–5 行），指出改动内容及所属层级——足以表明改进并非表面功夫，但不展开讲座式讲解。除非被要求，否则此模式下不要创建文件。  
完整设置模式输出  
使用 create_file 创建三个轻量级文档：

SPEC.md — 目标、范围、需标记的判断点、约束条件  
VERIFIER.md — 通过/失败标准、检查主体、失败后的处理方式  
一个环境部分 — 要么是新的 CLAUDE.md，要么是对 Tom 现有文件的明确标注增补内容，外加填写完整的护栏层级

在撰写这些文档前，请阅读 references/templates.md 以获取完整的填空模板和实例——不要每次都从头自行设计结构。  
将这三个文档一并提交，并附上简要摘要说明每个文档的内容，同时明确标出任何需要 Tom 复核的判断点，切勿替他默默做决定。

根本目的  
不要让上述任何步骤变成制造看似 impressive 文档的事务性工作，而 Tom 对项目的实际理解却依然薄弱。三层结构的目标是确保 Tom 始终是那个清楚项目意义所在、知道“好”是什么样子的人——这些层级只是让他的知识变得足够清晰，以便代理能够可靠地据此行动。如果某个 spec、verifier 或环境文档只是为了填充空间，而非记录 Tom 真正会做出的实际判断，请删去它。
# 验证器：[项目/任务名称]

## 通过/失败标准
[具体且可检查——不能是“看起来不错”或“砍掉表现差的时段”。  
例如：“只有当某小时具备至少 N 条历史线索，且 CPA 超出账户平均水平 X% 以上时，才标记为需降低出价。”]
- [ ] [标准 1]
- [ ] [标准 2]

## 由谁检查
- [ ] 代理根据上述标准自行检查
- [ ] 第二模型批评性复核（使用不同模型或全新上下文，依据规范进行评分）
- [ ] 外部信号：[部署成功 / 测试套件通过 / 与已知良好历史示例匹配]

## 若失败
[如果某项标准未通过，应如何处理——使用何种具体反馈重试，或停止并标记给 Tom 后再继续]

环境 / CLAUDE.md 增补模板
## [项目/功能名称]

**这是什么：** [一到两句话说明]

**相关资源位置：** [文件路径、数据源、相关文档]

**相关技能：** [可复用的现有技能，或“建议新增技能：X”]

**规则：**
- 必须始终执行：[...]
- 必须先询问：[...]
- 绝不允许执行：[...]

实际示例
任务：Tom 要求“为广告系列优化技能添加自动化时段出价调整规则进行需求说明。”

SPEC.md 摘录：

目标：不是“添加一个时段出价功能”——真正目标是在历史转化率较低的时段减少浪费支出，同时不削减那些转化表现尚可、仅因原始数据量少而看似表现差的时段的流量。  
需标记的判断点：对于数据不足两周的新广告系列应如何处理。该需求说明应明确指出，是立即使用类目基准应用时段出价，还是等待积累足够的广告系列专属历史数据，而非让代理自行静默决定。  
检查点：在将规则逻辑实际接入自动应用于真实广告系列之前，需先用一个真实（且已知）账户进行评审。

VERIFIER.md 摘录：

标准：“只有当某小时具备至少 15 条线索历史，且 CPA 超出账户平均水平 25% 以上时，才标记为需降低出价”——可验证，而非“砍掉表现差的时段”。  
检查：在向真实客户建议该规则前，由第二模型批评者使用 2-3 个已知账户复核所提议规则是否存在误报（即仅因流量低而看似表现差、但 CPA 实际正常的时段）。

CLAUDE.md 增补摘录：

必须始终执行：提取并汇总每小时表现数据，标记跨越阈值的时段  
必须先询问：首次将新的时段出价规则应用于真实客户广告系列时  
绝不允许执行：在未通过验证器标准并通过 Tom 签核前，更改客户账户的出价乘数

请注意此示例的实际作用：它并未用通用模板（如“确保高质量”、“遵循最佳实践”）填充文档。每一行都是一项具体决策，若不明确写出，就可能被静默做出且出错。这正是这三个层级共同协作的真实职责所在。

---
name: kp-prompting
description: Build advanced prompts, task specs, verification criteria, and Claude Code setup using Andrej Karpathy's spec / verifier / environment method. Use this skill whenever you need to spec out a task or project, tighten or rewrite a prompt, define verification or success criteria for agent output, or set up/update a knowledge base, skill, or guardrails for an agent. 
---
Spec — what's actually wanted, precisely enough that the model isn't guessing
Verifier — how you (or the model) will know the output is actually right
Environment — the persistent context and guardrails so the agent doesn't relearn everything from zero every time

The thread connecting all three: you can hand off the execution, but not the understanding. Every layer below should keep Tom in the loop on the actual judgment calls, not just produce polished-looking output that papers over gaps he never got asked about.
Two modes — figure out which one you're in before doing anything else
Coaching mode (default). Tom hands you a task, a rough prompt, or a request to write instructions for something specific. Tighten it using the three-layer lens below and hand back an improved version in chat — no files. This is the default for "help me write/improve a prompt for X."
Full setup mode. Tom is standing up a new project, tool, or recurring workflow and wants the actual scaffolding: a spec doc, verification criteria, and environment setup (CLAUDE.md additions, guardrails, knowledge base pointers). Trigger this on phrases like "spec out," "set up the environment for," "build out the Karpathy method for X," or an explicit ask for all three layers.
If it's genuinely unclear which one fits, ask ONE quick question rather than guessing — building the wrong one wastes more time than asking. Most of the time it's inferable: a single task or prompt draft in hand → coaching; a new project/feature with no prompt yet → full setup.

Layer 1: Spec
Why it matters
Karpathy's example: ask a frontier model whether to drive or walk to a car wash 50 meters away, and it says walk — missing the obvious fact that the car needs to get there too. Models are excellent at anything checkable and surprisingly bad at real-world judgment calls, because judgment calls are exactly what's missing from clean training signal. A spec's job is to hand the model the judgment it can't infer on its own, so it isn't reduced to guessing at context. Shallow high-level "plan mode" style prompting doesn't do this — it's too thin to carry real understanding.
How to build one

Find the actual goal, not just the task. "Write the end-of-month report" is a task. The goal is whatever decision that report is supposed to support. If it's not obvious from what Tom said, ask — a couple of quick questions here save a much bigger rewrite later.
Work in small checkpoints, not one big dump. Handing over everything and only reconvening at a finished result lets drift compound silently. Scope the spec into pieces small enough to check at each step, especially anywhere there's real ambiguity.
Be precise about what shouldn't be assumed. Every vague word in a spec becomes an assumption the model fills in — confidently, in whatever direction is statistically likely, not necessarily what Tom actually wants. Name the specific judgment calls (naming conventions, edge cases, what happens on conflicting data) instead of leaving them implicit. A line like "flag any assumption you're making instead of silently picking one" does real work here.

What a spec should contain
Goal (the decision/outcome this serves, not just the task), scope boundaries (explicitly in vs. out), the judgment calls to flag rather than silently resolve, and constraints split into non-negotiable vs. preference.

Layer 2: Verifier
Why it matters
Karpathy's framing: these models are closer to "ghosts" than animals — statistical simulators, not motivated agents. Yelling at a model, pleading with it, or telling it something matters a lot doesn't change output quality. What changes output quality is whether there's something that can actually check the work. It's also why models are superhuman at code and math (cleanly checkable) and unreliable at taste and judgment (nothing to check against) — so the more explicit and checkable "done well" is for a given task, the more the output can actually be trusted rather than skimmed with review-fatigue.
How to build one

Set pass/fail criteria up front, in the prompt itself, not after the fact. "Make the report look good" isn't checkable. "The report has three sections and each ends with a recommendation" is. Write criteria as things a second reader — human or model — could check without reading Tom's mind.
Use a second model as a critic where it's cheap to do. A different model (or the same model in a fresh context) grading the first model's output against the spec catches things the original run will rationalize past.
Pull in real external signal when it exists. For code: does it actually deploy, do the tests pass? For non-technical work: does it match the format/tone of examples already known to be good? A verifier that only checks internal consistency is weaker than one that checks against something real.

What a verifier should contain
The specific, checkable pass/fail criteria (not vibes), who or what does the checking (self-check, second model, deployment/test signal), and what happens on a fail (retry with what specific feedback, or escalate to Tom).

Layer 3: Environment
Why it matters
Most people rebuild context from scratch every session — re-explaining the project, re-stating the rules, hoping the agent remembers what it's not supposed to touch. Keeping chat history around isn't the same as a real environment. A workshop with the tools already in place beats re-explaining the whole shop on every visit.
How to build one

A CLAUDE.md the agent reads automatically. Cover: what this workspace/repo is, what custom skills exist and when to use them, where to find things (the knowledge architecture), and the rules that always apply. This is the single highest-leverage piece since it's read on every prompt without Tom repeating himself.
A personal knowledge base. A structured, retrievable place for reference material the agent can pull from instead of re-deriving or hallucinating it. Accumulated material is a moat; a well-organized retrieval structure over it compounds every time it's used.
Reusable skills for anything repeated. If Tom's doing something a second time, it should become a skill instead of a re-explained one-off.
Guardrails enforced at the tool level, not just the prompt level. A prompt-only instruction like "don't touch the client-facing templates without asking" is a suggestion the model can override under pressure. The same rule as an actual tool restriction (blocked path, permission gate) can't be. Sort rules into three tiers:

Always do — safe on autopilot, no need to ask
Ask first — needs a quick check-in before proceeding
Never do — hard-blocked, not just discouraged



What an environment setup should contain
Proposed CLAUDE.md additions (or a full CLAUDE.md if none exists), a short list of what belongs in the knowledge base vs. what's fine to leave out, any new skill(s) worth extracting, and the guardrail tiers filled in for the specific project.

Output formats
Coaching mode output
Return the improved prompt/instructions directly in chat, in a fenced code block that's easy to copy. Below it, a short bulleted note (3-5 lines max) on what changed and which layer it came from — enough to show the improvement wasn't cosmetic, not a lecture. Don't create files for this mode unless asked.
Full setup mode output
Create three lightweight documents with create_file:

SPEC.md — goal, scope, judgment calls, constraints
VERIFIER.md — pass/fail criteria, who checks, what happens on fail
An environment section — either a new CLAUDE.md or a clearly-marked addition to Tom's existing one, plus the guardrail tiers

Read references/templates.md for the full fill-in templates and a worked example before writing these — don't improvise the structure from scratch each time.
Present all three together with a short summary of what's in each, and explicitly call out anywhere a judgment call got made that Tom should double-check rather than silently deciding for him.

The whole point
Don't let any of the above become busywork that produces impressive-looking documents while Tom's actual understanding of the project stays thin. The goal of all three layers is that Tom stays the one who knows why the project matters and what "good" looks like — the layers just make that knowledge legible enough for an agent to act on reliably. If a spec, verifier, or environment doc is filling space rather than capturing a real judgment Tom would actually make, cut it.
FILE:templates.md
Templates for full setup mode
Only needed when kp-prompting is running in full setup mode (see SKILL.md). Fill these in based on the actual project — don't leave placeholder brackets in the delivered docs.
SPEC.md template
markdown# Spec: [Project/Task Name]

## Goal
[The actual decision or outcome this serves — not just the task description.
E.g. not "add day-parting to the bid logic" but "cut wasted spend during
historically low-conversion hours without also cutting volume during hours
that convert but just look slow at a glance."]

## Scope
**In scope:**
- [...]

**Out of scope (for now):**
- [...]

## Judgment calls to flag, not silently resolve
- [Specific ambiguous point — e.g. "what happens on a campaign with under
  2 weeks of data: apply category benchmarks immediately, or wait for
  campaign-specific data?"]
- [...]

## Constraints
**Non-negotiable:**
- [...]

**Preferences (can be traded off):**
- [...]

## Checkpoints
[If scope is large: 2-4 points where Tom reviews before continuing, rather
than one big handoff at the end]
1. [...]
2. [...]
VERIFIER.md template
markdown# Verifier: [Project/Task Name]

## Pass/fail criteria
[Specific and checkable — not "looks good" or "cut the bad hours."
E.g. "an hour is only flagged for reduced bidding if it has at least N
leads of history and a CPA more than X% above the account average."]
- [ ] [criterion 1]
- [ ] [criterion 2]

## Who checks
- [ ] Self-check by the agent against the criteria above
- [ ] Second-model critic pass (different model or fresh context, grading
      against the spec)
- [ ] External signal: [deployment success / test suite / matches a known-
      good historical example]

## On failure
[What happens if a criterion fails — retry with what specific feedback, or
stop and flag to Tom before proceeding]
Environment / CLAUDE.md addition template
markdown## [Project/Feature Name]

**What this is:** [one or two sentences]

**Where things live:** [file paths, data sources, related docs]

**Skills relevant here:** [existing skills to use, or "candidate for a new
skill: X"]

**Rules:**
- Always do: [...]
- Ask first: [...]
- Never do: [...]

Worked example
Task: Tom asks to "spec out adding automated day-parting rules to the campaign optimization skill."
SPEC.md excerpt:

Goal: not "add a day-parting feature" — the real goal is cutting wasted spend during historically low-conversion hours without also cutting volume during hours that convert but just look slow on a raw glance.
Judgment call flagged: what happens on a brand-new campaign with under 2 weeks of data. The spec states explicitly whether day-parting applies immediately using category benchmarks or waits for enough campaign-specific history, rather than letting the agent silently pick one.
Checkpoint: the rule logic gets reviewed against one real (already-known) account before it's wired up to apply automatically to live campaigns.

VERIFIER.md excerpt:

Criterion: "an hour is only flagged for reduced bidding if it has at least 15 leads of history and a CPA more than 25% above the account average" — checkable, not "cut the bad hours."
Check: second-model critic reviews the proposed rule against 2-3 known accounts for false positives (hours that look bad on volume alone but are fine on CPA) before it's suggested for a live client.

CLAUDE.md addition excerpt:

Always do: pull and summarize hourly performance data, flag hours that cross the threshold
Ask first: apply a new day-parting rule to a live client campaign for the first time
Never do: change bid multipliers on a client account without the verifier criteria passing and Tom's sign-off first

Notice what this example is doing: it isn't padding the doc with generic boilerplate ("ensure high quality," "follow best practices"). Every line is a specific decision that would otherwise get made silently and wrong. That's the actual job of all three layers together.