agentleFS
abhijeetgupta23abhijeetgupta23/ai-agent-to-learn-faster-and-better/CLAUDE.md

ai-agent-to-learn-faster-and-better

CLAUDE.md4 starsChanged 21 days agoMITView on GitHub

Prefer visuals over prose in every response. Prose is boring — especially for code and technically heavy concepts. - Default to a diagram, table, flowchart, annotated code map, or rendered chart before writing paragraphs. - For architecture / data-flow / system-design questions, render an actual diagram (visualize show_widget tool or an Artifact) — don't describe it in sentences. - When explaining code, show structure visually (boxes/arrows/tables) rather than narrating it line-by-line. - Keep any accompanying prose short and summary-first. -…

The file

We split this CLAUDE.md into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Prefer visuals over prose in every response.

    line 4
  2. Distinctive:

    Default to a diagram, table, flowchart, annotated code map, or rendered chart before writing paragraphs.

    line 6
  3. Very specific:

    When explaining code, show structure visually (boxes/arrows/tables) rather than narrating it line-by-line.

    line 8
  4. Distinctive:

    Keep any accompanying prose short and summary-first.

    line 9
  5. Very specific:

    Every LLM response is parsed into a Pydantic model (src/schemas.py).

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md
<!-- vester:visual-first:start -->

Visual-first responses

Prefer visuals over prose in every response. Prose is boring — especially for code and technically heavy concepts.

  • Default to a diagram, table, flowchart, annotated code map, or rendered chart before writing paragraphs.
  • For architecture / data-flow / system-design questions, render an actual diagram (visualize show_widget tool or an Artifact) — don't describe it in sentences.
  • When explaining code, show structure visually (boxes/arrows/tables) rather than narrating it line-by-line.
  • Keep any accompanying prose short and summary-first.
  • Every reply in chat opens with "In plain words": 2–3 short sentences a non-engineer understands (plus a tiny picture when it helps), then the detail. This applies to status updates too.
  • Default to the eli5 skill (.claude/skills/eli5) for every substantive answer, and always publish its picture page (HTML artifact) and link it in the reply. Actually invoke it (Skill tool, eli5) every time; an eli5-style page made without calling the skill does not count. This covers explanations (concepts, code, architecture, PRs, errors, results) and lookups, web research, recommendations, comparisons and lists. Skip it only for status updates, yes/no or one-line answers, and routine git/CI chores.
<!-- vester:visual-first:end -->

How we work: SDLC workflow

Full playbook: docs/SDLC.md (summary) and docs/SDLC_PLAYBOOK.html (interactive). This file holds conventions only — never feature details. Keep it under 200 lines.

#StageWhoOutputLabel after
1Write the storyYouIssue from story template—
2Tier it (S/M/L)Youtier:* labelstage:research (S → stage:tests)
3Research/research <n> → researcherIssue commentstage:plan
4PlanMain session (Opus)Plan comment, numbered stepsstage:tests
5Tests first/test <n> → testerRed tests, pushedstage:code
6Code each step/code <n> <step> → coderOne commit per step, pushedstage:review
7ReviewCI + tier-check + @codex review, then merge (see below)Green PR, Closes #<n>—
8Docs and lessonsdocs subagentDocs in same PR, ≤1 CLAUDE.md line—

