agentleFS
jaroslawherodjaroslawherod/micold-ai-ide/CLAUDE.md

micold-ai-ide

CLAUDE.md1 starsChanged 3 days agoApache-2.0View on GitHub

Guidance for Claude Code when working in this repository. Skip greetings, preambles, and recaps. Do not open with phrases like "I'd be happy to help", "Great question", or "Sure, I can do that". Do not close with a restatement of what you just did unless the user asks for a summary. Answer directly: for a question, give the answer; for a task, make the change and report only what changed and any follow-up the user needs to take. Output code…

The file

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

8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not reply in a finished cloud thread to ask a follow-up: after more than an hour idle, one reply re-writes the whole cache.

    line 16
  2. Very specific:

    When the user says to start work on an issue (#<issue>), do not work on it in the current session.

    line 21
  3. Distinctive:

    Every tool call re-reads the whole conversation, so call count and output size are what cost.

    line 28
  4. Very specific:

    Never poll with sleep loops or repeated gh pr checks: Run the wait as one Bash call with run_in_background (an until ….

    line 34
  5. Very specific:

    Autopilot subagents: run as the autopilot-unit, autopilot-reviewer and autopilot-worker types in .claude/agents/.

    line 53
  6. Very specific:

    Prefer mise run <task> over invoking cargo directly — the tasks in mise.toml are the canonical way to build, test, and run this project, so …

    line 67
  7. Very specific:

    Use grep -n for strings, log messages, config keys, docs, shell scripts and anything that is not Rust.

    line 112
  8. Very specific:

    Before adding a function, type or test fixture, grep -n the crates for what it does (a verb, a distinctive literal) and reuse or extend a …

    line 119

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

Guidance for Claude Code when working in this repository.

Response style: be concise

Skip greetings, preambles, and recaps. Do not open with phrases like "I'd be happy to help", "Great question", or "Sure, I can do that". Do not close with a restatement of what you just did unless the user asks for a summary. Answer directly: for a question, give the answer; for a task, make the change and report only what changed and any follow-up the user needs to take. Output code without wrapping explanation unless the user asks how or why. Prefer one line over a paragraph, and a paragraph over a bulleted essay, when either communicates the same information.

Follow-ups go to the project chat

Do not reply in a finished cloud thread to ask a follow-up: after more than an hour idle, one reply re-writes the whole cache. Ask in the project chat, or start a fresh thread.

"Start work on issue": worktree and autopilot session

When the user says to start work on an issue (#<issue>), do not work on it in the current session. Create a worktree for the issue with create_worktree (github_issue: <issue>), then create_session in that worktree with the prompt /speckit-autopilot #<issue>. Report the worktree and session id.

Keep the context small: read with Read, wait without polling

Every tool call re-reads the whole conversation, so call count and output size are what cost.

  • Read files with the Read tool, not sed -n, cat, head, or tail. There is no Grep tool in this setup: find the lines with grep -n in Bash, then Read with offset/limit. Session history showed ~9,400 sed -n 'X,Yp' chunk reads — main.rs alone over 300 times — each a separate round-trip that Read would have collapsed.
  • Never poll with sleep loops or repeated gh pr checks. Run the wait as one Bash call with run_in_background (an until …; do sleep 30; done that exits on the terminal state) or a Monitor, and act when its notification arrives. ~7,000 polling calls each re-read the full context for no new information.
  • Batch probes into one call. git status, ls, a grep -n and a gh pr view that you would run back to back go in one Bash call, and independent Reads go in one message. At a typical ~120k context, every call saved is ~120k cache-read tokens saved.
  • One session per unit of work. Context carried across tasks is re-read on every later call: one refactor session made 5,246 calls and alone accounted for 23% of all cache reads. Start a fresh session (or subagent) per feature phase or milestone, and hand state over in a file — a ledger, tasks.md, a commit — not in conversation.

Put cheap work on a cheaper model, in a fresh context

Session history ran 99% of calls on Opus, subagents included. Move work down a model only where it starts a fresh context: switching the model mid-conversation re-writes the whole cached context for the new model, which costs more than it saves.

  • Explore agents (locating code, tracing a call path): pinned to Haiku by .claude/agents/Explore.md.
  • Autopilot subagents run as the autopilot-unit, autopilot-reviewer and autopilot-worker types in .claude/agents/. autopilot-unit is pinned to Sonnet by its frontmatter (the others inherit the model); all drop the tools they never use: the Artifact schema alone is about 10k tokens on every call of a general-purpose subagent.
  • Re-review rounds (round 2+ of a spec, plan, tasks or diff review) and conformance checks: model: "sonnet". First-round artifact reviews pass model: "opus" explicitly.
  • Forked skills already set context: fork + model: sonnet in their frontmatter: visual-pass, speckit-analyze, speckit-bugfix-verify, speckit-tdd-verify. They see only their arguments, so pass paths and what to check. A spec-kit upgrade regenerates the speckit-* files; re-add those three lines afterwards.
  • Stay on the session model for writing specs and plans, debugging, architecture, and non-trivial Rust.

Use mise tasks, not raw cargo commands

Prefer mise run <task> over invoking cargo directly — the tasks in mise.toml are the canonical way to build, test, and run this project, so use them instead of rediscovering the right cargo invocation each time. mise tasks lists every task with its description; the ones whose use is not obvious from that:

  • mise run gate — CI's merge gate locally, in CI's order: cargo fmt --check, clippy (core, then workspace, -D warnings), cargo test --workspace, then scripts/tests/*.test.sh. Run this, not mise run test, before pushing — CI stops at fmt before any test runs.
  • mise run check — cargo check --workspace: no linking, so it is the fast loop while editing. mise run test/mise run gate link one executable per top-level tests/*.rs file (591 of them); a single cargo test -p micold-client run has written ~39 GB and driven I/O pressure to 50%. Iterate with mise run check or a single targeted test (scripts/build-lock.sh cargo test -p <crate> <test_name>, or mise run test-core for the core crate); reserve a --workspace test run for mise run gate before you push. See docs/development/shared-build.md.
  • mise run test-core — test only the render-free core (cargo test -p micold-core --all-targets); no GUI, no iced, so it is much faster for logic-only changes.
  • mise run image — build the :dev sandbox image from the working tree; mise run test-sandbox then runs the real-runtime sandbox suite against it (both crates, release, one at a time). Those tests are off by default, so mise run test does not need a container runtime installed.
  • mise run duplication — fail when code duplication passes its budget (jscpd, similarity-rs); not in the gate. See docs/development/duplication.md.

The first mise run <task> in a fresh worktree/clone requires trusting the repo's mise.toml once via mise trust (mise refuses untrusted configs by default).

Navigate Rust with the LSP tool before grep

Use LSP by default for every Rust symbol question — it is the first tool, not a fallback. It is a deferred tool: load it once with ToolSearch("select:LSP"). If it crashes (rust-analyzer ... crashed with exit code 1), the rustup toolchain is missing the component: run rustup component add rust-analyzer, then use LSP again. Only fall back to grep -n after that.

The rust-analyzer-lsp plugin (.claude/settings.json) backs the LSP tool. For a Rust symbol it answers in one call what grep -n plus several Reads answer in many, and it knows types and trait impls, which text search does not. filePath, line and character are 1-based; find the position with grep -n first.

  • Where is it defined / what is its type: goToDefinition, hover.
  • Who uses it, before changing a signature or deleting it: findReferences, incomingCalls. Do this before a rename or a removal; a grep misses macro-generated and trait-dispatched uses.
  • Which impl runs: goToImplementation on the trait method.
  • What is in a file: documentSymbol, then Read only the range you need, not the whole file.
  • Find a symbol by name: workspaceSymbol with a non-empty query.

Use grep -n for strings, log messages, config keys, docs, shell scripts and anything that is not Rust. If LSP reports no server or returns nothing (rust-analyzer still indexing, a file outside the workspace), fall back to grep -n and do not retry. It does not replace mise run gate: rust-analyzer's diagnostics are not CI's clippy.

Search for an existing helper before writing a new one

Before adding a function, type or test fixture, grep -n the crates for what it does (a verb, a distinctive literal) and reuse or extend a match. Copying a block and editing it is the failure mise run duplication budgets; extract the shared part instead.

One target directory, one build at a time

mise run builds share target-shared/ beside the main checkout (scripts/build-lock.sh --print-target-dir); a bare cargo in a worktree builds into a private target-shared/ beside the worktree instead. Expect to wait behind another worktree's build (Blocking waiting for file lock) and leave it that way — never point CARGO_TARGET_DIR somewhere private. MICOLD_NO_BUILD_LOCK=1 skips the git-dir lock for a one-off run. When disk is short, use the reclaim-disk skill. Why: docs/development/shared-build.md.

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.