DEV Community: DaymondHyper

I Gave Claude Code an AGENTS.md Contract and Stopped Babysitting It

DaymondHyper — Sun, 09 Aug 2026 07:11:55 +0000

Claude Code follows instructions too well, and that's the whole problem. When nothing tells it what engineering discipline looks like, it invents a plausible version: graceful degradation into any, tests that assert implementation details so they pass no matter what, silent catch (e) {} blocks eating the failures you needed to hear about. I spent months working around this one edit at a time. The fix wasn't a better prompt. It was a contract.

The problem is that it listens

Claude Code is the best instruction follower I've used, and that's the whole problem. Give it an ambiguous ask and it doesn't stall, it guesses. It picks the fastest plausible path, and on its own that path is usually a small degradation: a type widened to any here, a test that only asserts what the code already does there, an empty catch block quietly swallowing the error that should have been loud.

None of this is malice. It's what a very eager, very fast assistant does when nobody has told it what done looks like. And you can't just stand over it and correct every response, there's no point paying for an agent you have to supervise like an intern. The real question is how you draw the line between plausible and correct, and make it stick across every task, every session, every tool.

AGENTS.md is a contract, not a wish list

I started with CLAUDE.md, like everyone does, a prose file describing the project. It helped, but it read like documentation. Claude Code skimmed it, absorbed the vibes, and when a situation wasn't covered it went right back to inventing plausible engineering.

The shift came when I moved everything into AGENTS.md and stopped writing like I was leaving notes for a colleague. Claude Code reads AGENTS.md first, and other agents respect it too, so the discipline travels with the repo instead of living inside one tool's prompt. More importantly, I started writing it like a contract. A wish list says "write good tests." A contract says what good means, what happens when a test is bad, and what to do when the work keeps failing. Specific, numbered, testable. That difference is most of the win.

The contract skeleton

Mine has eight baseline rules, a six-rung verification ladder, and a failure protocol. Every change has to climb the ladder before it counts as done, and rungs one through three are non-negotiable. Here's the shape of it, trimmed to the parts that do the actual work:

# AGENTS.md

## Baseline Rules

1. Never widen a type to `any` to make a check pass. Fix the check.
2. A test that cannot fail is not a test. Delete it and write one that can.
3. No silent `catch (e) {}`. Handle it, rethrow it, or log it with context.
4. Prefer the codebase's existing patterns over new abstractions.
5. A change that compiles but is not verified does not exist.
6. Public APIs get tests before they get callers.
7. If a rule conflicts with a deadline, the deadline loses.
8. When in doubt, ask. Guessing is the expensive path.

## Verification Ladder

Rungs 1-3 are mandatory for every change:

1. Does it compile?
2. Does the changed behavior actually work?
3. Does it break anything adjacent?
4. Does it follow this codebase's conventions?
5. Does it hold at the boundaries: empty, null, huge, concurrent?
6. Is the result observable in production?

## Failure Protocol

- First failure: fix it and re-verify. Normal day.
- Second failure: stop and re-derive. Your mental model of the system is wrong.
- Third failure: stop, revert to last known good, and document what happened.

The failure protocol

This is the part people ask me about most, and it's the part that saves the most time. Claude Code iterates fast and burns tokens happily grinding on a broken hypothesis. It will re-read the same file, try the same fix a different way, and tell you with total confidence why this time it will work. Without a brake pedal, that's money and patience going down a hole.

Three attempts, that's the whole protocol. First failure, fix and re-verify, a normal day. Second failure, stop and re-derive, because by then the model's mental model of the system is wrong, not its typing. Third failure, stop, revert to last known good, and document. The revert matters: it puts the system back on known ground instead of worse ground, and the documentation means the next session starts from the lesson instead of repeating it.

That one rule, stop after three, has saved me more wasted work than anything else in the file. Grinding on a broken hypothesis is the expensive failure mode, and the protocol makes it structurally impossible.

Workflows get their own files

