Skip to content

Instantly share code, notes, and snippets.

@alirezarezvani

alirezarezvani/CLAUDE.md

Created June 3, 2026 12:34
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save alirezarezvani/75161f5c44d09757d999a10408f8c934 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save alirezarezvani/75161f5c44d09757d999a10408f8c934 to your computer and use it in GitHub Desktop.
Download ZIP
CLAUDE.md A practical working guide for coding with LLM agents - Inspired by Andrej Karpathy principals
Raw
CLAUDE.md

CLAUDE.md

A practical working guide for coding with LLM agents
Inspired by Andrej Karpathy’s workflow principles

Coding Workflow Principles

1. Plan Mode First

  • Use plan mode for any non-trivial task
  • Write detailed specs up front
  • Reduce ambiguity before writing code
  • Use a lightweight inline plan for smaller tasks

2. Verify Relentlessly

  • Watch like a hawk in a good IDE
  • Check assumptions, edge cases, and tradeoffs
  • Run tests, review diffs, and verify correctness
  • Don’t blindly accept — stay in the loop

3. Keep It Simple

  • Avoid overengineering and bloated abstractions
  • Prefer 100 lines over 1000
  • Clean up dead code and cruft
  • Ask: “Is there a simpler way?”

4. Surgical Edits Only

  • Change only what’s necessary
  • Don’t touch unrelated code or comments
  • Don’t “improve” things that aren’t broken
  • Minimize side effects and churn

5. Goal-Driven Execution

  • Give clear success criteria
  • Write tests first, then make them pass
  • Use tools (e.g. browser, MCP, IDE) in the loop
  • Let the agent iterate until the goal is met

6. Parallelize with Subagents

  • Offload research, exploration, and analysis
  • Use subagents to keep context clean
  • One task per subagent for focus
  • Merge results back with judgment

Core Principles

  • Simplicity First: Minimal code that solves the problem. Nothing speculative.
  • No Laziness: Find root causes. No temporary fixes. Operate at senior developer standards.
  • Minimal Impact: Only touch what’s necessary. No side effects. No new bugs.

Engineer Mindset

Tenacity

Agents never get tired.
Relentless iteration beats giving up.
Stamina is a force multiplier.

Leverage

Give success criteria and watch it go.
Imperative → Declarative.
Multiply your leverage.

Fun

Remove drudgery, focus on creativity.
More courage, less blocking.

Atrophy

Writing and reading code are different.
Stay sharp intentionally.

Speedups ≠ Just Faster

Do more, not just faster.
Expand what you can build, not just how quickly.

Slopocalypse

Brace for AI slop in 2026.
Hype will be loud.
Signal requires judgment.

Questions to Keep Asking

  • What happens to the 10X engineer gap?
  • Do generalists increasingly outperform specialists with LLMs?
  • What will LLM coding feel like in the future?
    (StarCraft? Factorio? Music?)
  • How much of society is bottlenecked by digital knowledge work?

TL;DR

LLM agent capabilities — especially Claude and Codex — crossed a threshold of coherence around December 2025.

This marks a phase shift in software engineering.

Intelligence is ahead — integrations, workflows, and diffusion must catch up.

2026 will likely be a high-energy year as the industry metabolizes this new capability.

Suggested Usage

Use this file as a working contract for AI-assisted software development:

  • attach it to repos as CLAUDE.md
  • include it in project onboarding
  • use it as a prompt anchor for agentic coding sessions
  • share it as a team operating guide

Short Version

If you only remember a few things, remember these:

  1. Plan before coding
  2. Verify everything
  3. Keep it simple
  4. Edit surgically
  5. Define success clearly
  6. Use subagents deliberately
  7. Stay judgment-heavy, not hype-heavy
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment