Context Engineering: Why Your Prompt Is the Smallest Problem

Source: Dev.to

I was at a client project recently, facing a situation I know well by now: a new codebase, no AI tooling set up, and a developer on the team asks me:

“How do you get the AI to produce such good results?”

I looked at his screen. He had Claude open in the browser, no project context, a fresh chat for every single task.

That’s the problem. Not the tool, not the model, not the prompt—the missing structure.

After a year of using AI daily in real projects, I’m convinced: the difference between “AI is pretty decent” and “AI has fundamentally changed how I work” isn’t the perfect prompt. It’s the context you give the AI before it answers the first question.

CLAUDE.md – Where Everything Starts

When I start working on a new project with Claude, the first thing I create is the CLAUDE.md. Not the first component, not the first feature—the context file.

What goes in it?

Everything a new developer would need to know on day one:

• Tech stack and versions
• Project structure and why it’s set up that way
• Design system – colors, typography, spacing (concrete values)
• Coding rules – what always applies, what never does
• External links, API endpoints, important accounts

It sounds like a lot of work. It is—once. After that I save myself from rebuilding that context in every AI session. I no longer have to explain “we use Tailwind, not Styled Components” or “all texts must go through i18n”. It’s in the file. Claude reads it, follows it.

Practical difference: when I say “create a new section for the services page”, I get code that uses my design system, my components, is TypeScript‑strict, and contains no hard‑coded strings. Not because Claude is magic—but because it knows the rules.

PRODUCT_SPEC.md – The Product Vision Written Down

CLAUDE.md describes how things are built. PRODUCT_SPEC.md describes what and why.

I created it the first time I realized that if I haven’t touched a project for three weeks and then pick it back up, I need a moment to get back into the right frame of mind myself. The AI needs that even more.

My PRODUCT_SPEC.md covers

• What is the core promise of the product?
• Who are the users and what do they want?
• What features exist, and what design decisions are behind them?
• What was deliberately not built – and why?

That last point is underrated. “What we don’t build” is just as important as “what we build”. If I don’t tell the AI that we deliberately decided against a certain feature, it will suggest—or even implement—it the next time it seems relevant.

Externalizing Coding Rules – Don’t Repeat Them in the Prompt

A lot of people include their rules in the prompt every time:

“Don’t write inline CSS. Don’t use any types in TypeScript. Always create a German and English version.”

Then they rewrite that for the next task.

That’s exhausting—and error‑prone. At some point you forget a rule, or you phrase it slightly differently, and the AI interprets it differently.

My solution: a thorough “Rules” section in CLAUDE.md. Everything that always applies goes there.

Real‑project examples

- ESLint must pass without errors before every commit
- No `eslint-disable` comments without explicit approval
- Every new text must appear in `i18n/de.json` and `i18n/en.json`
- Typography: en dash with non‑breaking spaces, never the English em dash

That last rule is one anyone recognizes after forgetting to specify it. I learned it by spending an hour fixing wrong dashes across an entire project.

Recurring Tasks as Skills

This is the part that gets talked about the least—and the one that has helped me the most.

Every project has tasks that always run the same way. After a new feature: run the linter, take a browser screenshot, comment on the ticket with the result. For a new blog post: validate front‑matter, run the typography check, create the German and English versions.

I used to describe this in the prompt every time:

“Don’t forget to run the linter afterwards.”

Now I put these workflows into skill files—Markdown files that describe step‑by‑step what to do in a given context. I mention the skill briefly in the prompt:

“Use the publish-blog-post skill.”

It sounds small, but in practice it’s what makes the difference between an AI I have to correct and an AI that simply does the right thing.

Define Data Models Before Writing Code

A lesson I learned the hard way.

I once gave an AI the task of implementing a new feature with several database tables. The result was technically working, but the data model was wrong—not a syntax error, but a design flaw that would cause problems in three months. Missing constraints, an N:M relation that should have been 1:N, and a field that semantically belonged in a different table.

Since then I do it differently: before I let the AI loose on database work, I write a short model spec. In prose, no special syntax:

Table: orders
- id: UUID, Primary Key
- user_id: FK → users.id, NOT NULL
- status: ENUM (pending, processing, shipped, cancelled), NOT NULL
- total_cents: INTEGER, NOT NULL (no DECIMAL – we calculate in cents)
- created_at: TIMESTAMP, NOT NULL, default now()
- updated_at: TIMESTAMP, NOT NULL, default now()

Having this clear, concise description up front saves countless hours of refactoring later.

TL;DR

1. Create a CLAUDE.md with tech stack, project structure, design system, coding rules, and useful links.
2. Write a PRODUCT_SPEC.md that captures the product’s purpose, users, features, and intentional omissions.
3. Externalize all evergreen coding rules in CLAUDE.md—don’t repeat them in prompts.
4. Package recurring workflows as “skill” Markdown files and reference them briefly in prompts.
5. Define data models in plain prose before asking the AI to generate database code.

By front‑loading this context, the AI becomes a true partner that knows the project, not a tool you have to constantly re‑educate. 🚀

Database Schema (excerpt)

CREATE TABLE orders (
    id           SERIAL PRIMARY KEY,
    user_id      INTEGER NOT NULL REFERENCES users(id),
    total_cents  INTEGER NOT NULL CHECK (total_cents >= 0),
    created_at   TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
);

Relations

• One order has many OrderItems (1 : N)
• One order belongs to exactly one user

Context Engineering Instead of Prompt Engineering

I notice the term “prompt engineering” showing up everywhere right now—workshops, courses, LinkedIn posts about the perfect phrasing. I think that’s the wrong focus.

The prompt is the last step. The system around it—CLAUDE.md, PRODUCT_SPEC.md, coding rules, skills, data models—is what actually determines quality. The AI is only as good as the context it receives, and that context can be built systematically, versioned, and improved over time.

• A good prompt in a poorly prepared project delivers mediocre results.
• A mediocre prompt in a well‑prepared project delivers good results.

I call this context engineering. Whoever understands it has a real advantage—not just with Claude, but with any AI tool.

TL;DR

What

• CLAUDE.md – Tech stack, project structure, design tokens, coding rules
• PRODUCT_SPEC.md – What we build, why, and what we deliberately don’t build
• Skill files – Recurring workflows defined once, referenced forever
• Data model specs – Written before code, not discovered through refactoring

Why

The better the structure around the AI, the better the results. That’s not theory—it’s the experience from a year of daily use in real projects.

I’m Christopher, a freelance full‑stack developer from Hamburg. I write about Vue/Nuxt, TypeScript, and working with AI in real projects at grossbyte.io.