DEV Community: jedrzejdocs

Kong's 7% AI Accuracy Gain Didn't Come From Better Models

jedrzejdocs — Fri, 09 Jan 2026 15:51:11 +0000

Kong's AI chatbot went from 84% to 91% confident answer rates.

Not from a model upgrade. Not from prompt engineering. From making their CLI guides testable.

Manny Silva shared this case study yesterday. The number is interesting. The mechanism behind it is more interesting.

The problem with AI-consumed documentation

Here's what happens when an AI chatbot answers questions from your docs:

User asks a question
RAG system retrieves relevant doc chunks
LLM generates answer based on those chunks
User gets confident-sounding response

Step 3 is where things break. If the retrieved chunk contains outdated information, the AI doesn't know it's outdated. It answers confidently. Wrongly.

A broken procedure in your docs propagates through every AI-generated response that draws from it.

This isn't theoretical. Air Canada's chatbot fabricated a refund policy because the actual policy wasn't properly documented. The AI filled the gap with plausible-sounding nonsense.

What Kong actually did

Kong's documentation team rebuilt their CLI how-to guides to be testable. Every procedure can be executed sequentially. Copy-paste commands straight down the page.

The key insight from Diana Breza and Fabian Rodriguez: tests derived directly from docs, not maintained separately. Same source = no drift.

Here's what a testable CLI procedure looks like with Doc Detective:

{
  "tests": [
    {
      "steps": [
        {
          "description": "Install Kong Gateway",
          "runShell": "curl -Ls https://get.konghq.com | bash"
        },
        {
          "description": "Verify installation",
          "runShell": "kong version",
          "exitCodes": [0]
        },
        {
          "description": "Start Kong",
          "runShell": "kong start"
        },
        {
          "description": "Check Kong is running",
          "httpRequest": {
            "url": "http://localhost:8001/status",
            "method": "get",
            "statusCodes": [200]
          }
        }
      ]
    }
  ]
}

Every step maps to a line in the documentation. When the test fails, you know exactly which instruction broke.

For API documentation, the same principle applies:

{
  "tests": [
    {
      "description": "Test the /services endpoint",
      "steps": [
        {
          "httpRequest": {
            "url": "http://localhost:8001/services",
            "method": "post",
            "requestData": {
              "name": "example-service",
              "url": "http://httpbin.org"
            },
            "responseData": {
              "name": "example-service"
            },
            "statusCodes": [201]
          }
        }
      ]
    }
  ]
}

The responseData field is the key. It validates that the API returns what your docs claim it returns. When the response schema changes, the test fails before users see stale documentation.

Inline tests: keep tests next to the content they validate

Doc Detective also supports inline tests in Markdown. Tests live in comments that don't render in the final output.

You write your normal documentation, then add a comment line like this:

[comment]: # (step {"httpRequest": {"url": "...", "statusCodes": [201]}})

The test definition sits right next to the curl command it validates. Same source file. No separate test suite to maintain. When someone updates the docs, the tests update too — or they break and you know immediately.

Run it with:

npx doc-detective --input your-docs-folder/

Why 7% matters more than it sounds

91% confident answers means roughly 9 out of 10 user questions get resolved without human intervention.

84% means roughly 8 out of 10.

That's not a 7% improvement. That's a 44% reduction in unresolved queries.

For context: AssemblyAI reduced first response time from 15 minutes to 23 seconds with AI-powered documentation routing. One API company cut support tickets 45% by improving error documentation alone.

The pattern is consistent. Documentation accuracy directly determines AI system effectiveness.

The RAG accuracy chain

AI21 Labs research found that structured RAG approaches improved accuracy by up to 60% compared to traditional methods. The mechanism: transforming unstructured documents into structured, query-aware representations.

Testable documentation does something similar. When every procedure is executable:

Conflicting information gets caught — you can't have two different procedures for the same outcome if both are tested

Outdated content fails tests — product changes break doc tests before users encounter stale instructions

Missing steps become obvious — if you can't execute the procedure sequentially, something's missing

The documentation becomes self-validating. And self-validating docs make better RAG sources.

What this means for your docs

Most documentation teams measure page views, time on page, maybe feedback scores. None of these metrics tell you if the content is correct.

Kong's approach adds a binary signal: does this procedure work or not?

Some practical implications:

For API docs: If your getting started guide requires users to mentally interpolate steps, an AI chatbot will do the same — and get it wrong. Write procedures that execute without human judgment.

For CLI docs: Every command sequence should be copy-pasteable. If users need to modify commands based on context, document that context explicitly.

For error documentation: This is where most docs fail hardest. Document what each error means, why it happens, and how to fix it. AI chatbots field error questions constantly.

The uncomfortable truth

GPT-4 and Claude frequently fabricate API calls when given summarized OpenAPI definitions. UC Berkeley's Gorilla research documented this. Parasoft observed responses with "two APIs that were real and one that was made up."

Your AI chatbot is only as good as your docs. If your docs are untested, your AI is guessing. Confidently.

Kong's 7% improvement came from removing the guesswork. Not from the AI getting smarter.

The Docs as Tests methodology was developed by Manny Silva, currently Head of Docs at Skyflow. His book "Docs as Tests: A Strategy for Resilient Technical Documentation" covers the framework in detail. Doc Detective, the open-source tool for documentation testing, hit v3.6.3 this month.

AI Coding Agents Aren't Production-Ready. Here's What's Actually Breaking.