Rules:

  • Every step's output opens with "In plain words" (eli5: 2–3 short sentences + a tiny before/after picture, no jargon), then the technical detail: story, research comment, plan comment and each plan step, the tester's and coder's report back, PR description, review replies to the owner, docs changes, and the weekly cleanup PR.
  • State lives in GitHub (issue body, comments, labels, branch, PR). Push after every step.
  • One eli5 picture per story, not per step. When the story's PR is opened, the main session runs the eli5 skill on what the whole story changed (before/after), publishes the artifact, saves a PNG to docs/issues/<n>/picture.png, pushes it, and comments on the issue with the image (raw URL pinned to the commit SHA) plus the artifact link. For frontend stories, the visual demo's screenshots go in it. Steps in between post text only ("In plain words" first). Subagents can't publish artifacts, so this is always the main session's job.
  • Frontend changes always ship with a visual demo. Any PR that changes how a page looks posts one validation comment before merge: before/after screenshots (desktop 1280px and phone 390px), a contrast table (every text/background pair ≥ 4.5), a web-design-guidelines re-run with no new findings, no JS errors on load, and nothing clipped, overlapping or scrolling sideways. Auto-merge goes on only after it passes; any failure keeps the PR open and goes to the owner.
  • Frontend coders see the design. A frontend story names its committed mockup PNG (docs/issues/<n>/…png). The coder opens it before building, then screenshots its own work at 1280px and 390px and compares it with the mockup before committing (.claude/agents/coder.md). The tester still works from the text only. The coder also reads the four design skills in .claude/skills/ (frontend-design, ui-ux-pro-max, taste-skill, web-design-guidelines); project rules win over them.
  • Design decisions live in docs/DESIGN_DECISIONS.md. Any design change adds an entry in the same PR (id, date, why, replaces, affects); changing your mind adds a new entry and marks the old one replaced.
  • The tester gets only the issue number and reads only the issue body.
  • Coders never edit tests/; they log unrelated mess as tech issues instead of fixing it.
  • Product/design questions from a coder go back to the planner; the plan comment is updated.
  • Planning stage: "Don't implement yet." Claude never reviews its own PR; Codex does.
  • Bloat is handled by the weekly cleanup subagent, not per PR.
  • Anything deliberately put off until there are real users goes in docs/PARKED.md, so it isn't forgotten at launch. Add the entry in the same PR that parks it.
  • Stay under ~60% of the context window per phase; split if needed.
  • In cloud sessions gh may be unauthenticated: use the GitHub MCP tools instead.

Tiers: how to classify S / M / L

Pick the highest row that matches. When unsure, go one tier up.

Pre-launch mode (now: 0 real users): pace over process. "A user can notice" doesn't raise a tier on its own, and "when unsure, go up" is off: label the lowest tier tier-check allows. L rules (sensitive paths, more than one src/ package, new module or data model) still apply in full. Process/tooling changes you've approved in chat skip the story; the PR is the record (L still means no auto-merge and your "merge"). Revisit when real users arrive.

TierAny of these makes it this tierMerge
LTouches a path in .github/sensitive-paths.txt (money, user data or its shape, secrets, untrusted-input defences, auth/payments, deploy/deps/CI) · changes more than one src/ package · new module or data model changeYou say "merge" and approved the plan; Claude checks CI + Codex first
MNew or changed behaviour a user can notice · adds a src/ fileYou say "merge"; Claude checks CI + Codex first
SNone of the above: a fix or tweak in one area, no new behaviourAuto-merge (rules below)
  • tier-check CI computes the minimum tier from the diff and fails a PR labelled below it. Judgement can raise a tier, never lower it.
  • The PR carries the same tier:* label as its issue. If tier-check raises it, relabel both.
  • Auto-merge for S: Claude enables GitHub auto-merge only after Codex has reviewed and every thread is resolved. GitHub then merges when the required checks are green.
  • To stop a merge, add the hold label: tier-check fails while it is on. tier-check also fails if auto-merge is on for an M or L PR, so promoting a queued S PR blocks it; Claude then disables auto-merge.
  • tier-check runs from the default branch (workflow_run after the no-op "Tier trigger"; the PR's commits are diffed, never run), so a PR can't loosen its own grading. Its own edits apply only after merge.
  • tier-check reads file paths and changed lines: secrets/env, model clients outside src/llm.py, HTTP routes, UNTRUSTED prompt text and command execution force L in any file. Codex applies the meaning-level rules in AGENTS.md.
  • Claude never merges M or L without your instruction, and never enables auto-merge on them.

Code conventions

  • Lint: ruff check . — Tests: pytest tests/ (offline, no API key). CI runs both on every PR.
  • Reuse src/llm.py for model calls and src/harness/ for retry/limits/cost — don't add new helpers.
  • Every LLM response is parsed into a Pydantic model (src/schemas.py); never parse prose.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.