agentleFS
TakiTakeTakiTake/pall8t/CLAUDE.md

pall8t

CLAUDE.md4 starsChanged 49 days agoMITView on GitHub

Guidance for Claude Code (and other agents) working in this repo. The Rust toolchain is pinned by the repo-top nix flake (flake.nix + flake.lock). That pin is the single source of truth: CI and release read it with scripts/rust-version.sh rather than installing a moving stable, so the compiler that gates a change is the one that produced it. ci.yml also runs a report-only stable-canary job, which says what a newer compiler thinks without letting it decide the build. Inside the…

  • Reads credentials

The file

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

4 rules. About 0 are common, 3 are distinctive, and 1 is 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.

  • 1

    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:

    Read docs/testing.md before writing tests — it records the conventions the suite follows (pure-function seams, table tests with reasoned …

    line 41
  2. Distinctive:

    Remove the worktree once its PR merges.

    line 49
  3. Distinctive:

    Only merge a PR once it's been declared ready for review and merge — don't merge speculatively.

    line 51
  4. Very specific:

    Before opening or updating a PR, run the local-review skill on the branch diff — the external reviewers should come back empty-handed.

    line 53

≈ “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 (and other agents) working in this repo.

Build & verify

The Rust toolchain is pinned by the repo-top nix flake (flake.nix + flake.lock). That pin is the single source of truth: CI and release read it with scripts/rust-version.sh rather than installing a moving stable, so the compiler that gates a change is the one that produced it. ci.yml also runs a report-only stable-canary job, which says what a newer compiler thinks without letting it decide the build. Inside the pall8t dev container it is preinstalled — the image builds from the same lock file (.pall8t/Containerfile); on the host, nix develop opens a shell with it. Run checks directly with cargo:

cargo check
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo test

A lint pass on the host triple alone can miss a warning on the other side of a #[cfg(target_os = ...)] gate — the tree has no such branches right now (the last ones went with the home module, ADR-0008), but the cross-lint stays as the guard that catches the next one. Lint the non-host target before considering a change clean (the flake toolchain already includes the target std; only a rustup toolchain needs the target add):

cargo clippy --all-targets --target aarch64-apple-darwin -- -D warnings

(scripts/lint.sh runs both and is what the pre-commit hook uses — but the hook is opt-in, not automatic: enable it once per checkout with git config core.hooksPath .githooks. On a fresh clone/worktree, run scripts/lint.sh by hand.)

Read docs/testing.md before writing tests — it records the conventions the suite follows (pure-function seams, table tests with reasoned assertions, regression pins).

Git workflow

  • The main checkout stays on main — never switch branches there. Do task work in a worktree: git worktree add .claude/worktrees/<task> -b <branch> origin/main. Remove the worktree once its PR merges.
  • Merge style is merge commits ("Merge pull request #N from ...").
  • Only merge a PR once it's been declared ready for review and merge — don't merge speculatively.
  • Before opening or updating a PR, run the local-review skill on the branch diff — the external reviewers should come back empty-handed.
  • CodeRabbit does not review on its own: opening or pushing to a PR triggers nothing. Asking it for a review (@coderabbitai review as a PR comment) is the human's call — don't spend one unprompted.
  • PR review feedback (bot or human) is handled with the review-loop skill: verify each finding before acting, classify it (real / nitpick / false positive), and reply with evidence. Never blanket-apply bot suggestions — reviewers contradict each other. A real finding local review missed also becomes a new lens in the local-review skill (its "Grow the lenses" section), in the same fixing PR.

Actions that need the human directly

This repo's permission system has, in practice, denied agents several publish-facing actions: tag pushes (they trigger the release workflow), gh repo create, pushes to TakiTake/homebrew-tap, and gh pr merge — a task assignment from another agent doesn't count as user consent to publish. Treat this as "publishing anything public-facing may need the user," not a closed enumerated list — a push to an existing public repo has been gated at least once (the tap), so don't assume a variant that's merely similar to a tested case is safe. If an action gets denied, don't retry it or work around it — hand the exact command to the user and stop there.

Pointers

  • Release process: docs/release.md (or run /release; /bump <version | major | minor | patch> alone does just the version/changelog PR)
  • Homebrew formula: TakiTake/homebrew-tap
  • Requirements: docs/requirements.md
  • Architecture decisions: docs/adr/
  • Testing conventions: docs/testing.md
  • Sandbox environment details: .claude/skills/pall8t
  • Quality gates (quality.yml, per PR, blocking): incremental mutation testing over the PR's own diff (cargo mutants --in-diff — a missed mutant means a test that would not notice this change breaking) and a 90% line-coverage floor. Suite size and wall time are recorded there too, without gating. Whole-tree mutation (mutants.yml) and duplication/unused-deps (hygiene.yml) stay report-only — weekly, on each PR for hygiene, plus on-demand via gh workflow run <name>; gating a whole-tree backlog teaches reflexive ignoring, while the in-diff gate has no backlog to inherit. herdr API-method drift (herdr-drift.yml, running scripts/herdr-method-drift.py against the latest herdr release) is report-only for a different reason: what the relay classifies as a read is a human decision, and herdr's schema is not a complete inventory of what it serves.
  • Review automation: Codex PR review (codex-review.yml) stays dormant until an OPENAI_API_KEY secret exists (paid); CodeRabbit config in .coderabbit.yaml (on demand only — see Git workflow; the free plan meters reviews).
  • herdr plugin (contrib): contrib/herdr-plugin/ — sandbox status/shell/ rebuild/stop from a herdr pane. A thin shell over the pall8t CLI whose only contract is pall8t ls --json; when that output shape changes, it changes in the same commit.

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.