DEV Community: Vinh Nguyen

Beyond CLAUDE.md and AGENTS.md: when your coding agent needs a behavior spec

Vinh Nguyen — Wed, 15 Apr 2026 16:31:47 +0000

TL;DR: CLAUDE.md and AGENTS.md are excellent at steering how agents write code. They were never designed to capture what the product promises to do. When agents refactor, extend, or integrate code, they need a behavior spec — not more workflow instructions. That's the layer above instruction files.

Your agent refactors the billing module and changes the grace period from 14 days to 30. The code is cleaner. The tests pass. The product promise is broken.

Your agent simplifies the auth flow and removes an edge case check. It looked redundant in the code — but it was handling a deliberate compliance requirement that existed nowhere except in your head.

You had CLAUDE.md or AGENTS.md in the repo. You had coding conventions written down. The agent followed those perfectly — and still broke the product.

This isn't a model capability problem. The models are better than they've ever been. It's a context architecture problem — instruction files tell agents how to write code, but not what the product promises to do.

What CLAUDE.md and AGENTS.md actually are

These files work. They solve a real problem. But it's worth being precise about which problem.

CLAUDE.md tells Claude Code how to operate in your repo. Use pnpm, not npm. Run tests before committing. Don't modify generated files. Keep responses concise. It's a workflow configuration — process knowledge that changes when your conventions change.

AGENTS.md does the same for Codex and other agents: coding conventions, build commands, architecture patterns, file organization rules. OpenAI's AGENTS.md spec has been adopted across tens of thousands of repos because it solves the "how to work here" problem well.

Both are instruction files. They answer: "How should an agent behave in this repo?"

That's a useful question. But it's not the question that causes production incidents.

The question they don't answer

The question that causes production incidents is: "What does this product promise to do?"

When an agent refactors your billing module, it doesn't need to know whether to use pnpm or npm. It needs to know that the 14-day grace period is a confirmed product decision — not a magic number to clean up. It needs to know that the empty tax_id field is intentionally blank for compliance reasons — not a bug to fix. It needs to know that the auth flow is deliberately minimal because the permission model hasn't been decided yet — not because nobody got around to adding OAuth.

CLAUDE.md doesn't have this information. Neither does AGENTS.md. Not because they're badly designed — because they were designed for a different purpose.

Where instruction files hit their ceiling

The ceiling isn't one thing. It's a pattern that shows up in three ways:

1. No semantic structure. CLAUDE.md and AGENTS.md are freeform prose. A human reads them and infers what matters. An agent reads them and treats every line as equally weighted. "Use TypeScript" and "never change the grace period without product owner approval" have the same format — a bullet point. One is a preference. The other is load-bearing.

2. No trust signal. Everything in an instruction file has the same status: written down. There's no way to distinguish a confirmed product decision from a provisional assumption from an active experiment. An agent treats them all as current truth — and they aren't.

3. No verification path. After an agent runs, there's no way to check whether it honored the product constraints. You can lint code style. You can run tests. But "did the agent preserve the billing contract?" requires a human to review the diff line by line and remember every product decision in their head.

These aren't flaws in CLAUDE.md or AGENTS.md. They're the natural limits of instruction files trying to carry behavior specs they were never built for.

What sits above instruction files

The layer above instruction files is a behavior spec — an artifact that captures what the product promises to do, in a format that's both human-reviewable and machine-readable.

A behavior spec (.pbc.md — formally a Product Behavior Contract) sits in your repo alongside CLAUDE.md and AGENTS.md, but it answers different questions:

	CLAUDE.md / AGENTS.md	.pbc.md
Answers	"How should the agent work here?"	"What does the product promise?"
Contains	Conventions, commands, patterns	Behaviors, rules, states, edge cases
Changes	When your workflow changes	When a product decision changes
Audience	Agents + new contributors	Everyone — product owner, eng, QA, agents
Structure	Freeform prose	Markdown with typed semantic blocks

Here's what the same knowledge looks like in each format:

In CLAUDE.md:

# Billing rules
- Grace period is 14 days
- Don't change billing logic without approval
- Tax ID is required for invoices

In a .pbc.md behavior spec:

## Grace period enforcement

