lubeengineering

AI Reference

Claude.md / AGENTS.md Reference

CLAUDE.md and AGENTS.md are instruction files that define how an engineering agent should operate in your codebase. They act as a local operating manual: standards, workflow rules, verification requirements, and project constraints.

In practice, teams often use CLAUDE.md for repo-level behavior and AGENTS.md for folder-level overrides or specialization. The exact filename and lookup behavior can vary by tool, but the design principles remain the same.

Last updated: 2026-03-11

Purpose and Benefits

Consistency

Enforces stable behavior across tasks so output quality does not depend on session luck.

Speed

Reduces repeated clarifications by encoding defaults once (testing, coding style, scope boundaries).

Quality

Makes verification mandatory and prevents “done” from meaning “just coded.”

Scale

Lets multiple engineers or agents follow one shared operating model without drifting standards.

How To Create and Use

  1. 1. Define your defaults first: planning rules, code standards, and required validation commands.
  2. 2. Put global rules in repo-level CLAUDE.md.
  3. 3. Add folder-level AGENTS.md only when local behavior truly differs.
  4. 4. Keep rules concrete and testable. Replace vague guidance with explicit checklists.
  5. 5. After user corrections or regressions, update these files so mistakes do not repeat.
  6. 6. Review instruction files during onboarding and major architecture changes.

1. Plan Mode Default

What this section does

Use planning for non-trivial work, stop and re-plan when you go off track, and write clear specs before coding.

Why it is useful

This prevents random implementation drift. Planning turns unclear work into checkable steps and catches misunderstandings early, which lowers rework and defects.

2. Subagent Strategy

What this section does

Use subagents for research, parallel analysis, and focused execution when problems are complex.

Why it is useful

Separating tasks keeps context cleaner and improves quality. You avoid mixing exploration, implementation, and review into one noisy stream.

3. Self-Improvement Loop

What this section does

After user corrections, capture lessons, convert them into rules, and review those lessons before future work.

Why it is useful

Without this loop, teams repeat the same mistakes. A lessons file turns one-off corrections into institutional memory.

4. Verification Before Done

What this section does

Do not mark tasks complete until behavior is proven with tests, logs, and practical validation.

Why it is useful

This enforces outcome-based completion instead of activity-based completion. It reduces false positives where code compiles but behavior is wrong.

5. Demand Elegance (Balanced)

What this section does

For non-trivial work, pause to choose cleaner solutions; for simple fixes, avoid over-engineering.

Why it is useful

Balanced quality controls prevent two common failure modes: hacks that become tech debt, and overbuilt solutions for tiny problems.

6. Autonomous Bug Fixing

What this section does

When given a bug report, diagnose from evidence (logs/tests/errors) and drive resolution with minimal user hand-holding.

Why it is useful

This speeds up debugging and reduces user overhead. The agent behaves like an engineer who can execute independently while still being transparent.

Task Management

What this section does

Plan first, verify plan, track progress, explain changes, document outcomes, and capture lessons.

Why it is useful

Task-management rules make work auditable and easier to hand over. Anyone can understand what was planned, what changed, and why.

Core Principles

What this section does

Prefer simple solutions, avoid laziness, and fix root causes rather than papering over symptoms.

Why it is useful

These principles improve long-term maintainability. They bias implementation toward minimal, durable, high-confidence solutions.

Starter Templates

Start with these templates, then tune them for your stack, architecture, and team conventions.

CLAUDE.md template

# CLAUDE.md

## Purpose
- Defines how the agent should operate in this repository.
- Optimizes for consistency, quality, and predictable delivery.

## Plan Mode (Default)
- Use a plan for any non-trivial task (3+ steps or architectural decisions).
- If implementation diverges, stop and re-plan.
- Validate assumptions before writing code.

## Execution Strategy
- Split complex work into focused sub-tasks.
- Keep one concern per task (research, implementation, validation).
- Prefer deterministic steps with clear completion criteria.

## Verification Standard
- Do not mark work complete without proof.
- Run targeted tests and type checks.
- Confirm expected behavior, not just compilation success.

## Task Workflow
1. Plan work with checkable items.
2. Implement incrementally.
3. Report progress with concrete outcomes.
4. Capture lessons after corrections.

## Core Principles
- Keep solutions as simple as possible.
- Prefer root-cause fixes over temporary patches.
- Avoid over-engineering on small changes.

AGENTS.md template

# AGENTS.md

## Scope
- Applies to this folder and descendants.
- Overrides or extends root-level agent policies when necessary.

## Local Rules
- Respect module boundaries in this directory.
- Keep changes small and focused.
- Use existing patterns before introducing new abstractions.

## Required Validation
- Run unit tests for touched logic.
- Run type checks for affected packages.
- Verify user-visible behavior with concrete examples.

## Coding Standards
- Use descriptive naming and object parameters for app-owned functions.
- Add short, useful comments only where intent is non-obvious.
- Keep functions cohesive and easy to reason about.

## Handoff Notes
- Summarize what changed.
- List validation commands executed.
- Record follow-up tasks if scope was intentionally deferred.