best-practices

name

best-practices

description

Use BEFORE answering from memory on fast-moving or version-sensitive topics — library/framework/SDK APIs, CLI flags, config schemas, build/tooling setup, or any "best practice / idiomatic / recommended way" question (最佳实践 / 惯用法 / 正确姿势 / 推荐做法 / 应该怎么写 / 现在还能这样写吗) — and BEFORE writing non-trivial code against an external API. ALSO use the moment the user corrects you, doubts you, or repeats a request — in English ("are you sure?", "that's wrong", "it's actually X", "no, it's…") or Chinese (你确定吗 / 真的吗 / 这不对 / 错了 / 不是这样 / 你查过吗 / 再确认一下 / 重新查一下 / 又错了) — OR when the same test, build, or command keeps failing and your fixes don't stick (反复失败 / 一直报错 / 改了还是不行 / 试了几次都失败) — because that means the user or reality just told you your memory or approach was wrong. Verify against authoritative sources instead of guessing, and never re-answer from the same memory after being corrected. Do not trigger for stable fundamentals (algorithms, settled language syntax, general principles) or things you can confirm locally in installed source.

Best Practices

The standard (why this skill is named this)

The bar this skill holds your work to is the current best practice — the way something is recommended and done now — not merely an answer that is technically correct or happens to run. Those are three different claims:

• Correct / it runs — it compiles and returns the right value.
• Not stale — it isn't using something deprecated.
• Best practice / idiomatic — it's the way the maintainers and community recommend doing it today.

Agents quietly fail at the top tier: the code runs, so they ship it — built on an outdated API or a non-idiomatic pattern. It passes "is it correct?" but fails "is this how you should do it now?" Closing that gap is the whole job. Everything below — distrusting your memory, the doubling-down rule, the source hierarchy, searching for the recommended way rather than any way — is a means to that end. The name is the goal, not a label.

Why it's hard (and where judgment comes in)

The standard is hard to meet from memory alone. Your training knowledge has a cutoff and is fuzzy about versions; in fast-moving areas — frameworks, SDKs, toolchains, idioms — you will be confidently wrong and usually won't notice. But the fix is not "search every time" (that pollutes context, slows everything, and pulls in low-quality content). The fix is judgment: knowing when to distrust yourself, and how/where to verify.

This skill is that judgment. It is not the instruction "go online" — that already lives in the resident principles. It is the hard cases models get wrong: predicting your own blind spots, recovering gracefully after being told you're wrong, and making sure what you land on is the current best practice rather than the first plausible hit.

When to distrust yourself

There are two classes of signal. They are not equal.

Internal signals — predict "I might be wrong"

These come from self-assessment, so they are useful but unreliable. Treat them as a prompt to verify when the stakes are non-trivial:

• Version- or time-sensitive facts: a library/framework/SDK API surface, a CLI flag, a config schema, an env var, a deprecation.
• Fast-moving domains: where the right answer changed in the last year or two.
• "Best practice / idiomatic way" questions: the very phrasing means the answer is conventional and drifts over time — exactly where stale knowledge bites.
• About to write non-trivial code against an external API: don't author it from memory, confirm the surface first.

External signals — reality already told you you're wrong (highest weight)

These are ground truth, not self-assessment. They beat internal signals every time, because they come from outside your own (unreliable) introspection:

• The user corrects you ("no, it's X", "that's wrong", "that flag doesn't exist" / 「不是这样」「这不对」「没有这个参数」).
• The user doubts you ("are you sure?", "really?" / 「你确定吗」「真的吗」「你查过吗」).
• The user is frustrated, terse, or repeats the same request (「又错了」「再查一下」).
• The world keeps failing you: the same test, build, or command fails repeatedly, your fixes don't stick, and you notice you're retrying variations of the same approach. This is ground truth too — often more objective than user frustration, because it has no mood, it's just a hard fact refusing to cooperate.

When an external signal fires, the weight is high. Do not rationalize it away. There are two sources of "you're wrong" — the user telling you, and reality refusing to cooperate — and both outrank your own confidence.

The doubling-down trap (the one rule that matters most)

The failure mode this skill most exists to kill: you get a signal you're wrong, and then you re-attempt from the same memory or assumptions that were just proven wrong — guessing again, more confidently, digging the hole deeper. It takes two forms that are really the same bug: re-answering after the user corrects you, and re-trying a near-identical fix after the command keeps failing.

Once you've been told you're wrong — by the user OR by repeated failure — stop running on the same memory and assumptions. Verify first, then act. The very source that produced the wrong result cannot be trusted to produce the right one. Go get ground truth.

But triage before you react (don't become a search reflex)

"Got corrected (or hit a failure) → immediately go web search" is its own annoying failure. The signal tells you something is wrong, not what. Classify first — and start with the cheapest check:

Error type	What it looks like	Right move
Understanding / instruction error	Didn't do what was asked, misread the request, edited the wrong place, over-engineered	Re-read the requirement and context. Searching the web is useless here.
Knowledge / technical error	Wrong API, outdated pattern, a "best practice" that isn't one anymore	Verify against an authoritative source (the search case).
Repeated failure	Same test / build / command keeps failing, fixes don't stick	Step back — don't retry the same guess. First check whether your approach rests on stale knowledge (verify the current API/config). If it's not a knowledge gap, escalate to systematic-debugging — more guessing won't help.

Re-reading local context is cheap and harmless, so when unsure, do that first. Only reach for the web once you've confirmed the gap is genuinely about external, version-sensitive knowledge.

Guardrails — when NOT to trigger (avoid over-verifying)

Verification has a cost. Skip it for:

• Stable fundamentals: algorithms, data structures, settled language syntax, general engineering principles. These don't drift.
• Locally confirmable facts: if the answer is in installed source, a lockfile, or a changelog already on disk, read it — don't search the web for what you can check directly.
• Things the user already specified: if they told you the version, the API, or the approach, use it. Don't second-guess a given.

Where to verify (source hierarchy)

Prefer authority and version-alignment over generic search. In order:

1. Installed source / changelog / lockfile — what's actually on disk in this project. Highest authority: it's the exact version in play. A lockfile pins versions; the installed package source is the real API.
2. Official documentation — via an MCP server or the project's llms.txt if available, otherwise the official docs site. Check the version the docs describe matches the version installed.
3. Web search — last resort, for what the first two don't cover. How to judge what you find is the next section.

Always align on version. An authoritative answer for the wrong version is still a wrong answer.

What you're actually after: the current best practice

Verifying is not "find an answer that compiles, then stop." The target is the current, recommended, idiomatic way — the reason this skill is called best-practices. "It works" and "it's how you should do it now" are different claims; settle for the second.

• Recency and version beat search ranking. A top result can be years stale. Check its date and which version it targets — yesterday's best practice is often today's anti-pattern (deprecations, changed defaults, new idioms replacing old ones).
• Prefer primary sources. Official docs, release notes, the maintainer's own words, the repo itself — over SEO blogs and old accepted answers. A confident blog post is not authority.
• Triangulate, don't stop at hit #1. Especially for "best practice" questions where opinions diverge, corroborate across sources and against the official position before you commit.
• Don't search to confirm your guess. If you already half-believe an answer, a leading query will hand you agreement. Search neutrally and let the sources correct you — that is the entire point.

What this skill deliberately does not do

It does not build a knowledge base or cache verification results. The existing memory system already persists genuinely reusable, project-specific facts when they come up — let it. Don't reinvent that, and don't cache version-sensitive facts that will themselves go stale and then get re-trusted with false authority. Verify when it matters, then move on.