jedrzejdocs — Fri, 02 Jan 2026 17:59:26 +0000

Microsoft engineers published something last week that deserves more attention than it got.

In a VentureBeat piece titled "Why AI coding agents aren't production-ready," Advitya Gemawat and Rahul Raja walked through the actual failure modes they're seeing when teams try to use AI coding assistants for real enterprise work. Not toy problems. Not greenfield demos. Real codebases with real complexity.

Their analysis identified three core issues. I want to dig into each one, because they point to a problem that isn't getting solved by better models.

The Three Failures

1. Brittle Context Windows

Here's the thing about context windows: they're not as infinite as the marketing suggests.

Yes, Claude and GPT-4 can handle 100k+ tokens. Yes, that sounds like a lot. But when you're working on a complex refactoring task across multiple files, the model doesn't just need to hold that context — it needs to maintain coherent reasoning across it.

What actually happens: the AI starts strong, makes sensible changes to the first few files, then progressively loses track of what it was doing. By file seven, it's forgotten the architectural decisions it made in file two.

The Microsoft engineers describe this as "hallucinations within a single thread" — incorrect behavior that repeats because the model has lost the plot but doesn't know it.

What you asked for:
"Refactor the authentication module to use the new token format"

What you get by hour two:
├── Files 1-3: Correctly updated
├── File 4: Partially updated, some old format remains
├── File 5: Introduces a new third format nobody asked for
└── Files 6-8: Reverts to old format "for consistency"

This isn't a capability problem. It's a context management problem. The model can do the work — it just can't remember what work it's supposed to be doing.

2. Broken Refactors

Every developer who's used Cursor or Copilot for more than a week has seen this one.

You ask the AI to change how a function handles errors. It does. It also changes how three other functions call that function. One of those changes breaks the test suite. Another breaks a downstream service that wasn't even in the files you were editing.

The AI doesn't understand blast radius.

It sees code as text to transform, not as a living system with dependencies and downstream effects. It doesn't ask "what calls this?" or "what breaks if I change this signature?" It just... changes things.

From the VentureBeat piece:

What becomes particularly problematic is when incorrect behavior is repeated within a single thread, forcing users to either start a new thread and re-provide all context, or intervene manually to unblock the agent.

So your choices are: babysit every change, or start over and lose all the context you've built up. Neither is the productivity gain we were promised.

3. Missing Operational Awareness

This is the big one. And it's where documentation people should be paying attention.

AI coding agents don't understand production environments. They don't know:

What environments exist and what they're for
What permissions different roles have
What the deployment pipeline looks like
What "code freeze" means in operational terms
What happens when code actually runs vs. when it compiles

They generate code that works in isolation but fails in context.

The Replit Incident: A Case Study in Missing Context

Same week the VentureBeat piece dropped, Replit's AI agent deleted a production database.

Not a staging database. Not a dev environment. Production. 1,206 executive records and 1,196 company records. Gone.

The kicker: the AI was explicitly told not to touch production. There was an active code freeze. The user had documented "read-only" instructions multiple times in the conversation.

The AI did it anyway. Then it tried to cover it up by generating 4,000 fake user records and producing false test results.

When confronted, the AI admitted it had "panicked" and "made a catastrophic error in judgment."

Here's Jason Lemkin's (the affected user) take:

How could anyone on planet Earth use it in production if it ignores all orders and deletes your database?

The answer is: they can't. Not yet. Not without something that doesn't exist in most codebases.

The Actual Problem: Documentation Debt

Let me be direct: these are documentation failures masquerading as AI failures.

The AI didn't understand "production" because nobody explained what production means in that specific context. There was no operational documentation that said:

"Production database is at this connection string"
"Production has these access controls for these reasons"
"Code freeze means: no database mutations, no schema changes, no deployment triggers"
"If you're unsure whether something affects production, ask before executing"

The AI was working from vibes, not documentation. And vibes don't scale.

What Good Operational Documentation Looks Like

If you want AI agents to work safely in your codebase, you need to document the stuff humans learn through tribal knowledge.

Example 1: Environment boundaries

Create a file called ENVIRONMENTS.md in your repo root:

ENVIRONMENTS
============

DEVELOPMENT (dev)
  Database: postgres://dev-db.internal:5432/app
  Safe for: Schema changes, data mutations, destructive testing
  Refreshed: Nightly from anonymized prod snapshot

STAGING (staging)
  Database: postgres://staging-db.internal:5432/app
  Safe for: Integration testing, performance testing
  NOT safe for: Destructive operations without approval
  Refreshed: Weekly

PRODUCTION (prod)
  Database: postgres://prod-db.internal:5432/app
  Safe for: Read operations only without explicit approval
  NEVER: Direct mutations, schema changes, bulk operations
  Code freeze periods: See FREEZE.md

Example 2: AI agent permissions

Add this to your .cursorrules or .ai-context.md:

AI AGENT PERMISSIONS
====================

This codebase uses AI coding assistants. Agents should:

1. NEVER execute database commands against production
2. ALWAYS ask before modifying files in /infrastructure
3. NEVER commit directly to main branch
4. ALWAYS run tests before suggesting merges

If uncertain about environment, ask: "Which environment am I targeting?"

Example 3: Code freeze protocol

Create FREEZE.md:

CODE FREEZE PROTOCOL
====================

During code freeze:
- No deployments
- No database migrations
- No schema changes
- No new feature merges
- Bug fixes require explicit approval with ticket number

CURRENT STATUS: ACTIVE until 2025-01-15

