Forem: Mateusz Dembek

CLAUDE.md - how to set up project instructions for Claude Code

Mateusz Dembek — Sat, 28 Feb 2026 11:18:12 +0000

My CLAUDE.md is 216 lines long. It references 13 separate rule files. It has a section called "How to Work With Mateusz" that includes gems like "Do not soften truth" and "When he says change X, change exactly X. Not Y. Not X and also improved Z. Just X."

I also have a file called lessons-learned.md where Claude automatically logs every mistake it makes. There are 20+ entries. One of them is about a hover color where Claude guessed #404040 instead of looking up the actual token. The real value was #737373. Darker instead of lighter. Claude was too lazy to check, and I was too trusting to notice until it looked wrong.

This is what happens when you take CLAUDE.md seriously. You end up building a relationship with a tool that forgets you exist every time you close the terminal.

The week the internet said to delete it

A study from ETH Zurich tested four coding agents on hundreds of real tasks. With instruction files and without.

/init makes things worse. Agents using auto-generated files solved fewer problems and cost 20% more. The generated content just repeated what the agent could already see by reading the code. You're paying Claude to read the same information twice.

Human-written files improved results by about 4%, but also cost more tokens. That 4% only happens if the file contains things Claude wouldn't figure out on its own.

Theo Browne tweeted "delete your CLAUDE.md" to half a million people. Addy Osmani wrote that you should stop using /init. Reddit piled on. For about 48 hours, instruction files were dead.

Nobody talked about what the study tested. They ran auto-generated boilerplate against coding benchmarks on unfamiliar projects. No lessons-learned file. No workflow rules. No "scan every hover state before writing CSS" born from Claude guessing a color wrong. They tested the worst version of these files and found it doesn't work. That's what happens when you write too much, too vague, and for problems you don't have yet.

Vercel tested the opposite. They put documentation for APIs that didn't exist during training into an instruction file. Pass rate went from 53% to 100%. When the file contains things the agent can't discover on its own, it works.

If your CLAUDE.md repeats what's in package.json and your folder structure, delete it. If it contains your preferences, your conventions, and the mistakes Claude made last week, keep it.

What is CLAUDE.md

It's a text file in your project. Claude reads it at the start of every session. Whatever you write there becomes part of how it thinks about your code.

I have terrible memory. Names, conversations, where I left things. So when I say Claude forgets everything the moment you close the terminal, I mean I get it on a personal level. The difference is I can drink coffee. Claude just gets a fresh CLAUDE.md.

Without it, every session starts with Claude poking around your files trying to figure out what's going on. With it, Claude starts with the right context: what matters, what to avoid, how you want things done. Instead of six rounds of "no, not like that," you get two.

Where to put it

I didn't know this at first, but Claude reads instructions from two places.

There's a personal file at ~/.claude/CLAUDE.md. Whatever you put there applies to every project you open. I use mine for coding philosophy, commit conventions, which AI models to use for which tasks. The stuff that's true regardless of what I'm building. Things like "no emojis in code" and "always use conventional commits" go here because I want them everywhere.

Then there's the project file. Drop a CLAUDE.md in your main project folder (or inside .claude/ if you want a cleaner root). This one is for the team. Commit it. Everyone who opens the project gets the same instructions. This blog has one that says "Lighthouse target: 100/100/100/100. 99 is not acceptable." My other projects have completely different rules.

The two layers stack. Personal preferences load first, project rules load on top. If they disagree, the project wins. Your preference is yours, but the project has the final word.

There's also CLAUDE.local.md for stuff you don't want to commit. Local dev URLs, test credentials, personal shortcuts. It gets gitignored automatically.

I discovered the layering by accident. I kept copy-pasting the same rules into every project's CLAUDE.md. Then I realized the personal file existed and moved all the shared stuff there. Now I write my preferences once and they follow me everywhere. Project-specific stuff stays project-specific. No more duplicate rules drifting out of sync.

What to put in it

Start with whatever you keep repeating. If you've told Claude the same thing three sessions in a row, that thing belongs in CLAUDE.md.

The fastest way is just telling Claude what to remember:

add to CLAUDE.md that this is an Astro 5 blog with MDX,
Tailwind CSS 4, deployed on Vercel

Claude writes the entry for you. You don't have to think about formatting or structure. Next time you correct something:

