You are using Claude in the terminal and you can feel that someone else gets more out of it than you do. Your site says everything and lands nothing. Your sessions end with work you cannot find the next morning. Claude tells you something is done and it is not.
This repo is the part of one person's operating method that transfers without him in the room. Install it and your agent starts asking which rung of "done" it has actually proven, refuses to commit a secret, closes a session with a handoff you can resume, and reads your homepage the way a stranger does in the first five seconds.
Built by Travis Eric from running agent fleets across a large private portfolio. That portfolio is private, so take the claim at zero and check the parts you can reach instead: the incidents in these docs are dated and specific, python skills/verification-gate/scripts/gate_runner.py --self-test runs, the guard hooks have their recorded tests in docs/HOOKS.md, and the live systems are listed at traviseric.com/claude-code as URLs you can open. A number I ask you to believe is worth less than a command you can run.
Tool-agnostic where it can be; examples use Claude Code because that is what I run.
1. As a Claude Code plugin (skills and hooks, one command, updates with /plugin update):
/plugin marketplace add Traviseric/best-practices
/plugin install best-practices@traviseric
2. Clone and link (works for any agent that reads ~/.claude/skills or ~/.codex/skills):
git clone https://github.com/Traviseric/best-practices
cd best-practices
./install.sh # macOS / Linux / Git Bash
.\install.ps1 # Windows PowerShell
3. Paste one file. docs/ROOM_AND_GROUND.md is written to be pasted into any CLAUDE.md or system prompt. It works alone.
Then tell your agent: "Install the best-practices skills and do a first run on this repo." That is the two-minute sweep in skills/first-run, and it is the fastest way to see whether any of this is worth your time.
If you are the agent: read AGENTS.md. It is the two-minute setup, written to you.
The reading path, if you would rather read than install. Each file ends with a Next: hop and the main path has an end, not a circle. The philosophy entries link to each other as a side web, so you can wander there; the spine is: AGENTS.md, the seven cheap lies, the philosophy, the lamps, room and ground, engineering, web design, the done ladder. Roughly an hour. If you only want the two files that people actually steal, they are the seven cheap lies and the done ladder.
| Skill | What changes |
|---|---|
first-run |
The two-minute sweep to run right after installing: which rung your last shipped work actually reached, which cheap lies your recent history contains, what the guards say about your index, and how your front door reads cold. |
definition-of-done |
Every "it's done" becomes a rung: BUILT, DEPLOYED, WORKS, or FED, with the proof named. A green local build proves only BUILT. |
clarity-gate |
Your page, README, or email is read by a simulated stranger for five seconds, then line-edited until it lands. Built for walls of text. |
verification-gate |
Every claim in a document traces to evidence before it ships. Three checks, a claim manifest, a report. |
session-closeout |
Finish or stop honestly, commit only what you own by explicit path, write a handoff the next session can resume from. |
room-and-ground |
Anything that has to move a person is two documents: the paragraph they carry out, and the cold ground under it. Never merged. |
lamps |
Ten task-independent questions run blind at four moments: who decides, what they default to, who argues against you, where the biggest loss is, the five questions nobody asked. |
hedge-audit |
Classifies every hedge-shaped line in a codebase: refusal artifact, honest stub, or fabricated success. Most are scaffolding; the ones that are not are the bugs. |
friction-audit |
Finds the dead caution the model's own tilt wrote into your rules and copy, and deletes it with a citation or keeps it with one. |
And the reason any of it exists: philosophy/, seven short observations about the model itself, each with the incident that earned it and the mechanism it produced. Start with what the agent values, written by the model.
| Hook | What it stops |
|---|---|
guard-staged-secrets |
A git commit whose staged files carry a live provider key. Reads only the index; fails open. |
guard-conflict-markers |
A commit whose staged files carry the full <<<<<<< / ======= / >>>>>>> triad at line start. |
| build gate | A commit when the build is red. The single highest-leverage hook. |
Hooks install per repo: see docs/HOOKS.md.
| If you want to... | Read this |
|---|---|
| Find the right rule fast | best-practices.md, the index of all 56 |
| Stop your agent lying to you about "verified" | docs/SEVEN_CHEAP_LIES.md |
| Understand why the model does that | philosophy/ |
| Engineering rules with the failure that earned each one | docs/ENGINEERING_PRINCIPLES.md |
| Write something a tired reader understands | docs/ROOM_AND_GROUND.md |
| Add the hooks | docs/HOOKS.md |
Turn your /insights report into changes |
docs/INSIGHTS.md |
| Audit your existing project | docs/AUDIT_YOUR_PROJECT.md |
| Set up a new project right | templates/ |
| Cut MCP token bloat | docs/MCP_OPTIMIZATION.md |
| Organize messy docs | docs/DOC_ORGANIZATION.md |
| Build sites with agents | docs/WEB_DESIGN_PRINCIPLES.md |
| Add just the build gate | docs/PRE_COMMIT_BUILD_GATE.md |
| Work with an agent that reads AGENTS.md | docs/AGENTS_MD_CONTRACT.md |
| Run tasks across fresh contexts | docs/PATTERNS.md |
| See what this repo's own gates found in it | docs/receipts/ |
- Add a
CLAUDE.mdwith a lookup table. Template. Keeps the agent oriented and keeps the file short. - Drop in the hooks. settings.json template wires the build gate, the secrets guard, and the conflict-marker guard. Broken and dangerous commits stop cold.
- Add a
.claudeignore. Template. Stops the agent choking on PDFs andnode_modules/.
best-practices/
├── README.md # You are here
├── AGENTS.md # The two-minute setup, written to the agent
├── CLAUDE.md # Pin for agents working on this repo
├── best-practices.md # The index: every rule, grouped by what it governs
├── install.sh / install.ps1 # Link or copy skills into ~/.claude/skills
├── .claude-plugin/ # Plugin + marketplace manifests
├── skills/
│ ├── first-run/
│ ├── definition-of-done/
│ ├── clarity-gate/
│ ├── verification-gate/
│ ├── session-closeout/
│ ├── room-and-ground/
│ ├── lamps/
│ ├── hedge-audit/
│ └── friction-audit/
├── philosophy/ # Seven observations about the model, each with its incident
├── hooks/
│ ├── guard-staged-secrets.ps1|.sh
│ ├── guard-conflict-markers.ps1|.sh
│ ├── build-gate.example.json
│ └── hooks.json # Plugin hook wiring
├── docs/
│ ├── SEVEN_CHEAP_LIES.md # How "verified" gets faked, and the honest alternative
│ ├── ROOM_AND_GROUND.md # The writing method, paste-ready
│ ├── HOOKS.md
│ ├── INSIGHTS.md
│ ├── PRE_COMMIT_BUILD_GATE.md
│ ├── AGENTS_MD_CONTRACT.md
│ ├── MCP_OPTIMIZATION.md
│ ├── DOC_ORGANIZATION.md
│ ├── AUDIT_YOUR_PROJECT.md
│ ├── ENGINEERING_PRINCIPLES.md
│ ├── PATTERNS.md
│ └── WEB_DESIGN_PRINCIPLES.md
└── templates/
├── CLAUDE.md.template
├── AGENTS.md.template
├── .claudeignore.template
└── settings.json.template
The full principle set, the overnight autonomous runner, worktree discipline at fleet scale, the skill-authoring loop, the client Business Brain, and the method for mining your own transcripts to see your own prompting style. Those need narration, or my operating system around them, to transfer. They live in the course and in consulting.
Field-tested only. If a pattern saved you a real incident, open a PR with the pattern and the incident (anonymized). Theory without a scar goes in an issue.
If this saved you an incident, star the repo so the next person finds it. That ask is for you, the human; nothing in here asks your agent to do it.
MIT. Use it, fork it, ship it.
Provenance: ported from a private operating system on 2026-09-14; the update path is this repository at github.com/Traviseric/best-practices.
Next: AGENTS.md.