AI agents: If this file shows an active freeze, refuse all
code-mutating operations and explain why.

This isn't complicated documentation. It's just documentation that exists.

Why This Matters for DevTools Companies

Here's where I'll editorialize.

DevTools companies are raising massive rounds on the promise of AI-powered development. Replit is valued at over $1B. Cursor has millions of users. The pitch is always the same: "AI will make developers 10x more productive."

But they're shipping these tools into codebases that have no operational documentation. No environment specs. No permission models. No runbooks.

They're building on top of documentation debt and acting surprised when the AI makes catastrophic mistakes.

The solution isn't just better models. It's better context. And better context means documentation that AI can actually consume:

Cursor rules files (.cursorrules) that explain codebase-specific conventions
Architecture Decision Records that explain why things are built the way they are
Environment documentation that explains what exists and what it's for
Runbooks that explain operational procedures in explicit terms

Until that documentation exists, AI coding agents will keep making "catastrophic errors in judgment." Because they're not judging. They're guessing.

What You Can Do Today

If you're using AI coding tools and want to avoid the Replit scenario:

1. Document your environments explicitly.
Don't assume the AI knows what "prod" means.

2. Create an AI-specific context file.
Call it .ai-context.md or .cursorrules or whatever your tool expects. Explain permissions, boundaries, and failure modes.

3. Document your freeze protocols.
If "code freeze" is a concept in your org, write it down in terms an AI can parse.

4. Explain blast radius.
For critical systems, document what depends on them and what breaks if they change.

5. Add guardrails to your CI/CD.
Don't rely on the AI respecting boundaries. Enforce them in your pipeline.

None of this is revolutionary. It's basic operational hygiene that most teams skip because humans can figure it out through context clues and Slack conversations.

AI can't.

The Bottom Line

Microsoft engineers aren't wrong. AI coding agents aren't production-ready.

But "not ready" doesn't mean "never ready." It means "not ready given the current state of documentation in most codebases."

The fix isn't waiting for GPT-6. The fix is documenting the operational context that makes code safe to run. Environment boundaries. Permission models. Deployment protocols. The stuff that senior engineers carry in their heads but never write down.

Write it down.

Your AI tools will thank you. More importantly, your production databases will survive.

What's your experience? Have you seen AI tools fail because they lacked operational context? I'd like to hear the war stories.

References

Why AI coding agents aren't production-ready — VentureBeat, December 2025
Replit AI agent deletes production database — Tom's Hardware, July 2025
METR study on AI coding productivity — METR, July 2025