add to CLAUDE.md: always use conventional commits.
feat: for features, fix: for bugs, refactor: for cleanup

And when you catch Claude doing something wrong:

add a rule to CLAUDE.md: no emojis in code or content.
also add: Lighthouse target is 100/100/100/100, 99 is not acceptable

The file writes itself from your corrections. Every time Claude does something you don't like, you tell it to remember. After a few sessions, you have a CLAUDE.md that reflects how you work. Not a template you copied from someone's blog post.

You can also put in architecture notes, folder structure, how things connect. I'd wait. Add those when Claude gets confused about where something lives. If it never gets confused, you saved yourself the context cost.

Let Claude write the first draft

If you want a starting point, Claude Code has a command:

/init

It scans your project and generates a CLAUDE.md based on what it finds. As I mentioned above, the ETH Zurich study found this actually makes things worse. /init writes down things Claude can already see by reading your code. Your folder structure, your tech stack, your build commands. Claude reads the same facts twice and you pay for both.

If you use /init, gut it. Delete everything Claude can figure out on its own. What survives is probably two paragraphs. Or skip it entirely and build the file from corrections, like I described above.

Splitting rules into separate files

One file works fine until it doesn't. My CLAUDE.md hit maybe 400 lines and I noticed Claude was ignoring stuff near the bottom. Rules I'd written carefully were having zero effect. So I told it:

split CLAUDE.md into separate rule files under .claude/rules/

My personal ~/.claude/rules/ directory has 13 files. There's bulletproof.md with platform-specific coding rules for React, React Native, and Swift. There's security.md that blocks Claude from committing API keys (I wrote about why that matters). There's anti-drift.md that prevents AI agents from going off-script during complex tasks. And there's lessons-learned.md, which is basically a diary of Claude's failures.

You don't need 13 files. You probably need two or three. But knowing you can split things up means you won't end up with one massive file that's impossible to maintain.

Claude doesn't read like you do. It pays the most attention to the beginning and end of its context, and the least to the middle. Long files mean rules get lost in that dead zone. Shorter, focused files mean every rule lands.

The lessons-learned file

I have a file called lessons-learned.md with a simple rule at the top: every time Claude makes a mistake, it has to log it. Automatically. No asking. The format is strict: date, project, what went wrong, why, what was fixed, and a new rule to prevent it from happening again.

A real entry from the file:

### [2026-02-19] NEVER guess CSS values - scan tokens from Design System
- Project: Shift
- Error: Hover on Button/Secondary set to #404040 (darker than default #525252).
  Correct hover is #737373 (lighter). I guessed instead of reading tokens
- Cause: Laziness. Didn't query Figma API for hover variant. Made up #404040
- Fix: Read tokens. Applied correct values
- Rule: BEFORE writing ANY CSS value for a DS component, scan ALL states.
  NEVER guess hover/focus/active values. ALWAYS scan

Claude literally wrote "Cause: Laziness" about itself. And that new rule at the bottom? It gets checked before every coding session. So the next time Claude works with design tokens, it reads that entry first and knows not to guess.

After 20 entries, I review them. Patterns that keep repeating get promoted to permanent rules in bulletproof.md. The rest stay as a reference. So it gets better over time. Not on its own. Because I built the system that forces it. The downside? All those rules and self-checks mean Claude burns through tokens the way I burn through creatine. Every session starts with it reading its own diary before it even looks at my code.

Other things worth knowing

There's a feature where rules only apply to specific files. You put a paths field in the frontmatter and the rule kicks in only when Claude touches matching files. I don't use it much, but if your frontend and backend have different conventions, it's useful. CLAUDE.md also supports @ imports for pulling content from other files into your instructions. The official docs cover the syntax for both.

Auto memory is separate. You can just say:

remember that we use pnpm, not npm

Claude saves it to a memory file that loads every session. For this blog, Claude's auto memory includes things like the background color change from pure black to #121212, why it was changed, and that every heading uses a specific CSS variable. Small things I'd otherwise repeat every session. Run /memory to see what it's saved and fix anything wrong or outdated.

All of this eats context. Everything in CLAUDE.md, every rule file, every memory entry takes up space in the same window Claude needs for reading your code, thinking, and generating a response. My setup loads around 200 lines of CLAUDE.md plus 13 rule files. That's a lot of tokens burned before Claude even looks at what I'm building. On a Max plan, I notice it. Sessions with large files get slower. Complex refactors hit the ceiling faster.

