SKILL ISSUE
Welcome to issue #1 of Skill Issue. The premise: when your AI agent disappoints you, it is usually a skill issue. Yours, not the model's. The good news is that skill issues are fixable, and each week we fix exactly one.
This week: the file that stops Claude Code from forgetting who you are every morning.
THE FIX
The 3 lines in CLAUDE.md that do the heavy lifting
Claude Code starts every session knowing nothing about your project. It does not remember yesterday. So people re-explain their stack every morning and wonder why the output keeps drifting. That is hiring a good contractor and refusing to show them the blueprints.
The fix is a file called CLAUDE.md at your project root. Claude Code reads it automatically when a session starts. Most people either leave it empty or stuff it with 400 lines of wishful thinking. Both fail. Anthropic's own guidance says keep it short and prune it hard: if Claude already does something correctly without a rule, delete the rule.
Three lines carry most of the weight.
1. The command line. Tell it how to run and test your project. npm test, make build, pytest -x, whatever you actually use. Without this it guesses, and every wrong guess burns minutes while it reads your package.json like a tourist squinting at a map.
2. The convention line. One sentence on how code should look in your house. "We use functional components, never class components." "All DB access goes through the repository layer." That one sentence kills most of the repeated mistakes.
3. The don't line. The thing it keeps doing that makes you yell at your monitor. "Never touch the migrations folder." "Never add dependencies without asking." Negative rules stick surprisingly well.
Do this right now, it takes under 5 minutes:
Create
CLAUDE.mdin your project root (or run/initand let Claude draft it, then cut it down).Paste the starter below and fill in your specifics.
Next session, watch it stop asking dumb questions.
Once a week, tighten it. Delete rules it no longer needs.
# Project: [name]
## Commands
- Test: `npm test`
- Build: `npm run build`
- Run: `npm run dev`
## Conventions
- [One sentence: the pattern you use, the pattern you avoid]
## Never
- Never [the thing it keeps getting wrong]
- Never add dependencies without askingTen lines. That is the whole file. A bloated CLAUDE.md gets ignored the same way you ignore a 40-page onboarding doc.
QUICK WINS
Three fast ones
Press Esc mid-generation to redirect Claude instead of waiting out an answer you already know is wrong. Interrupt it.
On anything bigger than one file, ask for a plan before code. Plan mode exists so you can review intent before it writes 600 lines in the wrong direction.
End sessions with: "What should I add to CLAUDE.md from this session?" Your config starts writing itself.
FROM THE MINES
Two finds from this week's dig
Two finds from this week's dig through the community:
I gave Claude Code a "lazy senior dev" mode and it writes like 6x less code (r/ClaudeCode, 1,964 upvotes). One persona instruction, six times less code to review. This is the convention line from today's fix taken to its extreme, and it works because less code means less to review.
Anthropic benchmarked "big model orchestrates, cheap models execute": 96% of the performance at 46% of the cost (r/ClaudeAI, 1,011 upvotes). If your bill hurts, let the expensive model plan and the cheap ones type. You can set this up in Claude Code today.
SKILL CHECK
Your turn
Reply with the worst thing your AI assistant did this week.
Deleted the wrong folder, "fixed" the tests by deleting them, wrote an apology essay instead of code, whatever you have. Best (worst?) story gets featured next issue, anonymized.
I read every reply.
Talk soon,
KhangNY
"Skill Issue is written by a human wrangling AI agents, with AI help. Every tip is tested before it ships. Not affiliated with Anthropic."