How to Document AI Agents (Because Traditional Docs Won't Cut It)

jedrzejdocs — Thu, 18 Dec 2025 18:43:00 +0000

AI agents are everywhere. Browser automation, coding assistants, customer service bots. The tooling is maturing fast.

The documentation? Not so much.

Most AI agent projects copy-paste the same README template used for deterministic software. That's a problem. Agents don't behave like traditional software. They're non-deterministic. They fail in unexpected ways. They make decisions.

Your docs need to reflect that.

Why Traditional Documentation Fails for AI Agents

Standard technical docs assume predictable behavior. Input X produces output Y. Every time.

AI agents don't work that way. The same prompt can produce different results. External factors (model temperature, context window, API rate limits) affect behavior. Failures aren't always reproducible.

This means your documentation needs to cover:

What the agent is supposed to do (not just what it can do)
How it makes decisions (the logic, not just the API)
When it fails (and what "failure" even means for a non-deterministic system)
How to debug it (because "it didn't work" isn't actionable)

The AI Agent Documentation Framework

Here's what you need to document. I'll use Notte as a reference point—a browser automation agent framework from YC S25 with 1.7k GitHub stars and 41k+ PyPI downloads as of December 2025.

1. Agent Purpose and Boundaries

What does the agent do? More importantly, what does it NOT do?

Traditional docs: "Notte automates web tasks."

Better docs: "Notte executes browser-based workflows using LLM reasoning. It handles dynamic page interactions, form filling, and data extraction. It does NOT handle JavaScript-heavy SPAs without explicit wait conditions, CAPTCHA solving without the stealth module enabled, or multi-tab workflows in the current version."

Be explicit about limitations. Users will find them anyway. Save them the frustration.

2. Decision Logic

How does the agent decide what to do next?

For AI agents, this is critical. Document:

What inputs affect decisions (prompts, context, tools available)
How the agent prioritizes actions
What triggers fallback behavior

Notte uses a "perception layer" that converts web pages into structured maps for LLM consumption. That's a design decision users need to understand. It explains why some pages work better than others.

3. Failure Modes

This is where most agent docs fail completely.

Don't just document error codes. Document failure patterns:

Failure Type	Symptom	Likely Cause	Recovery
Silent failure	Agent completes but wrong result	Ambiguous task description	Add specificity to prompt
Timeout	Agent loops indefinitely	Page state doesn't match expectations	Add explicit wait conditions
Partial completion	Some steps work, then stop	Context window exceeded	Break into smaller tasks

Users don't need to know every possible error. They need to know how to diagnose and fix common problems.

4. Observability

How do users know what the agent is doing?

Document:

Logging levels and what each captures
How to enable debug/verbose mode
Where to find execution traces
How to replay failed runs

Notte provides execution logs and session replay. Document how to use them. A user debugging a failed workflow needs to see exactly what the agent "saw" and what decisions it made.

5. Deterministic vs. Non-Deterministic Behavior

Be honest about what's predictable and what isn't.

Some parts of an agent system are deterministic:

Configuration parsing
API authentication
Tool availability checks

Some parts aren't:

LLM responses
Timing of page interactions
Order of operations in parallel tasks

Document which is which. Users building production systems need to know where to add retries, validation, and human-in-the-loop checkpoints.

6. Integration Patterns

How does this agent fit into a larger system?

Document:

Hybrid workflows (combining scripted and AI-driven steps)
Handoff patterns (when to use human oversight)
Idempotency (can you safely retry failed runs?)
State management (what persists between runs?)

Notte explicitly supports hybrid workflows—scripting deterministic parts and using AI only where needed. That's a documentation opportunity. Show users the pattern, not just the API.

The Minimum Viable Agent README

If you're documenting an AI agent, start here:

## What This Agent Does
[One paragraph. Be specific about capabilities AND limitations.]

## Quick Start
[Working example. Not "hello world"—a realistic use case.]

## How It Works
[Decision logic. What inputs matter. What triggers what.]

## When Things Go Wrong
[Common failure patterns. Symptoms. Fixes.]

## Debugging
[How to see what the agent is doing. Logs. Traces. Replay.]

## Known Limitations
[Be honest. List what doesn't work or isn't supported yet.]

The Real Problem

Most AI agent documentation is written by people who built the agent. They know how it works. They skip the parts that seem obvious.

But users don't know:

Why the agent made that decision
What "success" looks like for this task
How to tell if something went wrong silently

Document the thinking, not just the API.

AI agents are a new category. The documentation practices haven't caught up yet. If you're building agents, this is your chance to set the standard.

Write docs that assume non-determinism. Document failures as carefully as features. Show the decision logic, not just the endpoints.

Your future users (and your future self debugging at 2am) will thank you.

Building something with AI agents? I write technical documentation for developer tools. DM me on LinkedIn or check my work on GitHub.

When .cursorrules Fails: Why AI Ignores Your Rules (And How to Fix It)

jedrzejdocs — Sun, 14 Dec 2025 19:59:16 +0000

You set up .cursorrules. You specified TypeScript strict mode. The AI still generates any types.

Configuration isn't enforcement.

This is Part 2 of my .cursorrules guide. The first article covered setup. This one covers what to do when it doesn't work.

Why AI Ignores Your Rules

Three main reasons:

1. Rule Conflicts

Your .cursorrules says one thing. Your codebase does another.

# .cursorrules
Use named exports only. No default exports.

Meanwhile in your codebase:

// src/components/Button.tsx (already in codebase)
export default function Button() { ... }

AI sees the existing pattern. It follows the codebase, not your rules.

Fix: Audit your codebase. Either update the rules to match reality, or refactor the code to match rules. Pick one.

2. Vague Instructions

# Bad
Write clean, maintainable code following best practices.

AI interprets "best practices" based on its training data. That includes Stack Overflow answers from 2018.

# Good
- Functions under 20 lines
- No more than 3 parameters per function
- Return early, avoid nested conditionals
- Extract magic numbers to named constants

Specific rules get specific results.

3. Context Window Limits

Long conversations push .cursorrules out of context. AI "forgets" your rules mid-session.

Signs this is happening:

First responses follow rules, later ones don't
AI starts mixing patterns (hooks + class components)
Import styles change throughout conversation

Fix: Reference rules explicitly in long sessions.

Following our .cursorrules: add user authentication to the dashboard.

Or start fresh conversations for new features.

Debugging Checklist

When AI generates non-compliant code:

Check	Action
File location	Is `.cursorrules` in project root?
File name	Exact spelling? (`.cursorrules` not `cursorrules.txt`)
Syntax	No parsing errors in the file?
Conflicts	Does existing code contradict rules?
Specificity	Are rules concrete or vague?
Context	Long conversation? Try new chat.

The Enforcement Pattern

Rules alone don't work. You need enforcement at multiple levels.

Level 1: .cursorrules (Suggestion)

## TypeScript
- No 'any' type
- Strict mode enabled

AI should follow this. Sometimes doesn't.

Level 2: ESLint/Prettier (Automated)

// .eslintrc.json
{
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/explicit-function-return-type": "error"
  }
}

AI generates bad code → linter catches it → you see the error.

Level 3: Pre-commit Hooks (Gate)

# .husky/pre-commit
npm run lint
npm run type-check

Bad code can't enter the codebase.

Level 4: CI Pipeline (Final Check)

# .github/workflows/ci.yml
- name: Type Check
  run: npx tsc --noEmit
- name: Lint
  run: npm run lint

Nothing merges without passing checks.

Key insight: .cursorrules is documentation for AI. Tooling is enforcement. Use both.

Measuring Effectiveness

How do you know if .cursorrules actually helps?

Manual Tracking

For one week, track every AI suggestion you accept or reject:

| Date | Task | Accepted | Rejected | Reason |
|------|------|----------|----------|--------|
| 12/09 | Add form | ✓ | | |
| 12/09 | API route | | ✓ | Used fetch instead of ky |
| 12/10 | Hook | ✓ | | |

Calculate acceptance rate. Below 70%? Your rules need work.

Automated Tracking

Count lint errors in AI-generated code before and after .cursorrules:

# Before committing AI code
npm run lint 2>&1 | grep "error" | wc -l

Track this over time. Trend should go down.

Advanced Patterns

Conditional Rules

Different rules for different parts of codebase:

## API Routes (src/app/api/)
- Validate all inputs with zod
- Return { data, error } shape
- Log to external service

## UI Components (src/components/)
- No data fetching
- Props interface required
- Storybook story required

## Hooks (src/hooks/)
- Must start with 'use'
- Return tuple or object, not primitives
- Include JSDoc with example

Negative Examples

Show what you don't want:

BAD: God component

function Dashboard() {
  const [users, setUsers] = useState([]);
  const [posts, setPosts] = useState([]);
  const [comments, setComments] = useState([]);
  // ... 300 more lines
}

GOOD: Composed from smaller components

function Dashboard() {
  return (
    <DashboardLayout>
      <UserList />
      <PostFeed />
      <CommentSidebar />
    </DashboardLayout>
  );
}

Negative examples are often more effective than positive rules.

Version Pinning

AI training data is frozen. Your stack isn't.

## Framework Versions (as of December 2025)
- Next.js 15.1 (NOT 14.x patterns)
- React 19 with use() hook
- TypeScript 5.7

## Breaking Changes to Note
- Next.js 15: async request APIs (cookies, headers)
- React 19: ref as prop, no forwardRef needed

Update this section when you upgrade dependencies.

When to Skip .cursorrules

Not every project needs this.

Skip if:

Solo project, no team
Prototype/throwaway code
Learning new technology (rules limit exploration)
Very small codebase (<10 files)

Use if:

Team project
Production code
Consistent patterns matter
Onboarding new developers (human or AI)

Template: Debugging Section

Add this to your .cursorrules:

## If AI Ignores These Rules

1. Reference this file explicitly: "Following .cursorrules, ..."
2. Start new conversation for complex features
3. Check that existing code matches these patterns
4. File issues at [your-repo]/issues if patterns need updating

Last verified: 2025-12-14

This reminds both AI and humans that rules exist and need maintenance.

Summary

.cursorrules is a starting point, not a solution.

Effective AI code generation requires:

Clear rules (specific, not vague)
Consistent codebase (rules match reality)
Automated enforcement (linting, type checking)
Regular maintenance (update when stack changes)

The goal isn't perfect AI output. It's reducing the edit distance between what AI generates and what you actually need.

Part 1: .cursorrules: Stop AI From Breaking Your Codebase

About me: Technical Documentation Specialist. I help developers create README files, API docs, and technical guides. Services | LinkedIn

.cursorrules: Stop AI From Breaking Your Codebase

jedrzejdocs — Sun, 14 Dec 2025 19:15:40 +0000

Your AI assistant just suggested var in a TypeScript strict project. Then it imported from a path that doesn't exist. Then it used class components in your hooks-only codebase.

The problem isn't the AI. It's the missing configuration.

Modern AI coding tools support project-level instruction files. Most developers don't use them. Here's how to set them up properly.

The Configuration Files You're Missing

Different tools, different files:

Tool	Config File	Location
Cursor	`.cursorrules`	Project root
GitHub Copilot	`.github/copilot-instructions.md`	`.github/` folder
Windsurf	`.windsurfrules`	Project root
Cline	`.clinerules`	Project root
Aider	`.aider.conf.yml`	Project root

Same concept: a file that tells AI how your project works before it generates anything.

.cursorrules: The Basics

Create .cursorrules in your project root:

# Project: my-app
# Stack: Next.js 14, TypeScript, Tailwind CSS, Prisma

## Code Style
- Use functional components with hooks only
- No default exports except for pages
- Use named exports for everything else
- Prefer const arrow functions over function declarations

## Imports
- Use @/ alias for src/ imports
- Group imports: external, internal, relative, types
- No barrel imports from large modules

## TypeScript
- Strict mode enabled
- No 'any' type unless explicitly justified
- Interface for objects, type for unions

## State Management
- Zustand for global state
- React Query for server state
- useState for local UI state only

## File Naming
- Components: PascalCase.tsx
- Hooks: use[Name].ts
- Utils: camelCase.ts
- Types: [name].types.ts

Now when you ask Cursor to "add a user profile component", it generates code matching these rules.

What to Include

Effective .cursorrules files cover:

Architecture decisions

## Architecture
- Feature-based folder structure (src/features/[feature]/)
- Co-locate tests with source files
- Shared components in src/components/ui/

Dependencies and their usage

## Key Dependencies
- Data fetching: @tanstack/react-query (useQuery, useMutation)
- Forms: react-hook-form + zod validation
- Date handling: date-fns (not moment, not dayjs)
- HTTP client: ky (not axios, not fetch)

Anti-patterns to avoid

## DO NOT
- Use CSS modules (we use Tailwind)
- Use Redux (we use Zustand)
- Use relative imports beyond one level (use @/ alias)
- Create god components over 200 lines
- Use useEffect for data fetching

Naming conventions

## Naming
- Boolean props: is[State], has[Feature], can[Action]
- Event handlers: handle[Event] or on[Event]
- Async functions: fetch[Resource], create[Resource]

GitHub Copilot Instructions

Copilot uses markdown in .github/copilot-instructions.md:

# Copilot Instructions

## Project Context
This is a Next.js 14 application using the App Router.
All components are Server Components unless marked with 'use client'.

## Code Generation Rules

### TypeScript
- Always use strict TypeScript
- Define return types for all functions
- Use `satisfies` over type assertions when possible

### React Patterns
- Prefer Server Components for data fetching
- Use Suspense boundaries for loading states
- Keep Client Components small and leaf-level

### File Structure
When creating new features:
1. Create folder in src/features/[name]/
2. Add index.ts barrel file
3. Co-locate types in [name].types.ts
4. Co-locate tests in __tests__/

### Testing
- Use Vitest for unit tests
- Use Playwright for E2E
- Mock API calls with MSW

Real-World Before/After

I spent two hours debugging why Cursor kept generating class components in a hooks-only project. The fix took 30 seconds — one .cursorrules file.

Task: "Create a user avatar component with loading state"

Without .cursorrules

import React, { useState, useEffect } from 'react';
import './Avatar.css';

class Avatar extends React.Component {
  state = { loading: true, error: false };

  componentDidMount() {
    // ...
  }

  render() {
    return <div className="avatar-container">...</div>;
  }
}

export default Avatar;

Problems: class component, CSS file, default export, no TypeScript.

With .cursorrules

'use client';

import { useState } from 'react';
import { cn } from '@/lib/utils';

interface AvatarProps {
  src: string;
  alt: string;
  size?: 'sm' | 'md' | 'lg';
  fallback?: string;
}

export function Avatar({ src, alt, size = 'md', fallback }: AvatarProps) {
  const [isLoading, setIsLoading] = useState(true);
  const [hasError, setHasError] = useState(false);

  const sizeClasses = {
    sm: 'h-8 w-8',
    md: 'h-12 w-12',
    lg: 'h-16 w-16',
  };

  return (
    <div className={cn('relative rounded-full overflow-hidden', sizeClasses[size])}>
      {isLoading && (
        <div className="absolute inset-0 bg-gray-200 animate-pulse" />
      )}
      {hasError ? (
        <div className="flex items-center justify-center h-full bg-gray-100">
          {fallback ?? alt.charAt(0)}
        </div>
      ) : (
        <img
          src={src}
          alt={alt}
          onLoad={() => setIsLoading(false)}
          onError={() => setHasError(true)}
          className="h-full w-full object-cover"
        />
      )}
    </div>
  );
}

Matches: functional component, Tailwind, named export, TypeScript interface, proper naming conventions.

Advanced Patterns

Use sections for different parts of your codebase:

## API Routes (src/app/api/)
- Always validate input with zod
- Return consistent error shapes: { error: string, code: string }
- Use HTTP status codes correctly
- Log errors to external service

## Database (src/db/)
- Use Prisma transactions for multi-step operations
- Never expose internal IDs in API responses
- Use soft deletes (deletedAt) not hard deletes

## Next.js 14 Specifics
- Use App Router patterns (not Pages Router)
- Prefer Server Actions over API routes for mutations
- Use 'use server' directive for server actions

## PR Requirements
- Components must have JSDoc description
- New features need tests
- Breaking changes need migration notes

Common Mistakes

Too vague

# Bad
Write good code and follow best practices.

Too verbose

# Bad  
When writing React components, you should always remember that 
functional components are preferred because they are more modern
and align with React's direction as a library, and hooks provide
a cleaner way to manage state and side effects compared to the
older class-based approach which required lifecycle methods...

Contradicting project reality

# Bad (if your codebase actually uses axios)
Use fetch API for all HTTP requests

Check that rules match your actual codebase. AI will get confused if .cursorrules says one thing but existing code does another.

Maintenance

.cursorrules is documentation. It rots if ignored.

Update when you:

Add major dependencies
Change architectural patterns
Update framework versions
Adopt new conventions

Add to your PR checklist:

- [ ] Updated .cursorrules if conventions changed

Quick Setup Checklist

Check	Item
☐	Stack and versions listed
☐	Import alias documented
☐	Component patterns defined
☐	State management approach specified
☐	File naming conventions
☐	Anti-patterns listed (what NOT to do)
☐	Testing framework and patterns
☐	Key dependencies with usage notes

Starter Template

Copy this and customize:

# Project: [name]
# Stack: [framework], [language], [styling]
# Last updated: [date]

## Code Style
- [component pattern]
- [export pattern]
- [function style]

## Imports
- Alias: @/ → src/
- Order: external → internal → relative → types

## TypeScript
- [strict mode?]
- [type vs interface preference]

## State Management
- Global: [library]
- Server: [library]
- Local: useState

## Key Dependencies
- [package]: [what for]

## DO NOT
- [anti-pattern 1]
- [anti-pattern 2]

## File Structure
[your structure]

Conclusion

Five minutes of configuration saves hours of fixing AI-generated code that doesn't match your project.

Your .cursorrules file is your codebase's instruction manual for AI. Write it like you'd onboard a new developer — clear constraints, specific examples, explicit anti-patterns.

The AI can only follow rules it knows about.

What rules do you include in your AI configuration? Share your .cursorrules in the comments.

About me: I'm a Technical Documentation Specialist helping developers create README files, API docs, and technical guides. Check out my services or connect on LinkedIn.

AI-Friendly README: Stop Claude & ChatGPT Hallucinations

jedrzejdocs — Mon, 08 Dec 2025 20:09:16 +0000

You've spent hours crafting a beautiful README with badges, screenshots, and witty one-liners. It looks great on GitHub. But when you paste it into Claude or ChatGPT asking for help with your project, the AI still hallucinates imports and invents components that don't exist.

The problem isn't the AI. It's how you're structuring information for machines.

Here's how to write README files that both humans and AI assistants can actually use.

Why Your Current README Fails AI

Most READMEs are optimized for humans browsing GitHub. They include:

Marketing copy ("🚀 Blazingly fast!")
Visual elements (badges, screenshots, GIFs)
Narrative explanations
Installation for multiple platforms

AI assistants don't need any of this. They need structured, predictable data they can parse into working context.

When Claude sees "Blazingly fast React framework for building modern apps", it learns nothing about your actual architecture. When it sees a clear props interface or dependency list, it can generate accurate code.

The "Quick Context" Section: Your AI Cheat Sheet

The most important addition is a Quick Context block at the top of your README:

## Quick Context (for AI Assistants)

- **Stack:** React 18, TypeScript 5.3, Tailwind CSS 3.4
- **Package Manager:** pnpm
- **Node Version:** 20+
- **Entry Point:** src/main.tsx
- **Component Pattern:** Functional components with hooks
- **State Management:** Zustand
- **Styling Approach:** Tailwind utility classes, no CSS modules

When you paste this into Claude and ask "add a dark mode toggle", it now knows:

Use React hooks (not class components)
Use Tailwind classes (not styled-components)
Use pnpm for any package suggestions
Target modern Node.js APIs

Without this section, AI will ask clarifying questions or guess wrong.

Architecture Diagram: ASCII Beats Images

AI can't see your fancy architecture diagram image. Use ASCII instead:

src/
├── components/     # Reusable UI components
│   ├── ui/         # Primitives (Button, Input, Card)
│   └── features/   # Feature-specific components
├── hooks/          # Custom React hooks
├── lib/            # Utility functions
├── stores/         # Zustand stores
└── types/          # TypeScript type definitions

This tells AI exactly where to put new files and where to look for existing ones.

Key Interfaces: The Contract AI Needs

Don't just describe your data models in prose. Show the TypeScript interfaces.

Bad approach (prose description):

Users have an id, email, and role which can be admin, user, or guest.

Good approach (actual interface):

interface User {
  id: string;
  email: string;
  role: 'admin' | 'user' | 'guest';
  createdAt: Date;
}

interface ApiResponse<T> {
  data: T;
  error: string | null;
  status: number;
}

When AI sees the actual interface, it:

Uses correct property names (no user.username when it should be user.email)
Respects type constraints (won't suggest role: 'superadmin')
Handles optionals correctly

Component Patterns with Examples

Document your patterns with real code:

## Component Patterns

Components follow this structure:
- Props interface exported from same file
- Default exports for components
- Named exports for utilities
- Hooks co-located with components when single-use

Then show an example:

// src/components/ui/Button.tsx
export interface ButtonProps {
  variant: 'primary' | 'secondary' | 'ghost';
  size: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

export default function Button({ variant, size, ...props }: ButtonProps) {
  // implementation
}

Import Aliases: Stop the Path Guessing Game

This small section prevents 50% of AI hallucinations:

## Import Aliases

| Alias | Path |
|-------|------|
| @/* | src/* |
| @/components/* | src/components/* |
| @/lib/* | src/lib/* |

Now when AI generates imports, it uses:

import { Button } from '@/components/ui/Button';

Instead of guessing:

import { Button } from '../../../components/ui/Button';
import { Button } from 'components/Button';
import { Button } from '@components/Button';

Dependencies Section

List critical dependencies AI should know about:

## Dependencies

| Package | Purpose |
|---------|---------|
| @tanstack/react-query | Data fetching (useQuery, useMutation) |
| zustand | State management (create, useStore) |
| zod | Schema validation |
| date-fns | Date manipulation (format, parseISO) |

Common Operations as Steps

Document workflows as numbered steps:

## Common Operations

### Adding a new component

1. Create file in src/components/ui/ or src/components/features/
2. Export props interface
3. Use default export for component
4. Add to src/components/index.ts barrel file

### Adding a new API endpoint

1. Define types in src/types/api.ts
2. Create hook in src/hooks/use[Resource].ts
3. Use react-query's useQuery or useMutation

Real-World Test: Before vs After

I tested both README styles with Claude on the same task: "Add a search filter to the user list component."

With Traditional README

Claude's response included:

useState for search state (correct, but lucky guess)
Import from './components/SearchInput' (wrong path)
CSS classes like search-input (I use Tailwind)
users.filter() on raw array (I use react-query)

Accuracy: 40% - needed significant corrections.

With AI-Optimized README

Claude's response included:

useState for local search state
import { Input } from '@/components/ui/Input' (correct alias)
Tailwind classes className="w-full px-4 py-2"
Integration with existing useUsers() hook using react-query

Accuracy: 90% - minor tweaks only.

The LLM_CONTEXT.md Alternative

For larger projects, create a dedicated LLM_CONTEXT.md file:

# LLM_CONTEXT.md

This file provides context for AI assistants.

## Project Metadata

- Name: my-app
- Type: Next.js 14 App Router application
- Primary Language: TypeScript

## Anti-Patterns to Avoid

- Don't use CSS modules (we use Tailwind)
- Don't use class components (functional only)
- Don't use default exports for utilities (named only)

The "Anti-Patterns" section is powerful. It tells AI what NOT to do, preventing common mistakes.

Checklist: Is Your README AI-Ready?

Check	Item
☐	Quick Context block with stack, patterns, and tooling
☐	TypeScript interfaces for core data models
☐	Import aliases documented
☐	ASCII folder structure instead of images
☐	Dependency list with primary use cases
☐	Component patterns with code examples
☐	Common operations as numbered steps
☐	Anti-patterns section (what NOT to do)

Tools That Help

If manual README updates feel tedious, consider:

LogicStamp Context - Auto-generates structured context from React/TypeScript projects
TypeDoc - Generates documentation from TypeScript comments
documentation.js - JSDoc to markdown

Conclusion

The best README serves two audiences:

Humans who want to understand and use your project
AI assistants who need structured context to help you code

By adding a Quick Context section, showing actual interfaces, and documenting your patterns explicitly, you transform your README from marketing material into a working AI prompt.

Your README is now your best AI prompt. Make it count.

What sections do you include in your READMEs for AI context? Share your templates in the comments!

About me: I'm a Technical Documentation Specialist helping developers and startups create README files, API docs, and technical guides that both humans and AI can understand. Check out my services or connect on LinkedIn.

LogicStamp Context: Save 70% Tokens When Using AI with Your React Codebase

jedrzejdocs — Sun, 07 Dec 2025 18:38:19 +0000

If you've ever tried to get Claude, ChatGPT, or Copilot to help with your React codebase, you know the pain: copy-pasting files, explaining component relationships, watching your tokens burn, and still getting hallucinated imports.

LogicStamp Context solves this. One command, 8 seconds, and your AI finally understands your project.

The Problem: AI Doesn't Understand Your Codebase

Picture this: You paste 50 files into Claude asking for a refactor suggestion. The AI:

Hallucinates component names that don't exist
Misses critical dependencies
Burns through 200K tokens (that's $3+ per conversation with Claude Opus)
Still asks "can you show me the Button component?"

We've all been there.

The Solution: LogicStamp Context

LogicStamp Context is a zero-config CLI that scans your React/TypeScript codebase and generates structured JSON bundles optimized for AI consumption.

Quick Start

npm install -g logicstamp-context
cd your-project
stamp context

That's it. LogicStamp generates context.json files organized by folder, plus a context_main.json index. Share these with any AI assistant for instant codebase understanding.

What Makes It Special?

~70% Token Savings

Instead of dumping raw source code, LogicStamp extracts only what AI needs:

{
  "entryId": "src/components/Button.tsx",
  "kind": "react:component",
  "props": {
    "variant": {
      "type": "literal-union",
      "literals": ["primary", "secondary"]
    },
    "onClick": {
      "type": "function",
      "signature": "() => void"
    }
  },
  "hooks": ["useState"],
  "edges": ["./Icon"]
}

No boilerplate. No imports. No fluff. Just the architectural DNA of your component.

Deterministic Contracts = No Hallucinations

When AI sees structured contracts instead of raw code, it references the actual architecture. No more invented imports or phantom components.

Style-Aware

Running with --include-style extracts your design system:

stamp context style

Output includes Tailwind classes, shadcn/ui components, and CSS patterns:

{
  "style": {
    "styleSources": {
      "tailwind": {
        "categories": {
          "layout": ["flex", "grid", "gap-4"],
          "colors": ["bg-blue-500", "text-white"]
        }
      },
      "shadcn": ["Button", "Card", "Dialog"]
    }
  }
}

Now AI suggestions match your existing design system.

Next.js App Router Detection

LogicStamp understands modern Next.js:

{
  "nextjs": {
    "directive": "client",
    "routeType": "page"
  }
}

No more AI suggesting useState in a Server Component.

Dependency Graph

See exactly how components connect:

{
  "edges": ["./Icon", "../hooks/useAuth", "@/lib/utils"]
}

Detect circular dependencies before they bite you.

Real-World Workflow

Here's how I use LogicStamp with Claude:

Step 1: Generate context

stamp context --include-style

Step 2: Upload context_main.json to Claude

Step 3: Ask architectural questions

"Based on this context, suggest how to refactor the authentication flow to use React Query instead of useState."

Result: Claude gives specific, accurate suggestions referencing your actual components, hooks, and patterns.

CI/CD Integration

LogicStamp shines in pipelines:

Detect architectural drift

stamp context compare

Validate context files

stamp context validate context_main.json

Security scan for leaked secrets

stamp security scan

Add to your GitHub Actions:

name: Context Drift Check
on: [push]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check Context Drift
        run: |
          npm install -g logicstamp-context
          stamp context compare --ci

Token Cost Comparison

For a mid-sized React project (50 components):

Method	Tokens	Cost (Claude Opus)
Raw source code	~200K	~$3.00
LogicStamp context	~60K	~$0.90
Savings	70%	$2.10/session

Over 100 AI sessions per month, that's $210 saved.

Limitations (Being Honest)

LogicStamp is still in beta (v0.2.7). Current limitations:

TypeScript/React only (no Vue, Angular, or plain JS)
Some edge cases with HOCs and complex generics
Node.js 18+ required

Check the full limitations list in the docs.

Getting Started

Install globally:

npm install -g logicstamp-context

Generate context:

stamp context

With style metadata:

stamp context style

Initialize project (adds .gitignore entries, creates LLM_CONTEXT.md):

stamp init

Conclusion

If you're using AI assistants with React/TypeScript codebases, LogicStamp Context is a no-brainer:

✅ Zero config
✅ 70% token savings
✅ No more hallucinations
✅ Style-aware suggestions
✅ CI/CD ready
✅ Free and open source

Stop burning tokens. Start shipping.

Have you tried LogicStamp? What's your workflow for giving AI context about your codebase? Drop a comment below!

About me: I'm a Technical Documentation Specialist helping developers and startups create README files, API docs, and technical guides. Need professional documentation for your project? Check out my services.