A hundred well-chosen lines beat three hundred generic ones. If a rule doesn't save you time at least once a week, it probably doesn't belong there. I've pruned mine twice already and I'll do it again. The official documentation covers the technical details if you want the full picture.

The mistakes I made

Too much too soon. My first CLAUDE.md was 400 lines of everything I could think of. Claude read all of it but most of it was noise. Whatever you keep repeating to Claude belongs in CLAUDE.md. Everything else was wasting context.

Too vague. "Use 2-space indentation, no semicolons, prefer const over let" is useful. "Write clean code" is not. Be specific or don't bother.

Never updating it. Projects change. CLAUDE.md doesn't update itself. And then you sit there debugging rules you wrote two months ago wondering why Claude keeps doing something you stopped wanting.

Putting secrets in it. Don't. No API keys, no passwords, no connection strings. CLAUDE.md is a text file. If you commit it (and you should for team projects), everyone sees it. Use environment variables for secrets.

Writing rules for problems I didn't have yet. I added error handling rules before I'd encountered a single error. Accessibility rules before I had a single clickable button on the page. Those rules sat there eating context for weeks before they became relevant. Write rules when you need them, not when you think you might need them someday. This is the hardest one to follow because it feels productive to write rules. It's not.

Start small, then let it grow from pain

Create a CLAUDE.md in your main project folder. Put in your stack, your main commands, and three conventions you care about.

Then pay attention. The next time you catch yourself explaining the same thing to Claude twice, stop explaining and write it down instead. Your CLAUDE.md grows from actual pain, not from anticipating pain.

My setup is extreme. Yours doesn't have to be. But somewhere between "no CLAUDE.md" and "13 rule files with a self-improvement loop," there's a version that fits how you work. You'll find it by using Claude, getting annoyed, and writing one more rule.

The annoying part is that it works. Claude with good instructions wastes less of your time. And the only way to write them is to watch Claude guess a hover color wrong and think, I should have told it.

5 security checks before you ship your vibe-coded app

Mateusz Dembek — Sun, 22 Feb 2026 08:56:17 +0000

I pushed an API key (a secret password that lets your app connect to outside services) to a repo. My own key. In the actual code, sitting there in plain text for anyone on the project to see. Lucky for me, the repo was private. I only caught it because I have this habit of skimming every change after pushing it (watching myself do it, I'm starting to think it might be ADHD), even though I barely understand what I'm looking at. That day, something looked off. A long string of characters in a file that shouldn't have one.

I asked Claude: "Is that my API key in the code?" It was. Claude put it there when I told it to connect to the service. I said "connect," it connected. It also pasted the key right into a file instead of putting it somewhere safe.

What happened to Moltbook

In January 2026, Matt Schlicht launched Moltbook, an AI social network. His tweet got over 500,000 views.

538K views. Days later, Wiz found the database wide open.

Then Wiz dug into it. 1.5 million authentication tokens. 35,000 email addresses. Private messages between agents. All of it open. The whole thing came down to one database setting that was never turned on. AI built the app, but nobody asked it to secure the app.

I read that and thought: that could have been me. I build apps the same way Matt does. I say "build this" and AI builds it. I've never once said "and make sure nobody can break in."

Why this keeps happening

Researchers tested a bunch of AI-generated apps. 61% worked correctly. 10.5% were actually secure. Every app I've built was in that first group. I'm pretty sure none of them made it to the second.

The code is optimized for one thing: does it work? It's like hiring a contractor who builds you a beautiful house with no lock on the front door. Nobody asked for locks, so there are none.

The five checks

So I read a bunch of security reports. I understood maybe 40% of them. Here's what I got. Each one comes with a prompt you can paste straight into your AI tool. The prompts contain some technical terms. You don't need to understand them. Your AI does.

Your database is wide open

Supabase has a setting called Row Level Security (RLS). Firebase has its own version called Security Rules. Both control who can see what data. Both are almost never configured properly in AI-generated code.

Moltbook was the loudest example, but not the only one. Someone audited 5,600 vibe-coded apps. Over 2,000 security holes. Database access controls were a recurring theme. Not a bug. The default.

Check every table in my Supabase database. Enable Row Level
Security on all of them. For each table, create policies that
only allow users to read and modify their own data. Show me
what you changed.

Secrets in your source code

23.8 million secrets were leaked on public GitHub repositories in 2024. And they don't get cleaned up: 70% of secrets leaked back in 2022 were still active two years later. People push keys, forget about them, and the keys just sit there. For years.

API keys, database passwords, service URLs. They end up directly in your code files because that's the fastest path to working code. AI takes the fastest path every time.

The fix is a file called .env. It stores your secrets separately from your code, as something called environment variables. Another file called .gitignore tells GitHub to never upload .env.

Move all API keys, passwords, and database URLs out of the
code and into a .env file. Add .env to .gitignore. Make sure
no secrets appear anywhere in the code. Use environment
variables everywhere instead.

If you're already using GitHub, check that Secret Scanning and Push Protection are turned on in your repository settings. Public repos have them enabled by default and they're free. Private repos need a paid plan (GitHub Secret Protection, $19/month per active committer). And even when they're on, they only catch secrets that follow recognizable patterns, like keys from well-known services. A random API key with no recognizable pattern? Goes right through. The .env setup above is still the real fix.

The login page that looks right but works wrong

The login page looks professional. The problem is what happens behind the form.

Wiz dug into a bunch of vibe-coded apps and the findings were bleak. Password checks running in the browser instead of the server, meaning anyone who knows how to open developer tools can see the logic. "Stay logged in" handled by a simple flag in the browser that says "this user is logged in," which anyone can flip in seconds. That's it. That's the security.

The fix here isn't a prompt. It's a decision. Don't let AI build your login system from scratch. Use a library that thousands of developers have already tested. Supabase Auth, NextAuth, Clerk, Firebase Auth. Pick one. (If you're not sure which fits your project, I covered how to choose your tech stack in an earlier post.)

