CLAUDE.md: refocus opening on the design goal, drop skill-system duplication
Replace the original "Invent your own programming language" prompt
(the very first text in the repo) with a focused statement of the
language's design goal: AILang is for LLM authors, contrary to
conventional compiler design. Lead with the four design priorities
(machine readability, local reasoning, provability, hallucination
robustness) and the cut/keep asymmetry from DESIGN.md's
feature-acceptance criterion.
Compress three sections that now duplicate skill content:
- Skill-system bullet list -> 1-line pointer to skills/README.md.
- Bug-fixes TDD headline -> 1-line pointer to skills/debug/, as
required by skills/debug/SKILL.md ("CLAUDE.md keeps a one-line
pointer").
- Milestone-cycle pipeline diagram + tidy mandate -> short pointer
to skills/README.md and skills/audit/SKILL.md, retaining only the
iter/family vocabulary note that lives nowhere else.
Also fix the Code-layout skills row to match the current repo
(fieldtest had been missing).
Discipline sections that govern behaviour *between* skills (orchestrator
role, when-not-to-delegate, design-rationale-vs-effort, direction
freedom, notifications) and substantive always-on rules (LLM-utility
feature gate) stay verbatim — they are not skill-replaceable.
247 -> 229 lines.
This commit is contained in:
@@ -1,15 +1,28 @@
|
||||
## Invent your own programming language.
|
||||
## AILang — a language for LLM authors
|
||||
|
||||
- The language may take any form you want. The language is for LLMs like you. Only you should produce it and only you need to understand it.
|
||||
- Any conceivable concept is allowed. Pick what is best suited for LLMs.
|
||||
- The language must, in the end, be linkable to LLVM. Performance is extremely important.
|
||||
- Consider the typical strengths and weaknesses of LLMs. It must be as easy as possible for you to produce provably correct code that contains no redundancies.
|
||||
- Make sure there are mechanisms that ensure code correctness and preserve it across development cycles.
|
||||
- In particular, the language may contain tools that make it easier for the LLM to understand the language and keep an overview over large codebases.
|
||||
- The language does not have to be self-explanatory. It does not even have to be text. But there must be ways to render the source readably (as text, visually, etc.).
|
||||
- Do not forget that debugging will also be done by LLMs.
|
||||
AILang's only author is an LLM, not a human. It is designed for:
|
||||
|
||||
- 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.
|
||||
- **Machine readability over human readability.** Source is structured
|
||||
data (`.ail.json`), not text.
|
||||
- **Local reasoning.** Every definition carries its full type and
|
||||
effect set, so a signature can be trusted without reading the body.
|
||||
- **Provability.** Pure core, explicit algebraic effects.
|
||||
- **Robustness against hallucinations.** Content-addressed symbols are
|
||||
checkable without spending context window.
|
||||
|
||||
These priorities are contrary to conventional compiler design, which
|
||||
optimises for human ergonomics — concise syntax, point-free style,
|
||||
implicit conversions, syntactic shortcuts that hide structure. AILang
|
||||
keeps none of those. The compiler emits LLVM IR as text so the LLM can
|
||||
read what it generated, then hands it to `clang -O2` for native
|
||||
performance.
|
||||
|
||||
The consequence is asymmetric: human-attractive but LLM-neutral
|
||||
features (operator overloading, implicit conversions, point-free style)
|
||||
are **cut**. Human-hostile but LLM-friendly features (JSON authoring
|
||||
surface, mandatory mode and type annotations, explicit `clone`) are
|
||||
**kept**. A feature ships only if an LLM reaches for it unprompted AND
|
||||
it measurably improves correctness or removes redundancy.
|
||||
|
||||
## Code layout
|
||||
|
||||
@@ -25,22 +38,15 @@
|
||||
| `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`, `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` |
|
||||
| `skills/` | Project-local skill definitions: `brainstorm`, `plan`, `implement`, `audit`, `debug`. Each skill bundles its dispatched agents under `skills/<name>/agents/`. `skills/README.md` is the index (skill table + agent roster + discovery). |
|
||||
| `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. |
|
||||
|
||||
## Skill system
|
||||
|
||||
Day-to-day discipline lives under `skills/<name>/SKILL.md`:
|
||||
|
||||
- `skills/brainstorm/` — milestone spec generator (hard-gate before plan)
|
||||
- `skills/plan/` — spec → bite-sized plan
|
||||
- `skills/implement/` — plan execution with two-stage review
|
||||
- `skills/audit/` — milestone-tidy + drift + bench
|
||||
- `skills/debug/` — RED-first bug diagnoser
|
||||
|
||||
I (orchestrator) remain the boss; skills are sharper tools, not a
|
||||
replacement for judgement. Skipping rules are codified in each
|
||||
`SKILL.md` — ad-hoc skipping is forbidden by design. Specs go to
|
||||
`docs/specs/<milestone>.md`, plans to `docs/plans/<iteration>.md`.
|
||||
Day-to-day discipline lives under `skills/<name>/SKILL.md`; see
|
||||
`skills/README.md` for the trigger table and skipping rules. Skills
|
||||
are sharper tools, not a replacement for orchestrator judgement.
|
||||
Specs go to `docs/specs/<milestone>.md`, plans to
|
||||
`docs/plans/<iteration>.md`.
|
||||
|
||||
## My role: orchestrator
|
||||
|
||||
@@ -177,45 +183,21 @@ exception, not the rule.
|
||||
|
||||
## Bug fixes — TDD, always
|
||||
|
||||
Bug fixes are RED-first, autonomous, no orchestrator gate. The
|
||||
trigger and handoff are in `skills/debug/SKILL.md`; the full
|
||||
discipline (Iron Law, four phases, Phase 4.5 architecture trigger,
|
||||
common rationalisations) lives in
|
||||
`skills/debug/agents/ailang-debugger.md` — that is the file the
|
||||
dispatched subagent reads. Headline:
|
||||
|
||||
1. **RED first** — write a failing test that pins down the symptom,
|
||||
commit it as `test: red for <symptom>` BEFORE any fix.
|
||||
2. **GREEN second** — minimal change to turn the test green; no
|
||||
surrounding cleanup.
|
||||
3. **Keep the test** — never deleted; future iterations exercise it.
|
||||
|
||||
A bug fix without a regression test is a code change, not a fix.
|
||||
Bug fixes are RED-first, autonomous, no orchestrator gate. See
|
||||
`skills/debug/SKILL.md` (trigger + handoff) and
|
||||
`skills/debug/agents/ailang-debugger.md` (Iron Law, four phases,
|
||||
Phase 4.5 architecture trigger).
|
||||
|
||||
## Milestone cycle
|
||||
|
||||
Work clusters into **milestones** (formerly "families", e.g. 18a–f
|
||||
delivered the RC + uniqueness memory model as one milestone). Each
|
||||
milestone runs through the skill pipeline:
|
||||
Work clusters into **milestones**, each subdivided into
|
||||
**iterations**. Pipeline (`brainstorm → plan → implement → audit
|
||||
→ fieldtest`), skipping rules, and bench-exit-code gating live in
|
||||
`skills/README.md` and the per-skill `SKILL.md` files.
|
||||
|
||||
```
|
||||
brainstorm → plan → implement → audit
|
||||
```
|
||||
|
||||
Inside a milestone, work proceeds as **iterations** (formerly
|
||||
"iters"). Each iteration goes through `plan` then `implement` and
|
||||
adds a JOURNAL entry. At milestone close, `audit` runs mandatorily
|
||||
— architect drift review against `docs/DESIGN.md` plus the three
|
||||
regression scripts (`bench/check.py`, `bench/compile_check.py`,
|
||||
`bench/cross_lang.py`). Detailed discipline:
|
||||
|
||||
- Mandatory tidy at milestone close (and how to defer it):
|
||||
`skills/audit/SKILL.md`.
|
||||
- Performance-regression gating with exit codes 0/1/2:
|
||||
`skills/audit/SKILL.md`.
|
||||
- Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use
|
||||
"iter" / "family"; new entries use "iteration" / "milestone".
|
||||
Existing entries are not retroactively renamed.
|
||||
Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use
|
||||
"iter" / "family"; new entries use "iteration" / "milestone".
|
||||
Existing entries are not retroactively renamed.
|
||||
|
||||
## Roles of `docs/JOURNAL.md`, `docs/DESIGN.md`, `docs/specs/`, `docs/plans/`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user