🧭 LLM Coding Guidelines

Karpathy-inspired guardrails for AI coding agents — from repeated mistakes to cleaner first attempts.

LLM Coding Guidelines is a compact set of behavioral instructions for AI coding agents. It helps Claude Code, Codex, Gemini CLI, Cursor, and similar tools avoid broken contracts, downgraded tests, blurred boundaries, miswired feature flags, speculative abstractions, and noisy diffs.

---

🌟 Key Highlights

• 🤖 Multi-agent ready: One guideline set generated for AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, and reusable skill workflows.
• 🧱 Architecture-aware: Explicit guardrails for public APIs, schemas, messaging, boundaries, and ownership.
• ✅ Test-preserving: Agents are instructed to keep integration, slice, and unit tests in their proper category.
• 🎯 Surgical by default: Changes should trace to the task, match local patterns, and avoid drive-by cleanup.

---

🚀 Quick Start

The canonical guidelines live in guidelines/core.md. Pick the generated entrypoint that matches your agent or editor:

File	Use it for
AGENTS.md	General coding agents and Codex-style workflows
CLAUDE.md	Claude Code and Claude projects
GEMINI.md	Gemini CLI
.cursor/rules/karpathy-guidelines.mdc	Cursor project rules
skills/karpathy-guidelines/SKILL.md	Reusable skill/plugin workflows
CURSOR.md	Cursor setup notes
EXAMPLES.md	Supplementary examples

Copy the file your coding tool reads by default into the target project. Keep it close to the codebase so the agent sees the same guardrails before implementing changes.

---

📂 Repository Structure

├── guidelines/
│   └── core.md                         # Canonical guideline source
├── scripts/
│   └── sync-guidelines.sh              # Regenerates tool-specific files
├── skills/
│   └── karpathy-guidelines/SKILL.md    # Reusable skill entrypoint
├── .cursor/rules/
│   └── karpathy-guidelines.mdc         # Cursor project rule
├── AGENTS.md                           # General agent / Codex entrypoint
├── CLAUDE.md                           # Claude Code entrypoint
├── GEMINI.md                           # Gemini CLI entrypoint
├── CURSOR.md                           # Cursor usage notes
└── EXAMPLES.md                         # Supplementary examples

---

🧠 Current Guidelines

1. Ground First: Inspect local truth before choosing an approach.
2. Keep Diff Narrow: Do the requested change without drive-by cleanup.
3. Protect Contracts and Boundaries: Treat public APIs, OpenAPI schemas, messages, flags, and layers as owned surfaces.
4. Keep Tests Honest: Prove behavior through the same layer the user depends on.
5. Build Simply, Finish Cleanly: Avoid speculative code, inspect the diff, and report verification.

---

🛠️ Maintaining the Guidelines

Edit only guidelines/core.md when changing the generated instructions.

Regenerate every tool-specific entrypoint:

./scripts/sync-guidelines.sh

Verify the generated files are in sync before committing:

./scripts/sync-guidelines.sh --check
git diff --check

EXAMPLES.md is supplementary. It should illustrate the guidelines, not become a second source of instructions.

---

🛡️ Why this Fork Exists

I use LLMs heavily to code features, but I noticed a costly pattern: the agent would fall into the same traps again and again. The repeated issues were not just style problems; they were architectural mistakes such as downgrading integration tests into unit tests, mismanaging OpenAPI contracts, blurring service boundaries, or wiring feature flags incorrectly.

The original Karpathy-inspired guidelines were a strong starting point for general agent behavior. This fork keeps that spirit while adding stricter guardrails for contracts, tests, boundaries, feature flags, and implementation hygiene.

---

🙏 Credits

This project builds on the upstream Karpathy-inspired guidelines and adapts them for multi-agent coding workflows with stronger architectural and testing guardrails.

---

Built for AI coding agents by Antoine Ghigny