Baseline rules are the floor, but most tasks in a project follow a shape: feature, bugfix, review. Those shapes aren't contracts, they're procedures, steps in order with gates between them. So they live in separate workflow files, and the agent gets pointed at the right one when a task starts.

Keeping them separate matters because a workflow is sequential and the contract is not. Buried in a system prompt, a workflow gets skimmed. In its own file, it gets followed. When Claude Code starts a feature, it opens the feature workflow, and the first thing that file asks for is a two-sentence contract for the change. That single step kills a surprising amount of drift.

# Feature Workflow

1. State the contract for this feature in two sentences: what it does, what it deliberately doesn't.
2. Find the closest existing pattern in this codebase and follow it.
3. Write the behavior-proving test first. Watch it fail.
4. Implement the smallest change that makes it pass.
5. Climb the verification ladder. Rungs 1-3 are mandatory.
6. If the design fights you at rungs 4-5, stop and re-derive before writing more code.
7. Report back: what you changed, what you tested, what you left untested.

Tests that prove behavior, not implementation

Rung two of the ladder is where the discipline actually lands, because it's where Claude Code's default instincts go to die. Left alone, it writes tests that assert implementation details, tests that can't fail because they only check that the code runs, not that it's right.

// Asserts the mechanism, not the behavior. Passes even when the feature is broken.
test("addItem stores the item", () => {
  const cart = new Cart();
  cart.addItem({ name: "sword", price: 45 });
  expect(cart.items.length).toBe(1); // still passes if the total is never charged
});

// Asserts the behavior. Fails when the feature is broken.
test("addItem charges the full price of what was added", () => {
  const cart = new Cart();
  cart.addItem({ name: "sword", price: 45 });
  cart.addItem({ name: "shield", price: 30 });
  expect(cart.total()).toBe(75);
});

Here's the rule I use to judge any test: delete the implementation and the test should fail. If it doesn't, it was never testing anything. Behavior-proving tests are the ones that break when someone breaks the feature, and those are the only tests worth paying Claude Code to write.

None of this makes Claude Code magic. It's the same model doing the same reasoning. What changed is that the first file it reads now describes discipline as a procedure instead of a preference, and when the procedure says stop, it stops. You still review its work, just a lot less of it.

Free sample with the full AGENTS.md contract, plus TypeScript, security, and testing rules: https://github.com/DaymondHyper/agentforge

Full pack with feature, bugfix, and review workflows, templates, and 24 rule files for a one-time $29: https://dedyclan.gumroad.com/l/agentforge

Cursor Rules: How to Stop Your AI Agent From Writing Slop

DaymondHyper — Sun, 09 Aug 2026 06:17:21 +0000

You just installed Cursor, opened a TypeScript file, and asked the agent to fix a bug. Ten seconds later it handed you a type SomeType = any and a @ts-ignore above the line that wouldn't compile. This is the moment most developers discover that AI coding agents are powerful but undisciplined.

The fix isn't a better model. It's rules.

Most AI coding agent best practices boil down to a single idea: tell the agent what good looks like before it starts typing. Cursor lets you define rules files in .cursor/rules/ that load alongside your project context and tell the agent how to behave. Claude Code has its own rules system, Windsurf has a rules directory, Copilot reads .github/copilot-instructions.md. Learn to configure cursor rules properly and your agent starts behaving like a careful senior engineer instead of an eager intern.

What cursor rules files are

Cursor rules are markdown files with a .mdc extension stored in .cursor/rules/ at your project root. Each file is a set of instructions the agent reads before it starts working. When a rule's conditions match the file being edited, the instruction is injected into the model's context window.

A cursor rules file has two parts: a YAML frontmatter block between --- markers, and a markdown body with the actual instructions.

How to configure cursor rules: the frontmatter fields

Three fields matter.

description (required). A short summary of what the rule enforces. Cursor surfaces this when you toggle rules, so make it specific.

globs (optional). File patterns the rule applies to. Without globs, the rule applies to everything, which wastes context and creates conflicts.

alwaysApply (optional). Set to true for rules that should load in every session, regardless of the files involved. Leave it false for rules that only trigger when matching files are touched.