### When
A subscription payment fails

### Then
- System enters a 14-day grace period
- User retains full access during grace period
- Daily retry attempts are made against the payment method
- On day 14, if no successful payment: downgrade to free tier

### Invariants
- Grace period duration must be exactly 14 days — not configurable per plan
- No data deletion occurs during grace period
- Grace period cannot be extended manually by support

### Edge cases
- If user upgrades plan during grace period: new payment attempt immediately
- If payment method is removed during grace period: grace period continues (retry stops)

The CLAUDE.md version tells an agent "don't touch this." The behavior spec tells the agent (and the product owner, and QA, and the next developer) exactly what the product promises — in enough detail to verify whether the promise is still being kept.

The market knows something is missing

This isn't a theoretical gap. The pain is already showing up across the ecosystem:

Anthropic published hooks documentation — deterministic controls that run outside the model, because they recognized that prompt-level instructions aren't reliable enough for enforcement
OpenAI published a harness engineering series describing how they built their entire product with agents — structured documentation directories as the source of truth, architectural constraints enforced mechanically via linters and CI — then didn't productize the approach
Gartner started covering agentic AI governance as a distinct market category

The vocabulary is fragmenting — guardrails, governance, policies, behavior, intent — but the underlying need is converging: teams need a structured way to specify what agents are and aren't allowed to do, above the instruction file layer.

How to start

You don't need to spec your entire product on day one. Start with the module where an agent mistake would hurt most — usually billing, auth, or entitlements.

Create billing.pbc.md in your repo
Write the 3-5 behaviors that are non-negotiable (grace period, refund window, upgrade logic)
For each behavior: what must happen, what must not happen, edge cases
Point your CLAUDE.md or AGENTS.md at it: "Read *.pbc.md files before modifying any billing, auth, or entitlement logic"

That last step is the bridge — your existing instruction files become the pointer to the behavior spec. They work together, not against each other.

The stack, not the replacement

The right mental model isn't "PBC replaces CLAUDE.md." It's a stack:

Layer 4: Behavior specs (.pbc.md)                  — product truth — what it promises
Layer 3: Feature specs / PRDs                      — what we plan to build
Layer 2: Session memory / context                  — what we're doing now
Layer 1: Instruction files (CLAUDE.md, AGENTS.md)  — how to work here

Each layer is useful. None replaces the others. Most repos have layers 1-3 covered. Layer 4 is the one that prevents the production incident where an agent does exactly what it was told — and breaks a product promise nobody wrote down.

The PBC spec is open source at github.com/stewie-sh/pbc-spec. You can browse example contracts in the PBC viewer.

If your instruction files are working for code conventions but failing for product decisions — this is the layer that's missing.

Disclosure: this article was drafted with AI assistance and reviewed, edited, and fact-checked by the author before publication.

AI agent context still misses the product layer

Vinh Nguyen — Sun, 29 Mar 2026 15:35:04 +0000

If you spend time around AI coding tools, the conversation has clearly shifted.

People are talking less about prompts and raw model quality, and more about the surrounding system: repo rules, memory, harnesses, evals, and monitoring.

That shift is correct. But even the better AI agent stacks still miss one important layer: product context.

Now the serious work is happening one layer above the model:

OpenAI is writing about harness engineering and internal monitoring for coding agents.
Anthropic is writing about effective harnesses for long-running agents and even parallel agent teams building a C compiler.
Every tool ecosystem now has some version of workflow rules, repo instructions, memory files, and spec-driven coding.

Taken together, these point to the same conclusion: the model is only part of the system. Reliable agentic coding depends on the surrounding stack.

That's real progress. But it still leaves one missing layer.

The modern agent stack is getting better at telling agents how to work. It still does a poor job telling them what the product must continue to do.

What AI agent context solves today

Most serious AI-native repos are already building some version of the same stack:

Repo instructions like AGENTS.md, CLAUDE.md, or tool-specific rules tell the agent how to work in this codebase.
Memory files preserve what happened in prior sessions so the next run doesn't start cold.
Harnesses manage long-running work, handoffs, tool access, and task decomposition.
Evals and monitors check whether the agent stayed within technical or safety boundaries.

