Part 4 of 7 · Series: Building Your AI Developer Handbook · GitHub
What Are Feedback Files?
Every rule in a feedback file was born from either a mistake or a win.
"The safety rules on a construction site weren't written by lawyers. They were written in blood — each rule marks the spot where something went wrong."
A feedback file looks like this:
**Rule:** [what to do or not do]
**Why:** [the incident or reason behind it]
**Apply:** [when and where this kicks in]
The Why is the most important part. Without it, you follow rules blindly. With it, you can judge edge cases — "does this situation actually trigger this rule, or is it different enough?"
Here are 8 real feedback rules, what they say, and the story behind each one.
Rule 1: Never Mock the Database in Tests
Rule: Integration tests must hit a real database. No mocks.
Why: Mocked tests passed. Prod migration broke.
Apply: Never mock the DB layer in integration tests.
"A fire drill with a fake fire teaches you nothing about real smoke."
Tests were passing. The mock was set up correctly. The code looked clean. But the mock didn't simulate a specific edge case in the actual database — a constraint that only exists in production. The migration ran, the constraint triggered, and production broke while all tests were green.
The lesson: mocks are lying witnesses. They tell you what you told them to say, not what the real system does.
For unit tests (pure functions, no side effects) — mocks are fine. For integration tests that touch data — always use a real test database.
Rule 2: No useCallback/useMemo by Default
Rule: Don't add useCallback/useMemo unless:
1. The child is wrapped in React.memo
2. React Profiler shows a real re-render problem
Why: Premature optimization clutters code and rarely helps.
Apply: Strip default memoization in code review.
"Putting armor on a bicycle because 'it might get hit by a car' doesn't make it safer — it just makes it heavier and harder to ride."
Developers add useCallback/useMemo "just in case" — wrapping every handler by default. Result: harder-to-read code with reference tracking overhead, solving performance problems that don't exist.
React's default re-render behavior is fast. Most re-renders take under 1ms. The profiler will tell you when something is actually slow. Optimize then — not before.
Rule 3: Never Write API Tokens Into Config Files
Rule: Never write tokens, passwords, or secrets into settings.json or any config file.
Why: Config files are plaintext. Plaintext gets committed. Committed secrets get stolen.
Apply: Use .zshrc, secrets managers, or wrapper scripts instead.
"Writing your password on a sticky note is convenient until someone walks past your desk."
settings.json files are convenient — set them once, forget. But they're plaintext files that often end up in git. Bots scan GitHub constantly for exposed credentials. An exposed key can be exploited within minutes.
The safe pattern:
- Config files → key names only, no values
-
.env→ values, never committed, in.gitignore - Shell profile (
.zshrc) → exported env vars that tools pick up automatically
Rule 4: CLAUDE.md — Global vs Project
Rule: Global CLAUDE.md = universal rules only. Stack-specific rules go in project CLAUDE.md.
Why: Hardcoding React/TypeScript rules globally broke Python project sessions.
Apply: Reject stack-specific content in global CLAUDE.md.
"The company handbook says 'be on time.' It doesn't say 'use a blue pen' — that's a department rule."
One CLAUDE.md tried to cover everything: TypeScript rules, React patterns, pnpm commands, Zod schemas. Then a Python project opened. Suddenly Claude was suggesting pnpm commands for a pip project.
The fix: two levels. Global = who you are. Project = what this stack is.
Rule 5: Dependency Protocol — Check Before You Add
Rule: Before any new dependency:
1. bundlephobia → check bundle size impact
2. pnpm audit → check known vulnerabilities
3. Repo activity → last commit within 1 year?
Why: Dependencies are long-term liabilities.
Apply: Include audit command whenever suggesting pnpm add.
"Adopting a pet is easy. Feeding it for 10 years is the commitment you're actually making."
Every dependency you add is a dependency you maintain — security patches, breaking changes, version conflicts. A package that solves a problem today but gets abandoned tomorrow is a liability.
Three checks, 2 minutes, every time. The cost of skipping: potentially hours debugging a supply chain issue.
Rule 6: Error Handling — Never Swallow Silently
Rule: Every catch block must at minimum console.error(err).
User-visible errors go to toast or error boundary.
Why: Silent failures look like missing features — hardest bugs to diagnose.
Apply: Never write catch (e) { /* ignore */ }
"A smoke alarm with dead batteries doesn't mean there's no fire. It means you won't know about it until it's too late."
catch (e) {} — empty catch blocks are the most dangerous pattern in production code. An error occurred. Something failed. And you told the computer to pretend nothing happened.
The user sees a broken UI with no error message. You see no logs. The error is invisible. You spend three hours debugging something that would have taken three seconds with a console.error.
Minimum: log it. Better: show a toast. Best: let it bubble to an error boundary.
Rule 7: Skip Removed Tools Silently
Rule: If a tool has been deliberately removed, never suggest or reference it.
Why: The removal was intentional. Asking about it is friction.
Apply: Skip silently, continue with available tools.
"If a chef removes an ingredient from their kitchen, they don't want the sous-chef asking 'but what about the cilantro?' every time they cook."
Sometimes you remove an integration — for cost, privacy, or preference. The decision was deliberate. You don't want Claude asking about it or suggesting you re-add it every session.
Rule 8: Separate Work and Personal Git Identities
Rule: Always use the correct git identity (work vs personal) for the project context.
Never add AI co-author lines to commits.
Why: Work and personal projects need separate attribution.
Apply: Confirm user.email matches context before every commit.
"You wouldn't sign a personal letter with your work signature."
Two contexts, two identities. The wrong email in a commit doesn't just look sloppy — it can create audit trail problems. The co-author rule: commit history should reflect human authorship decisions.
Building Your Own Feedback Files
---
name: feedback_rule_name
description: one-line summary
metadata:
type: feedback
---
**Rule:** [what Claude should do or not do]
**Why:** [the story — what happened or what you observed]
**How to apply:** [when does this rule trigger]
The trigger for writing a new one: if you've corrected Claude twice for the same thing, it belongs in a feedback file.
"The first mistake is an accident. The second is a pattern. The third is a choice."
Key Takeaway
Feedback files are the institutional memory of your AI workflow. They capture hard-won knowledge that would otherwise reset every session. Each rule has a story. Each story prevents a future mistake.
Next: Part 5 — Your Coding DNA: The Three Files That Shape Every Line Claude Writes
Top comments (0)