huguryildizhuguryildiz/ALETHEIA/templates/CLAUDE.md

ALETHEIA / templates

CLAUDE.md0 starsChanged 4 months agoMITView on GitHub

{{ONE_LINE: what this project computes/optimizes/models, for which output — e.g. "X pipeline targeting one journal paper + one dataset release".}} Current phase status is NOT kept in this file (it drifts) — derive it from git log, the latest {{build_log_dir}} entry, and TODO.md. Machine-readable bindings; every Aletheia skill resolves its {{placeholder}} references here. Filled by the skill-library-generator interview, or by hand. Which discipline applies to which kind of work. Default is the minimum; escalation is conditional. Never turn a small…

In this repository15 other files it gives its agents.
- build-logSkill
- canonical-paramsSkill
- correctness-gateSkill
- decision-logSkill
- evidence-conventionSkill
- layer-syncSkill
- phase-gateSkill
- project-layoutSkill
- run-provenanceSkill
- external-positioningSkill
- lit-anchorSkill
- negative-results-ledgerSkill
- numerical-determinismSkill
- statistical-reportingSkill
- skill-library-generatorSkill

The file

Create a free account to mount

Files

CLAUDE.md

CLAUDE.md — {{PROJECT_NAME}}

<!-- Aletheia template: copy to your project root and fill every {{...}}.
     The Aletheia skills read the config block below; the routing table tells the
     agent which discipline applies to which kind of work. Keep both. -->

One line

{{ONE_LINE: what this project computes/optimizes/models, for which output — e.g. "X pipeline targeting one journal paper + one dataset release".}}

Current phase status is NOT kept in this file (it drifts) — derive it from git log, the latest {{build_log_dir}} entry, and TODO.md.

Quick start

{{INSTALL_COMMAND}}        # e.g. "uv sync" / "conda env create -f environment.yml"
{{TEST_COMMAND}}           # full test suite
{{gate_command}}           # the correctness gate (Rule 1 below)

Aletheia config block

Machine-readable bindings; every Aletheia skill resolves its {{placeholder}} references here. Filled by the skill-library-generator interview, or by hand.

aletheia:
  critical_modules: ["src/{{pkg}}/core/**", "src/{{pkg}}/model/**"]  # correctness-gate scope
  gate_command:     "{{e.g. pytest tests/test_correctness.py}}"      # the named gate
  canonical_values: "src/{{pkg}}/config/constants.py"                # protected defaults (canonical-params)
  evidence_dir:     "results/"                                       # evidence-convention root
  doc_layers:       [decisions, spec, code, notebooks]               # layer-sync order (authority first)
  decision_log:     "docs/decisions.md"                              # decision-log file
  build_log_dir:    "docs/build_log/"                                # build-log entries
  phase_plan:       "docs/roadmap/plan.md"                           # phase tables + acceptance checklists (phase-gate)
  env_manifest:     "pyproject.toml"                                 # + lockfile alongside (run-provenance)
  data_dir:         "data/"                                          # input data root (run-provenance)
  bibliography:     "docs/references.bib"                            # verified citations (lit-anchor)
  claim_log:        "docs/novelty_claims.md"                         # optional: novelty/absence claims + backing searches (lit-anchor)

Work-type routing (default + escalation — NOT mandatory-every-time)

Which discipline applies to which kind of work. Default is the minimum; escalation is conditional. Never turn a small change into bureaucracy.

Work type (trigger)	Default (do this)	Escalate to … when …
small exploration	notebook + light note (`project-layout`)	— (stays light)
reusable experiment / real run	script + `evidence-convention` (results dir + meta)	+ `run-provenance` (env + input + seed fingerprints) when it feeds a paper figure/claim or must be reproduced by others
critical logic change	`correctness-gate` (run the named gate)	+ `canonical-params` when it touches protected defaults; + `decision-log` when a red gate is an intentional formulation change
stochastic run	record seeds (`run-provenance`)	+ `numerical-determinism` when results must be bit-reproducible / cross-machine
numeric claim / result	`statistical-reporting` (replication + interval)	+ `verifier` agent when the claim is load-bearing (goes in the paper); + `external-positioning` when it is a novelty claim
phase conclusion	`phase-gate` checklist	+ `build-log` when it is a real milestone, not a trivial sub-step
assumption / default change	`decision-log` entry	+ `layer-sync` when it touches ≥ 2 layers; + `canonical-params` when it is a canonical default
dead end / failed attempt	one-line `negative-results-ledger` entry	— (stays light)
citing prior work / bibliography	verify each source one-by-one (`lit-anchor`)	+ `external-positioning` when it backs a novelty/absence claim

Operating rules (project-pinned summaries; the skills carry the detail)

Correctness gate — any change under critical_modules → gate_command must pass before "done". Red = bug OR intentional change (then: approval + pin update + decision entry). Never pass silently.
Canonical operating point — values in canonical_values change only inside a sweep or with explicit approval; probes are script-level arguments.
Session artifacts — AI-generated plans/scratch specs live under .claude/plans/, never in docs/ or the repo root.
Rhythm — execution turns work from TODO.md; phase ends close via phase-gate; sessions after a gap open with the session-historian agent, not from memory.
{{PROJECT_SPECIFIC_RULES: language conventions, math-notation rules, review cadence — add your own numbered rules here.}}

Pointers

Decisions: {{decision_log}} (authority layer — newest on top).
Spec: {{SPEC_DOC_PATH: the implementation contract the gate tests against}}.
Plan/status: {{phase_plan}} (+ status board).
Evidence: {{evidence_dir}}<name>_<date>/ — no dark runs.

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.

Check your setup, free