Each layer solves a real problem.

Repo instructions reduce workflow mistakes. Memory reduces repeated exploration. Harnesses help agents make progress across long tasks. Evals and monitors catch bad outputs and suspicious behavior.

If your goal is better software engineering execution, this stack makes sense.

Why better harnesses still don't protect product decisions

Here's the problem: an agent can follow every repo rule, use the right harness, pass the tests, and still break the product.

Not by writing obviously bad code. By changing something that looked reasonable from the code alone.

That happens because most product decisions are not explicit in the repo:

Is the 14-day refund window a confirmed policy or a placeholder?
Is the current permission model intentional or just the minimal thing that shipped first?
Is an empty field a bug, a compliance requirement, or a deliberate product choice?
Is this validation rule load-bearing, or leftover code that should be removed?

The agent sees implementation. It does not automatically see product intent, trust level, or business significance.

That is why teams end up saying the same thing after an agent made a "wrong" change: the code was plausible, but it violated something the team had already decided.

This is not a prompt quality problem. It is a missing artifact problem.

What is missing from AI agent context today?

The missing layer is product truth.

Not a PRD. Not a sprint spec. Not a memory log. Not a test suite.

Product truth answers a narrower and more durable question:

What does this product actually promise to do right now, and which behaviors are confirmed enough that agents should treat them as protected?

That layer needs to capture things like:

confirmed product behaviors
forbidden states and actions
deliberate edge cases
areas that are still provisional
decisions that are actively being explored and should not be treated as settled

Without that layer, every agent is forced to infer product meaning from implementation details.

Sometimes that works. Sometimes it silently introduces product drift.

Why AGENTS.md and memory banks are not enough

This is where teams get confused, because all of these artifacts look similar from the outside. They're usually text files in the repo. They're all readable by both humans and agents. They all seem like "context."

But they operate at different levels:

AGENTS.md tells the agent how to behave as a contributor.
Memory banks preserve what happened across sessions.
Feature specs describe what the team plans to build.
Tests verify implementation behavior in specific scenarios.
Monitors look for dangerous or misaligned actions.

None of those directly answer: which product behaviors are intentional, protected, and safe to build on top of?

You can have all five and still leave the core product layer implicit.

That's why a repo can feel "well-instrumented" for agents and still be fragile when they touch billing, entitlements, onboarding logic, permissions, or compliance-sensitive flows.

What a Product Behavior Contract adds

A Product Behavior Contract adds the missing product layer without replacing the rest of the stack.

It sits alongside your existing agent context and makes the behavioral contract explicit:

What must happen
What must not happen
Which edge cases are deliberate
Which behaviors are confirmed, provisional, or still being explored
Which source files provide evidence

That changes the quality of agent decisions.

When the contract says a billing limit is confirmed, the agent stops treating it as an arbitrary number it can refactor freely. When the contract says the permission model is still under exploration, the agent stops extending it as if the design were settled. When a behavior is marked provisional, humans and agents both know not to overfit around it.

This is the difference between code context and product context.

Code context tells the agent what exists.
Product context tells the agent what must remain true.

The agent stack is converging. The product layer is next.

My read of the current ecosystem is that OpenAI, Anthropic, and the broader tool market are all converging on the same architecture:

give agents better maps of the repo
help them work across long time horizons
break work into clearer sub-tasks
evaluate and monitor their behavior more rigorously

That is the right direction.

But as agents get better at execution, the cost of missing product truth goes up, not down.

A stronger coding agent can now move faster, touch more files, and refactor more confidently. If the product layer is still implicit, that extra capability just lets it make bigger product mistakes more efficiently.

The next mature AI-native repo will not stop at workflow rules, harnesses, and evals. It will also include a durable product artifact that says what the software is actually supposed to do.

That's the role of a product behavior contract.

The format is open source. The PBC viewer lets you browse structured contracts in the browser, and the PBC spec is public if you want to see the model directly.

If you're already using AGENTS.md, memory files, or spec-driven coding, this is the next layer I'd look at: a durable artifact for product truth, not just execution rules.

Disclosure: this article was drafted with AI assistance and reviewed, edited, and fact-checked by the author before publication.