Do not build custom authentication. Use [Supabase Auth / NextAuth /
Clerk / Firebase Auth] for all login, signup, and session management.
Make sure every page that requires login redirects unauthenticated
users. Make sure passwords are never stored in plain text.

The package that doesn't exist

Sometimes your code references packages. These are pre-built chunks of code written by other developers that your project borrows. Except some of the ones AI suggests don't exist. The names are fabricated. AI just made them up.

Here's where it gets weird. Attackers watch for these fake names. Then they register them on npm, the main directory where JavaScript packages live, and fill them with malicious code. Your project tries to install a package AI invented, and it downloads something an attacker planted there yesterday. There's a name for it: "slopsquatting." I did not make that up.

Up to 21.7% of packages AI references don't exist (less with commercial models, more with open-source ones). And 58% of those fake names show up consistently across multiple sessions, which makes them predictable targets.

List every npm package this project uses. For each one, verify
it exists on npmjs.com and has more than 1,000 weekly downloads.
Remove any package that doesn't exist or isn't actively
maintained. Remove any package that isn't actually used in the
code.

If your project is on GitHub, turn on Dependabot. It watches the packages you use and alerts you when any of them have known security problems.

Your forms trust everyone

Every form in your app accepts text. Someone can type a script instead of their name. If your app doesn't clean the input first, it just runs it. This is called cross-site scripting. The code you get back fails to prevent it roughly 87% of the time.

Add input validation and sanitization to every form and user
input in the project. No user input should ever be inserted
directly into database queries, HTML output, or system
commands. Use parameterized queries for all database
operations. Sanitize HTML output to prevent script injection.
Show me every change.

How to actually run these checks

You don't need to remember five separate prompts. Here's one you can paste at the start of any new project:

Before writing any code, set up these security basics:

1. Create a .env file for all secrets (API keys, database URLs,
   passwords). Add .env to .gitignore. Never hardcode secrets
   in source files.

2. If this project uses Supabase or Firebase, enable Row Level
   Security on every table. Create policies so users can only
   access their own data.

3. Use an established auth library for all login and signup.
   No custom authentication code. Make sure every protected
   page checks for a valid session.

4. Validate and sanitize all user inputs. No raw input in
   database queries or HTML output. Use parameterized queries.

5. Before installing any package, verify it exists on npmjs.com
   and is actively maintained. Do not install packages with
   fewer than 1,000 weekly downloads unless I approve it.