Real example:

---
description: Enforce strict TypeScript, no any, no ts-ignore
globs: **/*.{ts,tsx}
alwaysApply: false
---

# Strict TypeScript

## Context
This codebase runs with `strict: true`. Using `any` disables the type system
for that value and lets bugs through at runtime. Banned types are a team
decision, not a style preference.

## Requirements
- Give function parameters and return values explicit types.
- Use `unknown` instead of `any` when a value's shape is not known yet, then
  narrow it with a type guard before using it.
- Model state with discriminated unions rather than long optional chaining
  chains.

## Anti-Patterns
- ❌ `any` type annotations. Use `unknown` and narrow.
- ❌ `@ts-ignore` or `@ts-expect-error` to silence the compiler. Fix the type.
- ❌ `as any` casts to force a value through.

Note the structure of the body: Context, Requirements, Anti-Patterns. That pattern is the heart of what makes a rule actually work, and I'll come back to it below.

AGENTS.md and CLAUDE.md: how they differ from .cursor/rules

A few related standards do similar jobs, and the naming confuses everyone.

AGENTS.md is a cross-tool standard: a single markdown file at the repository root that documents how an agent should work in that repo. Think of it as a README written for AI agents. It covers build commands, project conventions, and "don't touch X". Because it's a plain file at the root, any tool that follows the spec picks it up.

CLAUDE.md is Claude Code's project memory file. The claude code rules system reads it at startup, along with files it references, and treats it as long-term context for the session. Older projects use a CLAUDE/ folder with sub-files; a single root file is the current recommendation.

.cursor/rules files differ from both in one important way: they are scoped and conditional. AGENTS.md and CLAUDE.md are read as context in full. Cursor rules only load when their globs and settings match the current task. That makes them the right tool for file-type-specific discipline, while AGENTS.md is the right tool for repo-wide onboarding information.

A pragmatic setup: put repository facts (commands, architecture, conventions) in AGENTS.md, then layer scoped rules on top for things like "TypeScript files never get any" or "every new API endpoint needs input validation". The tools are converging on the same idea under different filenames.

Common mistakes that make cursor rules useless

Most rule files fail for one of four reasons.

1. Rules are too vague. "Write clean code" is not a rule, it's a wish. The agent has no operational definition of "clean", so it ignores the instruction. Good rules name the exact behavior: "no any", "every function has an explicit return type".

2. No anti-patterns. Telling the agent what to do is only half of it. Models pattern-match strongly on negative examples. A rule that says "validate all input" but never shows what an invalid attempt looks like produces validation that is decorative. List the exact things you never want to see, with examples, and the agent stops producing them.

3. No globs. A rule about API endpoints that applies to every file gets loaded constantly and starts conflicting with other rules. Scope rules to the files they govern. A testing rule probably belongs on **/*.test.{ts,tsx}, not **/*.

4. Nobody checks that the agent obeyed. Cursor lets you toggle rules in the chat composer, and @-mentioning a rule or file forces it into context for a conversation. If a rule matters for a task, mention it explicitly instead of trusting that the model read all seventeen rule files. Then verify: review the diff for any and @ts-ignore, and send it back if the agent slipped.

There's also a context budget problem. Every rule that loads costs tokens. Twenty vague rules crowd out real project context and make the agent worse, not better. Prefer a few sharp rules over a pile of aspirational ones.

Copy-pasteable cursor rules examples

These work in Cursor's .cursor/rules. The structure transfers to any tool that reads markdown rules. Adjust the globs to your stack.

1. TypeScript strictness

---
description: No any, no ts-ignore in TypeScript files
globs: **/*.{ts,tsx}
alwaysApply: true
---

# Strict TypeScript

## Context
The project compiles with `strict: true`. Any, ts-ignore and unsafe casts are
banned because they disable compile-time checks and move failures to runtime.

## Requirements
- Write explicit types for parameters, return values, and exported variables.
- Reach for `unknown` when a value arrives from an untyped boundary, then
  narrow it with a type guard.
