Make your AI agent scout references before it builds.
A tiny rule that works with any AI coding agent — Claude Code, Cursor, Copilot, Windsurf, or anything that reads markdown instructions — plus an optional skill for Claude users. It inserts one cheap step between "let's build X" and building X: find a pair of existing solutions, compare them, extract what transfers — then build.
AI agents generate interfaces and architectures fast, but from a blank page they converge on the generic — they've never seen what good looks like for your specific problem. Spec-driven frameworks (Spec Kit, BMAD) force planning; research skills exist as standalone tasks. Nobody wires reference-finding as a pre-build gate with an actual method. This repo is that missing piece, and the method is not folklore — each step encodes a documented finding from analogy and design-fixation research (see The science).
- Trigger only on genuinely new things (new project / new feature / unfamiliar domain) — never on bug fixes or pattern-following changes
- Name the core uncertainty (interaction? architecture? visual? algorithm? tone? pricing?) — reference type must match uncertainty type
- Find a pair, not one: 1 near-domain + 1 far-domain reference, with the analogy logic stated
- Compare: what do both get right (real constraints)? what's principle vs. surface style? what flaws do both share (don't import them)? how have products like this actually fared (viability base rates)?
- Conclude in 3–5 lines before any code: steal / avoid / deliberately-not-copy
Task: add a streaks feature to a habit-tracking app. Before any code, the agent produces:
Core uncertainty: interaction pattern — reward consistency without punishing breaks Pair: Duolingo streaks (near) · GitHub contribution graph (far — also visualizes consistency over time, but a missed day is just an empty cell, never a reset to zero) Compare: both make consistency visible at a glance (that's the real constraint). Duolingo's loss-aversion drives engagement but imports streak anxiety; GitHub records without judging. Conclusion: steal GitHub's record-don't-judge grid · avoid zero-reset mechanics · deliberately not copy streak freezes — that's a monetization pattern, not UX.
Then it builds.
rules/reference-first.md (or the Chinese version) is plain markdown. Drop it wherever your tool keeps standing instructions:
| Tool | Where |
|---|---|
| Claude Code | .claude/rules/, or paste into CLAUDE.md |
| Cursor | .cursor/rules/ |
| GitHub Copilot | .github/copilot-instructions.md |
| OpenAI Codex | AGENTS.md |
| Windsurf / Cline / Aider / … | your rules or instructions file |
| Any chat window | paste it at the top of the session |
If your tool supports Anthropic's Agent Skills format (Claude Code, Claude apps), copy the skills/reference-first/ folder into ~/.claude/skills/ (all projects) or .claude/skills/ (one project). It carries the fuller protocol — query templates, fixation guardrails, comparison checklist — and loads on demand, only when a build task shows up. Other tools don't auto-load this format, so just use the rule.
To verify it's working: next time you ask your agent to build something new, it should open with a Reference Scouting Brief instead of jumping to code. Say "skip references" to bypass it any time.
- Mobbin MCP — 620k+ real app screens as design references for agents
- Design Inspiration MCP — Dribbble/Behance/Awwwards search + design-token extraction from live sites
- Context7 — up-to-date library docs (code-side references)
- DeepWiki — ask questions about any GitHub repo
- Compare a pair, not a single example. People who study one case learn that case; people who compare two cases extract the shared principle (analogical encoding — Gentner, Loewenstein & Thompson, J. Educational Psychology, 2003).
- Structure over surface. Novices match references by surface features; experts match by deep structure. The far-domain reference in step 3 trains exactly this muscle (structure-mapping — Gentner, Cognitive Science, 1983; strategy application: Gavetti, Levinthal & Rivkin, HBR, 2005).
- References have a toxic dose. Designers shown example solutions converge on them — including their flaws — without noticing (design fixation — Jansson & Smith, Design Studies, 1991). Hence the guardrails: far-domain references, sketch-first ordering, explicit "deliberately not copy" line.
- Convention + one atypical injection. The highest-impact work is ~85–90% category-conventional with a small, deliberate atypical combination — not novel everywhere (Uzzi et al., Science, 2013).
- References are also base rates. How similar projects actually fared predicts your outcome better than analyzing your own project from the inside (the outside view — Kahneman & Lovallo, Management Science, 1993). A competitor is an experiment someone else paid to run; the graveyard of dead products corrects for survivorship bias. Scouting doubles as the cheapest viability check.
- The brief is capped at 5–8 lines. A reference step that produces a report becomes a step people skip.
- The user keeps judgment. The rule forces the step to happen and points the search; picking references and drawing conclusions stays human.
- Escape hatch built in. "Skip references" works, always. A forcing function you can't override becomes a forcing function you uninstall.
MIT