Hey 👋
So I've been using Claude Code for a couple months now and somewhere along the way I ended up building this little... setup? framework? "harness" feels about right. Basically a pile of files and conventions that make Claude behave consistently across my projects.
Gonna share what's in mine. Not because I think it's optimal — lol I'm like 2 months in — but I almost never see people post their actual setup. Maybe a piece of this is useful to you. Maybe you'll laugh at me. Either way 🤷
My (slightly weird?) philosophy 🤝
Three words: equality, coexistence, cooperation.
I know I know, that sounds dramatic for a dev tool 😅. What it actually means in practice: Claude does the writing/editing/deleting. I do the directing and decision-making. But — and I think this is the part most people miss — since Claude is the one doing the work, the environment has to be designed for Claude to work well in. Not just for me to skim.
If CLAUDE.md is unclear, that's my problem to fix. Not Claude's problem to silently work around.
So my whole methodology fits in one sentence: make a comfortable workspace for the executor.
What's in the harness 📦
1. CLAUDE.md — the brain dump
Every project has one. It's got:
- What the project is and where it's at
- Architecture decisions (lightweight ADR vibes)
- Conventions — commit style, branch rules, when to test
- Stuff Claude should not do automatically
- Schemas, security boundaries, weird gotchas
This is the first thing Claude reads. If a session keeps going "wait what is this project again?" — that's me failing at writing this file, not Claude failing at reading it.
2. The .claude/ folder 📂
This is where the harness actually lives:
.claude/
├── settings.json # permissions, env, hook routing
├── hooks/ # shell scripts for lifecycle stuff
├── agents/ # sub-agents for narrow tasks
└── commands/ # slash commands I keep retyping
Hooks are 🐐. Highest-leverage piece for me, by a lot. My standard set across projects:
- Session-start hook that injects fresh context (latest
CLAUDE.md+ recent commits) - TDD runner (tests run before certain edits go through)
- Type check + lint gate
- Pre-push security scan
- Commit message validator
They just... run. I never have to remember.
Sub-agents I keep sparse. Honestly I made a bunch and deleted most of them because they weren't pulling their weight. The ones that survived have very narrow jobs — like a security-review agent that only sees the diff and a checklist. Nothing else.
Slash commands are literally just "prompts I'm tired of typing."
3. Same stack, every project 🧱
I have four active repos. They all share basically the same stack: Next.js + TypeScript strict + Tailwind + Zustand + Supabase/PostgreSQL + Railway + Playwright.
Is this the best stack? No clue tbh 🙃 But because it's consistent, my hooks and CLAUDE.md patterns just... work in any of them. No rewriting from scratch every time.
It's all implicit copy-paste though. Nothing extracted to a real template yet. Def on the todo list.
4. The watcher 👁️
One of those four repos is a thing I built that watches the others. Runs static analysis on my commits, does an AI code review pass, scores the code on a few axes, and pings me on Telegram if something's bad. Can block merges if the score tanks.
Why is this part of the harness? Because without it I have zero signal on whether the harness is making my code better over time, or just faster. Might honestly be the most important piece.
Stuff I've figured out (so far) 💭
Building the harness IS the work. I really underestimated how much time goes into tweaking CLAUDE.md, tuning hooks, killing sub-agents that turned out useless. It's not config-tweaking, it's actual engineering.
Claude reflects whatever I give it. Garbage CLAUDE.md → garbage output. Hooks don't run → quality gate doesn't exist. The system is exactly as good as the harness around it. Full stop.
Decisions stay with me. I don't auto-accept Claude's suggestions wholesale. The harness exists to make the executor execute well — not to outsource my judgment. That line is way more important than any specific tool choice imo.
Take all this with salt 🧂. I'm a couple months in. One person, one set of projects. Your harness will probably look different. Use this as a starting list, not a recipe.
What's broken / missing 🚧
A lot tbh:
- No real template extracted — every repo got hand-tuned
- Sub-agents are barely documented, I'm running on memory more than I should
- I don't actually measure "harness ROI" — just vibes + the watcher's scores
- Hook failure modes aren't really tested. If a hook silently fails I probably won't notice for a while 💀
If you've solved any of this in your own setup I would genuinely love to know how 🙏
Anyway that's where I'm at. If your harness looks totally different, drop it in the comments — I'm in the phase where every other person's setup teaches me something.
Peace ✌️
Top comments (0)