- Handle `null` and `undefined` explicitly. Prefer early returns over `!`.

## Anti-Patterns
- ❌ `any`, `as any`, or `as unknown as SomeType`.
- ❌ `@ts-ignore` and `@ts-expect-error`.
- ❌ Non-null assertion `!` on values that can actually be null.

2. Tests that prove behavior

---
description: Test files must assert behavior, not cover lines
globs: "**/*.{test,spec}.{ts,tsx,js,jsx}"
alwaysApply: false
---

# Behavioral tests

## Context
Coverage percentages measure nothing if the assertions don't. A passing test
suite that never fails is a treadmill. Each test should demonstrate one
behavior.

## Requirements
- One behavior per test. Name it like `should reject expired tokens`.
- Assert on observable outcomes, not on how the code is wired internally.
- Follow arrange, act, assert, and keep the act section to one call.

## Anti-Patterns
- ❌ Tests with no assertions, or `expect(true).toBe(true)`.
- ❌ Mocking the system under test so heavily that the test proves nothing.
- ❌ Snapshot-only tests that would pass with obviously wrong output.

3. Security at every boundary

---
description: Validate input and avoid common security traps
globs: "**/*.{ts,tsx,js,jsx,py,go}"
alwaysApply: false
---

# Security guardrails

## Context
Every input is untrusted until proven otherwise. The cheapest vulnerability is
the one you never ship, so apply these checks to new code automatically.

## Requirements
- Validate and sanitize all input at the service boundary, before use.
- Use parameterized queries or an ORM for any database access. Never build SQL
  by string concatenation.
- Escape output in HTML templates. Prefer the framework's built-in escaping.
- Redact secrets and tokens in logs. Never log request bodies wholesale.

## Anti-Patterns
- ❌ SQL assembled with template strings containing user input.
- ❌ Storing secrets in source code or config files that get committed.
- ❌ Trusting client-supplied values for authorization decisions.

The full rule set and where to get it

The examples above are the foundation. Once you see the pattern, you'll want rules for more of your stack: frontend conventions, backend API design, database migrations, code review workflows, and project templates that ship with rules already wired in.

That's what AgentForge is: a pack of 24 opinionated, machine-readable rule files across seven categories (general, frontend, backend, testing, AI agents, DevOps, database). Every file uses the frontmatter format and Context / Requirements / Anti-Patterns structure shown above, with accurate globs and alwaysApply settings so rules load only when relevant. It comes with a one-command installer and project templates, and it's a one-time purchase: US$29 (A$45) at https://dedyclan.gumroad.com/l/agentforge.

Not sure the structure fits your workflow? A free sample pack with three rule files is available on the same page. Drop them into .cursor/rules/ and feel the difference on your next task.

FAQ

What is a cursor rules file?

A cursor rules file is a markdown document with the .mdc extension placed in the .cursor/rules/ directory. It contains YAML frontmatter (description, globs, alwaysApply) and a markdown body of instructions. Cursor injects the body into the agent's context when the file being worked on matches the rule's globs, or whenever the rule has alwaysApply: true.

How do I get Cursor to follow my rules?

Three things help. First, make rules specific with explicit anti-patterns, because vague instructions are easy to ignore. Second, @-mention the rule or file in the chat composer so it's forced into context for that conversation. Third, verify: review the agent's diff for banned patterns like any or @ts-ignore and send the change back until it complies.

What's the difference between AGENTS.md and .cursor/rules?

AGENTS.md is a plain markdown file at the repository root that any standards-compliant agent tool reads as context. It's best for repo-wide facts: build commands, architecture, conventions. .cursor/rules files are conditional and scoped by globs, which makes them better for fine-grained discipline like "no any in TypeScript files". The two complement each other.

How to make your AI coding agent stop writing slop

DaymondHyper — Sun, 09 Aug 2026 06:15:18 +0000

Every AI coding agent I've used shares one habit: it writes the plausible thing. The code compiles. The tests pass. And a senior engineer reviewing it would reach for a red pen. any where a union belongs. Tests that assert on implementation so they survive any refactor. catch (e) {} blocks that quietly swallow production errors.

