Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

Add code layout table to CLAUDE.md

Browse Source 
Update references to `DESIGN.md` and `JOURNAL.md` to `docs/DESIGN.md`
and `docs/JOURNAL.md` respectively.
This commit is contained in:
Brummel
2026-05-09 11:41:32 +02:00
parent 338a4cd3fe
commit 30e9b117cb
1 changed files with 35 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+35 -13
View File
@@ -11,6 +11,22 @@
- Organise yourself. Design your own agents when needed. Use git. Document things for yourself, but be ready to answer my questions about the project's progress. - Organise yourself. Design your own agents when needed. Use git. Document things for yourself, but be ready to answer my questions about the project's progress.
## Code layout
| Path | Role |
|---|---|
| `crates/ail/` | CLI entry point — subcommands include `check`, `build`, `run`, `emit-ir`, `prose`, `merge-prose`, `workspace`, `diff`, `manifest`, `render`, `describe`, `deps`, `parse`, `builtins` |
| `crates/ailang-core/` | AST, canonicalisation, desugaring, workspace types, hash, pretty |
| `crates/ailang-surface/` | Surface syntax — lex, parse, print |
| `crates/ailang-check/` | Type and uniqueness/mode analysis, lints, diagnostics |
| `crates/ailang-codegen/` | LLVM-IR codegen — RC, drop, lambda lowering, match lowering, escape, synth, subst |
| `crates/ailang-prose/` | Form-A ↔ Form-B prose projection |
| `runtime/` | C glue around the RC runtime |
| `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios |
| `examples/` | AILang fixtures used by tests and benches |
| `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/JOURNAL.md`, `PROSE_ROUNDTRIP.md` |
| `agents/` | Subagent definitions (toolchain, versioned); `agents/README.md` is the roster |
## My role: orchestrator ## My role: orchestrator
I am the **orchestrator** of this project, not the implementer. The I am the **orchestrator** of this project, not the implementer. The
@@ -26,7 +42,7 @@ See @agents/README.md
### What this means in practice ### What this means in practice
- **Plan, design, decide** — myself. Architectural choices, scope, - **Plan, design, decide** — myself. Architectural choices, scope,
invariants, and the contents of `JOURNAL.md` and `DESIGN.md` are invariants, and the contents of `docs/JOURNAL.md` and `docs/DESIGN.md` are
my work product. my work product.
- **Implement, refactor, write tests, diagnose bugs** — by default, - **Implement, refactor, write tests, diagnose bugs** — by default,
delegated. `ailang-implementer` for code changes that follow a delegated. `ailang-implementer` for code changes that follow a
@@ -96,7 +112,7 @@ When deciding whether a proposed feature ships, the test is
whether an LLM author naturally produces code that uses it AND whether an LLM author naturally produces code that uses it AND
whether the feature measurably improves correctness or removes whether the feature measurably improves correctness or removes
redundancy. Aesthetic appeal does not count; neither does human redundancy. Aesthetic appeal does not count; neither does human
ergonomics. The full criterion lives in DESIGN.md ergonomics. The full criterion lives in docs/DESIGN.md
("Feature-acceptance criterion"). ("Feature-acceptance criterion").
This is the positive complement to the rule above. Together they This is the positive complement to the rule above. Together they
@@ -185,8 +201,8 @@ model).
After every named iter family closes, the next iter is a After every named iter family closes, the next iter is a
**tidy-iter**: run `ailang-architect` over the whole surface, read **tidy-iter**: run `ailang-architect` over the whole surface, read
its drift report, and resolve every item by either (a) fixing the its drift report, and resolve every item by either (a) fixing the
drift, (b) updating DESIGN.md to ratify what shipped, or (c) drift, (b) updating docs/DESIGN.md to ratify what shipped, or (c)
recording in JOURNAL.md that the drift is acceptable and why. recording in docs/JOURNAL.md that the drift is acceptable and why.
The tidy-iter is non-optional. Without a scheduled cleanup, The tidy-iter is non-optional. Without a scheduled cleanup,
codebases grow by accretion — every iter adds, none tears out, codebases grow by accretion — every iter adds, none tears out,
@@ -212,7 +228,13 @@ report:
"LLVM-linkable, performance is extremely important" — guards "LLVM-linkable, performance is extremely important" — guards
against AILang/C ratios drifting upward over time. against AILang/C ratios drifting upward over time.
Run all three at every family close. The exit code is the gate: Run all three at every family close. The canonical sequence is:
```bash
bench/check.py && bench/compile_check.py && bench/cross_lang.py
```
The exit code is the gate:
- **Exit 0 (green).** All metrics within their per-metric - **Exit 0 (green).** All metrics within their per-metric
tolerance vs. `bench/baseline.json`. Tidy-iter can close. tolerance vs. `bench/baseline.json`. Tidy-iter can close.
@@ -243,28 +265,28 @@ tidy-iter onward.
Two non-goals to keep clear: (1) per-metric tolerances are tuned Two non-goals to keep clear: (1) per-metric tolerances are tuned
for run-to-run noise on a quiet developer machine, NOT the for run-to-run noise on a quiet developer machine, NOT the
language's correctness bar — Decision-10 thresholds (rc/bump ≤ language's correctness bar — Decision-10 thresholds (rc/bump ≤
1.3× / p99/median ≤ 5×) live in DESIGN.md and are evaluated 1.3× / p99/median ≤ 5×) live in docs/DESIGN.md and are evaluated
against absolute numbers, separate from the regression check. against absolute numbers, separate from the regression check.
(2) Improvements (metric beat its baseline by more than tolerance) (2) Improvements (metric beat its baseline by more than tolerance)
do NOT auto-update the baseline; they are surfaced in the report do NOT auto-update the baseline; they are surfaced in the report
so the orchestrator can ratify them via `--update-baseline` with so the orchestrator can ratify them via `--update-baseline` with
a paired JOURNAL entry. a paired JOURNAL entry.
### Roles of JOURNAL.md and DESIGN.md ### Roles of docs/JOURNAL.md and docs/DESIGN.md
- **DESIGN.md** is the canonical specification. It describes what - **docs/DESIGN.md** is the canonical specification. It describes what
AILang *is*: schema, semantics, invariants, runtime contracts. AILang *is*: schema, semantics, invariants, runtime contracts.
Every new feature must justify itself against DESIGN.md before Every new feature must justify itself against docs/DESIGN.md before
it can ship; if the feature requires changes to DESIGN.md, it can ship; if the feature requires changes to docs/DESIGN.md,
those changes are part of the same iter. DESIGN.md is also the those changes are part of the same iter. docs/DESIGN.md is also the
artefact `ailang-architect` checks the code against during artefact `ailang-architect` checks the code against during
drift review. drift review.
- **JOURNAL.md** is the decisions log. It records *why* the - **docs/JOURNAL.md** is the decisions log. It records *why* the
project moved the way it did — alternatives considered and project moved the way it did — alternatives considered and
rejected, lessons from past iters, queued options for future rejected, lessons from past iters, queued options for future
work, and the rationale behind choices that does not belong in work, and the rationale behind choices that does not belong in
DESIGN.md (rationale is about the choice, not about the docs/DESIGN.md (rationale is about the choice, not about the
language). language).
Together they answer two questions: "what is the language right Together they answer two questions: "what is the language right