DEV Community

Ricards Taujenis
Ricards Taujenis

Posted on

CLAUDE.md & Rules - Before Skills, Hooks, or Agents

#ai #productivity #automation #claude

If you're using Claude Code with open-ended prompts and re-explaining your project every session, you're quietly burning through your Pro usage for nothing. CLAUDE.md and Rules fix that — and they're the foundation everything else (Skills, Hooks, Agents) gets built on top of.

This is part 1 of a 5-part series walking through Claude Code's features in order — CLAUDE.md and Rules first, then Hooks, Skills, MCP, and Subagents, all using the same real project as the example.

The Problem With Open-Ended Prompts

Every time you open a fresh Claude Code session without context, you're paying twice. Once to re-explain your architecture, your conventions, your stack — and again when Claude inevitably guesses wrong on something you already told it last week.

This is the part that's easy to underestimate. It's not just wasted tokens — it's wasted attention. Every paragraph you spend re-establishing "this project uses DDD, Redis is for hot data, Airtable is for history" is a paragraph that isn't moving the actual task forward. Multiply that across every session, every week, and the cost adds up fast — especially on a Pro plan where usage isn't infinite.

Without a persistent source of truth, you're not building a relationship with your codebase. You're starting from zero, every single time. The fix isn't a better prompt. It's not needing to write that prompt at all.

Planning First: Sketching the Rules Before Touching the Repo

Before writing anything into the actual repository, the first real step happened in the Claude Desktop app — not Claude Code. This is worth calling out because it's a genuinely useful pattern, not just a detour.

The idea was simple: rather than improvising a CLAUDE.md prompt cold inside the project, sketch it out in a separate chat first. That conversation surfaced a few specific questions that needed answers before any rule could be written correctly:

  • What does the project use for the backend/API layer? (Go)

  • How should Trading212 data get pulled in? (the public API, if available)

  • What actually triggers the weekly Redis → Airtable migration? (a Fly.io scheduled cron machine)

These aren't trivial details. They directly shape what the rules say — "store snapshots in Redis" is a vague rule, but "move data older than 7 days from Redis into Airtable via a weekly Fly.io cron job, then purge it from Redis" is a rule Claude can actually enforce and verify against.

What CLAUDE.md + Rules Actually Do

CLAUDE.md and .claude/rules/ solve two different problems:

  • CLAUDE.md — the big picture. Project overview, tech stack, architecture, dependency direction. This is what Claude reads to understand what the project is.
  • .claude/rules/ — the enforceable specifics. Coding standards, layer boundaries, naming conventions. This is what Claude reads to understand how to write code for it. The split matters more than it looks. CLAUDE.md is narrative — it reads like documentation, and it's the kind of thing a new human teammate would also want to read. Rules are closer to a linter's config file: terse, specific, and meant to be checked against rather than just read once and absorbed.

Notice the split: .claude/rules/portfolio.md holds the enforceable rules, CLAUDE.md holds the narrative context, and .claudeignore keeps Claude away from .env and other files it has no business touching. The folder structure also shows the DDD layering — domain/, infrastructure/, application/, cmd/, config/ — sitting right alongside the .claude/ directory, which is intentional. The rules aren't bolted on after the fact; they describe the structure that's already there.

The Real Test: Fixing an API Issue

The actual proof a rules-based setup works isn't the first prompt — it's the second one. When an API issue came up mid-build, the fix wasn't to re-explain the whole project again. It was a one-line edit to the rules file itself.

Claude Code was authenticating against Trading212 the wrong way — guessing at a bearer token approach that returned a 401. The fix wasn't a back-and-forth conversation explaining the API again. It was adding a dedicated section to the rules file:

## Trading212 API

- Official docs: https://docs.trading212.com/api
- Base URL: `https://live.trading212.com/api/v0`
- Authentication: HTTP Basic Auth — `Authorization: Basic base64(accessKey:secretKey)`.
  - `TRADING_212_STORAGE_ACCESS_KEY` is the access key (username)
  - `TRADING_212_SECRET_STORAGE_ACCESS_KEY` is the secret key (password)
- Do NOT use a plain bearer token or `Authorization: Bearer` — that is the deprecated approach and returns 401.
- Portfolio positions endpoint: `GET /equity/portfolio`
- Always consult https://docs.trading212.com/api before adding new Trading212 endpoints.
Enter fullscreen mode Exit fullscreen mode

With the official docs link and the correct auth scheme written into the rule, Claude Code referenced the right context immediately and fixed the issue — no re-explaining, no trial and error on a second guess. The rule didn't just patch the bug once; it makes the same mistake structurally impossible to repeat in any future session, because the correct auth method and a link to verify it are now sitting right there in the rules file.

That's the actual payoff. When something breaks — an API quirk, a naming mismatch, a layer violation — the fix is a targeted edit to the rule that's wrong or missing, not a fresh paragraph of context typed into a new prompt. The next session, and every session after that, inherits the fix for free.

Try It Yourself

  • Repo: github.com/Mozes721/PortfolioPulse
  • Video: youtu.be/4BmACot5BF0
  • Claude Code best practices: code.claude.com/docs/en/best-practices Clone the repo, open .claude/rules/portfolio.md, and adapt it to your own stack. The structure transfers even if your project has nothing to do with stocks or Redis. If you want to try the planning-first approach, sketch your own project's data flow in a Claude Desktop or claude.ai chat before writing a single file — the few minutes spent clarifying triggers, sources, and storage boundaries pays off the moment Claude has to write code against them.

What's Next

CLAUDE.md and Rules are the foundation. Next up: Hooks — automating lint fixes, format-on-save, and deploy triggers so Claude isn't just following rules, it's reacting to events in your workflow automatically.

Subscribe or follow along if you want the rest of the series as it drops — Skills, Hooks, MCP, and Subagents, all built on the same PortfolioPulse project.

Top comments (0)