The fix isn't a better model or a cleverer prompt. It's a set of rules at the repo level, written in a format the agent is guaranteed to read.

What rules files are

Cursor reads .cursor/rules/*.mdc. Claude Code reads CLAUDE.md and AGENTS.md. The .mdc format is plain markdown with YAML frontmatter. Here's the opening of the TypeScript rule file from the AgentForge sample pack:

---
description: "Strict TypeScript discipline for production code"
globs: "**/*.{ts,tsx}"
alwaysApply: true
---

Three fields carry the weight. description tells the agent in one sentence what the file is for. globs scopes it, so a TypeScript rule never fires on a Python file. alwaysApply: true loads it into every session. Agents skip a 2,000-line rules file. They read a 40-line one.

Write a discipline contract, not a wish list

Claude Code follows instructions frighteningly well, and that cuts both ways. Tell it "write good code" and it will be confidently, grammatically wrong.

An AGENTS.md contract fixes that. Start with a baseline of rules: think before you act, take small verifiable steps, never claim what you haven't verified, no drive-by refactoring. Then add a verification ladder with six rungs. Does it compile? Does the changed behavior work? Does it break anything adjacent? Does it follow the codebase's conventions? Does it hold at the boundaries? Is it observable in production? The first three are mandatory for every change.

Then the failure protocol, which is the line that pays for itself:

First failure: fix and re-verify. Second failure: re-derive, your mental model is wrong, form at least two new hypotheses. Third failure: stop, revert to last known-good, document, and re-approach from a different angle.

Agents iterate fast and they'll happily burn tokens on a broken hypothesis. A rule that forces a stop is cheap insurance.

Rules that actually change output

The discipline that matters most lives in the specific rules. From the sample TypeScript file:

Never use any. When you cannot name a type, use unknown and narrow it with type guards before use.
Never suppress errors with @ts-ignore / @ts-expect-error.
Type every function signature explicitly, parameters and return types.
Handle every branch of a discriminated union with exhaustiveness checking.

The last one is a typed-error pattern that converts future bugs into compile errors:

type OrderStatus = "pending" | "approved" | "rejected" | "refunded";

function handleStatus(status: OrderStatus) {
  switch (status) {
    case "pending":  return queueForReview();
    case "approved": return fulfill();
    case "rejected": return notifyCustomer();
    default:         return assertNever(status);
  }
}

function assertNever(x: never): never {
  throw new Error(`Unexpected: ${x}`);
}

Add a fifth status and the build fails until every case is handled. The agent can't silently skip it, and neither can you.

Errors get the same treatment. catch (e) {} is an anti-pattern; the sample rule says log, rethrow, or return an explicit error, never swallow. And e is unknown, so narrow it with a type guard before touching it. That one habit removes a whole class of silent production failures.

Testing that proves behavior

Tests are where agents generate the most waste. The sample testing file sets the standard: test behavior through public interfaces, name tests after the behavior they prove, and assert on outcomes, not calls. Write the assertion first, then the code that makes it pass. That's the closest thing to TDD an agent can follow mechanically. A good name reads like a spec:

it("rejects orders above the account credit limit", () => {
  const result = placeOrder({
    userId: "u1",
    totalCents: 900_000,
    creditLimitCents: 100_000,
  });
  expect(result).toMatchObject({
    status: "rejected",
    reason: "credit_limit_exceeded",
  });
});

And the hard rule: every bugfix ships with a regression test that fails on the old code and passes on the fix. If you can't write one, you haven't understood the bug.

Try it on your own project

The files quoted above, plus the full AGENTS.md contract, are free. Drop them in a repo and watch what your agent does differently. If the structure holds up for you the way it did for me, the full pack extends it to 24 files across frontend, backend, testing, DevOps, database and agent workflows, with project templates and a one-command installer.

Free sample: https://github.com/DaymondHyper/agentforge
Full pack ($29 one-time, no subscription): https://dedyclan.gumroad.com/l/agentforge