fairmark
CLAUDE.md1 starsChanged 5 days agoApache-2.0View on GitHub
@AGENTS.md @specs/constitution.md Standard loop: spec-writer → (maintainer approves) → test-engineer → core-engineer → code-reviewer (+ numerical-auditor when numbers changed, + security-reviewer when dependencies or workflows changed) → docs-writer → PR. To change an agent or a skill, edit .agents/ and run uv run just generate; never edit .claude/agents or .claude/skills directly.
In this repository39 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- add-methodSkill
- adr-newSkill
- commitSkill
- explain-changesSkill
- fix-ciSkill
- golden-caseSkill
- implement-specSkill
- onboardingSkill
- plan-sprintSkill
- pre-prSkill
- pr-triageSkill
- releaseSkill
- roadmap-updateSkill
- run-sprintSkill
- session-endSkill
- session-startSkill
- spec-newSkill
- translateSkill
- add-methodSkill
- adr-newSkill
- commitSkill
- explain-changesSkill
- fix-ciSkill
- golden-caseSkill
- implement-specSkill
- onboardingSkill
- plan-sprintSkill
- pre-prSkill
- pr-triageSkill
- releaseSkill
- roadmap-updateSkill
- run-sprintSkill
- session-endSkill
- session-startSkill
- spec-newSkill
- translateSkill
- fairmarkSkill
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Never use icons, emoji, pictograms or decorative symbols: not in documents, README, comments, commit messages, PR or issue text, nor in …
- Very specific: line 42
Write everything that goes into the repository in English.
- Very specific: line 63
Every request is read with the roadmap in mind (UserPromptSubmit reminder): propose the roadmap change with /roadmap-update when a request …
- Very specific: line 76
Prefer reading specs/ and docs/en/concepts/ over guessing intent.
- Distinctive: line 77
When a methodology choice is ambiguous, ask the maintainer instead of picking one.
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 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.
Files
CLAUDE.md
@AGENTS.md @specs/constitution.md
Claude Code specifics
House style — non-negotiable
Never use icons, emoji, pictograms or decorative symbols: not in documents, README, comments,
commit messages, PR or issue text, nor in your replies about this project. Use words.
scripts/check_style.py enforces it in CI.
Subagents (.claude/agents/, generated from .agents/agents/)
Delegate instead of doing everything in the main context:
| Subagent | Use it for |
architect | Structural decisions and ADRs, before cross-cutting changes |
spec-writer | Turning a request into spec.md, then plan.md + tasks.md |
test-engineer | Golden cases and property tests from acceptance criteria, before code |
core-engineer | Implementing Rust core tasks from tasks.md |
docs-writer | Methodology pages, guides, regenerated reference |
code-reviewer | Reviewing the current diff against AGENTS.md and the constitution |
numerical-auditor | Independently recomputing results, checking conventions and determinism |
security-reviewer | Dependencies, workflows, data handling |
ci-investigator | Root cause of a red CI run |
release-manager | Release readiness and verification |
sprint-planner | Proposing the next sprint (sprints/SNN.yaml) with parallel lanes |
translator | Updating the Italian edition from the English source, with the glossary |
Standard loop: spec-writer → (maintainer approves) → test-engineer → core-engineer →
code-reviewer (+ numerical-auditor when numbers changed, + security-reviewer when
dependencies or workflows changed) → docs-writer → PR.
Skills (.claude/skills/, generated from .agents/skills/)
/spec-new, /implement-spec, /add-method, /golden-case, /adr-new, /pre-pr,
/fix-ci, /release, /plan-sprint, /run-sprint, /commit, /explain-changes,
/translate, /onboarding, /session-start, /session-end, /pr-triage,
/roadmap-update.
Languages
Write everything that goes into the repository in English. Talk to each person in the
language they prefer: read CLAUDE.local.md if it exists. Prepare commits with /commit
(English message plus a translation for review). After English documentation changes, run
/translate so the Italian edition stays current.
Sprints and orchestration
Subagents cannot start other subagents: the main session is the orchestrator. /run-sprint
delegates each issue of sprints/SNN.yaml to the agents above (locally, lane by lane) or to
Claude in GitHub Actions (remotely, via @claude on the issue). Every issue ends as a PR;
nothing is merged without the maintainer.
Documentation
A Stop hook runs scripts/docs_sync.py impact: if code changed without its documentation,
you are sent back to fix it (delegate to docs-writer).
To change an agent or a skill, edit .agents/ and run uv run just generate; never edit
.claude/agents or .claude/skills directly.
Hooks (.claude/settings.json)
- Edited
.rs/.pyfiles are formatted automatically after each edit. - Edits to existing files in
tests/golden/are blocked: ask the maintainer. - Every request is read with the roadmap in mind (
UserPromptSubmitreminder): propose the roadmap change with/roadmap-updatewhen a request adds, changes or drops planned work.
MCP
.mcp.json registers this repository's own fairmark MCP server (dogfooding): use its tools
to sanity-check numbers while developing instead of computing them yourself.
Session protocol
Begin with /session-start, end with /session-end, review the merge queue with /pr-triage.
The journal in .agents/journal/ is how the next session knows where this one stopped.
Working style
- Plan before multi-file changes; keep diffs small and focused on one task.
- Prefer reading
specs/anddocs/en/concepts/over guessing intent. - When a methodology choice is ambiguous, ask the maintainer instead of picking one.
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
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.