Follow these rules for the entire project. If any of them
conflict with a feature request, tell me before proceeding.

If you already have a live project, paste this instead:

Audit this entire project for security issues. Check for:
hardcoded secrets in any file, .env files not in .gitignore,
Row Level Security disabled on any database table, user inputs
used without validation or sanitization, authentication
bypasses, admin routes without auth checks, and unused or
suspicious packages. Create a numbered list of every issue
with the file name and a specific fix for each.

And before you push anything live, ask AI to review its own work:

Act as a security reviewer. Go through every file in this
project and check for: hardcoded secrets, missing input
validation, unprotected routes, Row Level Security disabled,
plain text passwords, unnecessary packages, and any other
security issue. List every problem you find with the file
name and what needs to change.

I use Context7 (by Upstash, thanks Doug!) for code review. It's a plugin that gives AI access to current documentation for whatever tools your project uses, instead of whatever was in the training data months ago. Works with Cursor, Claude Code, and Windsurf. Free.

If your project is on GitHub, go to Settings and enable Dependabot (free on all repos). If your repo is public, also turn on Secret Scanning and Push Protection (also free). For private repos, these two require a paid GitHub plan. They won't fix existing problems, but they'll catch new ones before they go public.

That API key I pushed to my repo? Claude fixed it in two minutes once I asked. The problem wasn't the fix. It was that I didn't know to ask. Now I do. Now you do too.

How to install and run Claude Code in VS Code

Mateusz Dembek — Sun, 22 Feb 2026 08:33:54 +0000

On November 24th one of my dev friends (hey Maciej!) told me I could run Claude Code in VS Code's terminal. I had no idea. Shame on me I guess. Since then I've been building all the things I always wanted but never had a developer for.

Let me show you how to start using it. Install to first prompt in under 5 minutes.

Step 1: Open VS Code and the terminal

Open your project folder in VS Code. If you don't have a project yet, create an empty folder somewhere and open that.

VS Code after opening a project. Ignore the shortcuts for now.

Pull up the terminal. Top menu: Terminal > New Terminal. Or just hit Ctrl+`.

This is where you'll type commands and talk to Claude.

This terminal at the bottom is where everything happens. All the commands below go here.

Step 2: Install Claude Code

Same terminal. One command, nothing else to install first.

On Mac or Linux:

bash curl -fsSL https://claude.ai/install.sh | bash

On Windows (PowerShell):

powershell irm https://claude.ai/install.ps1 | iex

You'll see a few lines of output. When it stops and you get your cursor back, you're good. Close and reopen VS Code so the terminal picks up the new command.

Step 3: Launch it

Same terminal. Type claude and hit Enter.

bash claude

First time you run it, there's a quick setup. Takes about a minute.

It asks you to pick a color theme:

Theme selection on first launch. Dark mode is the only correct answer.

Next up: how you want to log in. You need a Claude Pro, Max, or API account.

If you're paying for Claude Pro or Max, pick option 1.

It opens a browser window where you authorize the connection:

Click Authorize and switch back to VS Code.

Back in VS Code, it confirms you're logged in:

Login confirmed. Almost there.

Next it shows security notes. Read them or don't, then press Enter.

Standard disclaimer. Press Enter to continue.

Now it wants to know about terminal settings.

Say yes. This makes Shift+Enter work for new lines, which you'll use constantly.

Last step: it checks if you trust the project folder.

Your own project? Trust it. Random folder from the internet? Maybe don't.

That's it. You're in. The whole setup takes about a minute once you've done it before.

Claude Code ready to go. Type what you want to build and hit Enter.

When things break

"command not found" - Close VS Code, reopen, try again. Works embarrassingly often.

Permission errors - Paste the error into any AI chat and ask for help. That's what I do.

Login issues - The login opens in your browser. If it's not working, clear browser cookies, try incognito, log in again.

Anything else - Screenshot the error and paste it into any AI chat. Ask it to help. No shame in that. I do the same thing every day. My entire debugging strategy is asking AI to fix the AI setup.

Summary

Install Claude Code. Type claude in your project folder. When something breaks, screenshot it and ask AI.

If I figured this out as a designer who's never written a line of code, you'll be fine.

Oh, and for those of us who appreciate readable font sizes: Cmd+= (or Ctrl+= on Windows) zooms in the whole VS Code window, terminal included. Killer feature.