EagleMinds Coding Guidelines for AI Coding Agents
A CLAUDE.md, Claude Code skill, Cursor rule, and AGENTS.md that stop LLM coding agents from guessing, overbuilding, touching code they shouldn't, and saying "done" without running anything. Built from how LLM coding agents fail in practice, turned into rules an agent can follow mid-task, and tested with and without.
Works with Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, OpenCode, Amp, and any agent that reads AGENTS.md.
English | 简体中文
Quick install
Claude Code plugin (adds the eagleminds-guidelines skill and the /eagleminds-review command to every project):
/plugin marketplace add shankar4jazz/eagleminds-coding-guidelines
/plugin install eagleminds-guidelines@eagleminds-coding-guidelines
CLAUDE.md (per project, for Claude Code):
curl -o CLAUDE.md https://raw.githubusercontent.com/shankar4jazz/eagleminds-coding-guidelines/main/CLAUDE.md
AGENTS.md (per project, for Codex, OpenCode, Gemini CLI, Amp, Devin, Jules, and others):
curl -o AGENTS.md https://raw.githubusercontent.com/shankar4jazz/eagleminds-coding-guidelines/main/AGENTS.md
Cursor (project rule, always applied):
mkdir -p .cursor/rules && curl -o .cursor/rules/eagleminds-guidelines.mdc https://raw.githubusercontent.com/shankar4jazz/eagleminds-coding-guidelines/main/.cursor/rules/eagleminds-guidelines.mdc
GitHub Copilot (repository instructions):
mkdir -p .github && curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/shankar4jazz/eagleminds-coding-guidelines/main/.github/copilot-instructions.md
Already have one of these files? Append instead of overwrite (curl ... >> CLAUDE.md). The rules are written to sit alongside project-specific instructions.
What problem does this solve?
LLM coding agents fail in a few predictable ways:
- They guess. Faced with an ambiguous request, they pick a reading, never say which one, and build on it. They don't surface the inconsistency, don't present the tradeoff, and don't push back when the request looks like a mistake.
- They overbuild. A helper grows a config object, an interface, and three options nobody asked for. 1000 lines land where 100 would do, and the dead code stays.
- They touch what they don't understand. A comment gets rewritten, a
sleep() gets removed, imports get reordered, all as side effects of an unrelated task.
- They declare victory early. "Fixed, should work now" on code that was never run, or tests that pass without meeting the requirement.
And one thing they do well: given a concrete success criterion, they loop against it until it passes. Don't tell them how; tell them what "done" looks like.
Naming a failure doesn't stop an agent from committing it. What stops it is a rule it can apply at the moment of temptation: a threshold for when to ask, a list of smells to spot in its own draft, a loop that starts with a failing check, and a reporting standard that makes "should work" unsayable. That's what this repository contains.
The five rules
| Rule | What it prevents |
|---|
| Calibrate first | Full ceremony on a typo fix, or none on a schema change |
| 1. Understand before you build | Silent wrong assumptions, and the opposite failure: interrogating the user instead of reading the code |
| 2. Build the minimum | Speculative abstractions, options nobody asked for, 1000 lines where 100 would do |
| 3. Change only what the task needs | Drive-by reformatting, renames, and deleting code the agent doesn't understand |
| 4. Define done, then loop | "Fixed" without reproducing, tests that pass without meeting the requirement |
| 5. Report what you verified | "Done, should work now" when nothing was run |
Calibrate first. An obvious one-liner gets no ceremony. A standard change gets a one-line assumption, a check, and a short report. Anything ambiguous, large, or hard to undo gets code reading, a plan with a check per step, and tradeoffs surfaced before coding.
Understand before you build. Look, decide, then say. Read the code before asking; most assumptions are answerable from the repo. Restate the task in one sentence. Ask only when the readings lead to materially different work or the action is hard to reverse, otherwise state the assumption and proceed. When you ask, ask one question and recommend an answer. Flag contradictions. Disagree out loud, then defer if the user reaffirms.
Build the minimum. Solve today's problem, with a list of overcomplication smells (options nobody passes, single-implementation interfaces, try/except around code that can't fail, reimplemented stdlib, narrating comments) so the agent recognizes them in its own draft. Simple does not mean thin: reuse existing helpers, keep boundary validation and security checks.
Change only what the task needs. Every changed hunk traces to the request. No reformatting, renaming, type hints, docstrings, or dependency bumps as side effects. Follow the file's style; if the style is harmful, say so rather than copy or silently fix it. Re-read the diff before reporting.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
