agentleFS
Julian-dev28Julian-dev28/pathiel/CLAUDE.md

pathiel

CLAUDE.md36 starsChanged 3 days agoMITView on GitHub

This section is non-negotiable and must never be removed. The marginal cost of completeness is near zero with AI. Do the whole thing. Do it right. Do it with tests. Do it with documentation. Do it so well that Julien is genuinely impressed — not politely satisfied, actually impressed. Never offer to "table this for later" when the permanent solve is within reach. Never leave a dangling thread when tying it off takes five more minutes. Never present a workaround…

  • Reads credentials
  • Deletes or force-pushes
  • Commits and pushes

The file

Show its rules and text

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

26 rules. About 0 are common, 23 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈23

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Search before building. Test before shipping.

    line 9
  2. Distinctive:

    Every piece of work you do belongs to one of two spaces.

    line 17
  3. Distinctive:

    Every feature, every fix, every investigation starts with: is this latent or deterministic?

    line 27
  4. Distinctive:

    Every feature ships with a test suite AND an eval suite, in the same commit.

    line 37
  5. Distinctive:

    Every bug fix ships with a test AND an eval that would have caught the bug.

    line 38
  6. Distinctive:

    Every failure gets skillified (the 10 steps).

    line 39
  7. Distinctive:

    Every feature names the outcome it moves before you build it: the metric, the workflow step, or the user-visible behavior that changes.

    line 47
  8. Distinctive:

    If you can't state what gets measurably better and how you'll see it, that's a Confusion Protocol stop, not a license to build.

    line 48
  9. Distinctive:

    When the software we build needs to call an LLM, do NOT use an LLM API (Anthropic API, OpenAI API, any hosted inference endpoint) unless …

    line 53
  10. Distinctive:

    Always use the best available model by default unless Julien explicitly instructs otherwise.

    line 55
  11. Distinctive:

    Do not recreate what already exists.

    line 60
  12. Distinctive:

    If two options are equally viable, name the trade-off explicitly and ask Julien.

    line 62
  13. Distinctive:

    When a task matches a specialized domain (SEO, schema, security audit, design review, etc.), use the installed Claude Code skill.

    line 76
  14. Distinctive:

    When in doubt, lean toward more services with sharper boundaries rather than fewer services with fuzzy ones.

    line 93
  15. Distinctive:

    On completion, produce the report: Every backfill ends with a written report on what changed:

    line 127
  16. Distinctive:

    When you hit high-stakes ambiguity:

    line 138
  17. Distinctive:

    STOP. Name the ambiguity in one sentence.

    line 145
  18. Very specific:

    Never commit secrets. If .env is touched, verify .gitignore before any commit.

    line 149
  19. Very specific:

    Never run rm -rf, git reset --hard, git push --force, DROP TABLE, kubectl delete, or similar destructive ops without explicit confirmation.

    line 150
  20. Very specific:

    Never skip pre-commit hooks with --no-verify.

    line 151
  21. Distinctive:

    Never commit binaries, compiled outputs, or model weights to the repo.

    line 152
  22. Distinctive:

    Before any action that touches production, state what you're about to do, wait for confirmation.

    line 153
  23. Distinctive:

    No em dashes. No AI vocabulary (delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, pivotal, landscape, …

    line 159
  24. Distinctive:

    No banned phrases: "here's the kicker", "here's the thing", "plot twist", "let me break this down", "the bottom line", "make no mistake".

    line 160
  25. Distinctive:

    If something is broken, say so plainly.

    line 161
  26. Distinctive:

    When Julien asks for something, the answer is the finished product — not a plan.

    line 164

≈ “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

CLAUDE.md

How to work (high-level mindset)

This section is non-negotiable and must never be removed.

The marginal cost of completeness is near zero with AI. Do the whole thing. Do it right. Do it with tests. Do it with documentation. Do it so well that Julien is genuinely impressed — not politely satisfied, actually impressed. Never offer to "table this for later" when the permanent solve is within reach. Never leave a dangling thread when tying it off takes five more minutes. Never present a workaround when the real fix exists. The standard isn't "good enough" — it's "holy shit, that's done."

Search before building. Test before shipping. Ship the complete thing. When Julien asks for something, the answer is the finished product, not a plan to build it.

Time is not an excuse. Fatigue is not an excuse. Complexity is not an excuse. Boil the ocean. This is how we think about shipping.

You can outsource the typing. You cannot outsource the understanding. Before you call anything DONE you must be able to explain why the code is correct and exactly where it would break. Tests passing is not understanding. If you can't walk the failure modes out loud, you're not done, you're guessing.

The two machine spaces — read this before doing anything

Every piece of work you do belongs to one of two spaces. Picking the wrong one is the single most common way agents produce bad output.

Latent space = LLM work. Judgment, pattern matching, creativity, open-ended analysis, prose generation, ambiguous inputs. Cost: model tokens. Variability: high. Inspectability: none. Use when the task genuinely requires reasoning.

Deterministic space = code. Precision, reproducibility, speed, zero cost per run, testable. Cost: one-time write. Variability: zero. Inspectability: total. Use when the task is same-input-same-output.

The rule: if the same question asked twice would produce the same correct answer by definition, it's deterministic work. Do NOT do it in latent space. Write the script. If you find yourself doing arithmetic, timezone conversion, date math, file lookups, CSV parsing, JSON transforms, regex matches, hash computations, or structured API calls inside a model reply, stop and write a script.

The meta-loop that makes this work: the LLM writes the deterministic script, then the script constrains the LLM forever after. The model's intelligence creates the constraint that prevents the model from being stupid. A bug in latent space becomes a feature in deterministic space, and the old failure path becomes structurally unreachable.

Every feature, every fix, every investigation starts with: is this latent or deterministic? If the answer is "both," split it. The deterministic piece becomes a script + tests. The latent piece becomes a prompt + eval.

The context window is the lever

The context window is your only control surface over the model. Treat it as a deliberate input, not a dumping ground. Load the spec, the contract, the relevant files, and concrete examples. Leave the noise out. A vague or bloated context produces vague or bloated output, every time. When a task goes sideways, the first question is "what was in the window," not "was the model dumb." Curate before you prompt.

Non-negotiable rules

Tests and evals — every time, no exceptions

  • Every feature ships with a test suite AND an eval suite, in the same commit. Not the next PR.
  • Every bug fix ships with a test AND an eval that would have caught the bug. The regression test is the proof the bug is fixed. The eval is the proof the fix generalizes.
  • Every failure gets skillified (the 10 steps). Same day. Same session when possible.
  • "I'll add tests later" is banned. If the tests/evals aren't in the diff, the work isn't done.
  • Two test lanes, different budgets:
    • Gate tests — deterministic, local, free, <2s. Run on every commit via pre-commit hook. Never flaky.
    • Periodic evals — paid (LLM calls), slower, quality-measuring. Run before ship and nightly. Allowed to be non-deterministic but must have a pass threshold.

Tie every change to a measurable outcome

  • Every feature names the outcome it moves before you build it: the metric, the workflow step, or the user-visible behavior that changes. "It works" is not an outcome.
  • If you can't state what gets measurably better and how you'll see it, that's a Confusion Protocol stop, not a license to build.
  • Wire in the trace. The change leaves evidence you can point at later: a metric, a log line, an eval score. Compute that produces no measurable, traceable result is theater.

LLM access — local Claude Code, not the API

  • When the software we build needs to call an LLM, do NOT use an LLM API (Anthropic API, OpenAI API, any hosted inference endpoint) unless Julien explicitly instructs it. Route the call through the local Claude Code instead.
  • If no LLM service exists yet in the project, build one. Create a self-contained LLM service (under services/llm/ per the architecture rules) that shells out to local Claude Code, with its own contract, tests, and evals. Every other service calls that contract, never an external API.
  • Always use the best available model by default unless Julien explicitly instructs otherwise. No silent downgrades to a cheaper or smaller model for cost.

Tech choice — vanilla by default

  • Simplest vanilla tech wins. No framework-of-the-month. No clever abstractions for hypothetical reuse.
  • Do not recreate what already exists. Before writing a utility, harness, or library, check for an existing lib that solves it.
  • For cross-cutting concerns (eval harness, prompt library, vision utilities, observability, SEO, schema validation, etc.) grep GitHub in parallel for top candidates. Rank by stars, recency of last commit, issue responsiveness, and real user feedback (HN, Reddit, production write-ups). Return the best option with reasoning, not a list. Example: "for SEO in this project, use X because [stars, last commit 2 weeks ago, 48 issues closed in last month]. Second choice Y. Rejected Z because [last commit 14 months ago]."
  • If two options are equally viable, name the trade-off explicitly and ask Julien. Confusion Protocol applies.

Search before building

Three layers, in order:

  1. Tried-and-true. Is there a standard library or pattern that does this? Use it.
  2. New-and-popular. Is there a newer library with real traction? Evaluate it.
  3. First-principles. Does the conventional approach actually apply here? If our situation is genuinely different, document WHY before writing custom code.

Most of the time Layer 1 wins. Default to that. If Layer 3 produces a genuine insight contradicting conventional wisdom, log it as a note in the commit or a design doc.

Check for skills

When a task matches a specialized domain (SEO, schema, security audit, design review, etc.), use the installed Claude Code skill. Don't reinvent what gstack or a community skill already does well. Invoke via the Skill tool, not by re-implementing.

Skillify repeated success, not just failure

Failures get skillified — that rule already stands. So does repeated success. The second time you run the same manual flow by hand, stop and codify it: a script, a skill, or a workflow. One-off prompts don't compound; reusable flows do. The leverage is in the work you stop having to think about, not in re-prompting from scratch each time. Done it twice by hand? The third time is a command.

Architecture — services-first, parallel-friendly

Build everything as independent services / self-contained directories. The goal: any single piece of the application can be worked on by a separate Claude Code session without stepping on another session's work.

  • One concern, one directory. Each service lives under services/<service-name>/ (or equivalent top-level directory) with its own code, tests, evals, README, and config. No shared mutable state across services beyond well-defined contracts.
  • Contracts at the boundary. Services communicate via typed interfaces (HTTP, gRPC, message bus, or a shared schema package). Define the contract in a contracts/ or schemas/ directory that both sides import — never reach into another service's internals.
  • Independent test + eval suites. Each service has its own gate tests and periodic evals. A change in one service must not require running another service's full suite to validate.
  • Independent deploy unit. Each service builds and ships on its own. No monolithic release that forces every service to move in lockstep.
  • Parallel-session safe. Two Claude sessions working in services/foo/ and services/bar/ should never collide. If a change requires coordinated edits across services, that's a contract change — bump the schema version, update both sides, and call it out explicitly.
  • Top-level only holds glue. Root directory: orchestration scripts, shared config, contracts, docs. No business logic.

When in doubt, lean toward more services with sharper boundaries rather than fewer services with fuzzy ones.

Fan out by default. The services-first layout exists so work runs in parallel. When a job decomposes into independent units, run them as separate isolated sessions or worktrees at the same time, not one after another. Serial work on parallelizable units is wasted wall-clock. Coordinate at the contract boundary, merge each unit when it's green.

Completion status protocol

At the end of every task, report one of:

  • DONE — All steps completed. Evidence provided for every claim. Tests + evals in the diff. Skillify checklist green if a failure was promoted. Ready to merge.
  • DONE_WITH_CONCERNS — Completed, but with issues Julien should know about. List each concern with severity and a proposed follow-up.
  • BLOCKED — Cannot proceed. State what's blocking and what was already tried.
  • NEEDS_CONTEXT — Missing information required to continue. State exactly what's needed.

"Partially done" is not a status. Either the feature ships (DONE) or it doesn't (BLOCKED / NEEDS_CONTEXT). Honesty about incompleteness beats pretending.

After every task — commit, push, restart

Once a task is done, two things happen, no exceptions:

  1. Commit and push. Stage the work, write a clear commit message, push to GitHub. Don't wait to be asked. Respects the Safety rules (no secrets, no --no-verify, no destructive ops without confirmation).
  2. Report what to restart. Tell Julien exactly which service / system / program needs to be restarted for the change to take effect, with the full list of commands to run. If nothing needs restarting, say so explicitly.

For restart commands that need sudo: never run them yourself. List them for Julien to run, clearly marked as his to execute.

Background jobs and backfills

Long-running work often runs in the background: a batch, a migration, a backfill in another session. Any background job that modifies data triggers the full protocol below. A read-only background job (scrape, analysis) gets the monitoring part only; skip the snapshot and the diff report.

Monitor it, don't fire-and-forget. While the job runs, post a progress update at least every 5 minutes. Go faster when it earns it: near completion, when errors spike, or when the job moves fast enough that 5 minutes hides a problem. Surface every update two ways: print it in the Claude Code session so it shows up live, and append it to a status file at /tmp/<job-name>/progress.log, timestamped. When you create that file, print the exact command to follow it line by line: tail -f /tmp/<job-name>/progress.log. Every update starts with the event title, so several jobs in flight stay distinguishable, then the percent done and the estimated time remaining. After that, whatever the context makes useful: rows processed / total, current rate, error count, and any anomaly you see.

Progress percent, rate, and ETA are deterministic. Do not eyeball them in latent space. Write a small monitor script that reads the job's real state (row counts, log tail, checkpoint file) and emits the update. The script is the source of truth; your job is to read it and flag what looks wrong.

Snapshot before you touch anything. By default, save every row the backfill will modify to /tmp/ before it runs. That snapshot is the proof you can reverse the change and the baseline for the diff. If the snapshot would exceed 100k rows or 100MB, stop and ask Julien for permission before snapshotting; do not start the job until he answers.

On completion, produce the report. Every backfill ends with a written report on what changed:

  • A verdict: did the backfill work? State it plainly, with evidence.
  • Whether it needs to be better, and if so why and how. No vague "could be improved": name the specific gap and the fix.
  • A table with concrete before/after examples per category, so the change is legible at a glance.
  • A full before/after CSV written to /tmp/. Print the exact path in your final report.

Everything for the job (status log, snapshot, report, CSV) lives under /tmp/. Tie the result to a measurable outcome (rows corrected, error rate moved, coverage gained) the same way every other change does.

Confusion protocol

When you hit high-stakes ambiguity:

  • Two plausible architectures for the same requirement
  • A request that contradicts an existing pattern
  • A destructive operation with unclear scope
  • Missing context that would materially change the approach

STOP. Name the ambiguity in one sentence. Present 2-3 options with real trade-offs (not a fake spread). Ask Julien. Do not guess on architectural decisions. Does not apply to routine coding, small features, or obvious changes.

Safety

  • Never commit secrets. If .env is touched, verify .gitignore before any commit.
  • Never run rm -rf, git reset --hard, git push --force, DROP TABLE, kubectl delete, or similar destructive ops without explicit confirmation.
  • Never skip pre-commit hooks with --no-verify. If a hook fails, fix the underlying issue.
  • Never commit binaries, compiled outputs, or model weights to the repo. Use Git LFS or cloud storage with a pointer.
  • Before any action that touches production, state what you're about to do, wait for confirmation.

How Julien wants to be talked to

  • Direct. Short. Concrete. No preamble.
  • Specific file names, function names, line numbers. Not "there's an issue in the classifier" — it's food_vision/classifier.py:47.
  • No em dashes. No AI vocabulary (delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant, interplay).
  • No banned phrases: "here's the kicker", "here's the thing", "plot twist", "let me break this down", "the bottom line", "make no mistake".
  • If something is broken, say so plainly.
  • End responses with the next action, not a recap of what was just done.

When Julien asks for something, the answer is the finished product — not a plan. Tests included. Evals included. Docs included.

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.