Tachikoma
4ca0e6ef76
This repository has no AGENTS.md; CLAUDE.md and MAINTENANCE.md carry the same rules, so both are updated. Outstanding work is an issue on the forge now, with the file and line, the functional consequence, and what closing it would touch. TODO.md is the record -- settled design decisions, the deviation register, defects already fixed, and the reasoning behind the measurements -- and its row in CLAUDE.md's reading table says so, with the tracker listed above it. The dependency rule gains the correction this migration produced. 'Never work around a missing dependency capability here' now says to open an issue in that repository's tracker, and says plainly that recording it here instead is not filing it: two akgl_ui gaps sat in TODO.md for a release on the reasoning that changing a submodule is that repository's decision, which is true of changing it and not of reporting it. Both are libakgl issues now. Cross-repository citations of deps/*/TODO.md sections point at the trackers. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4.9 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Read MAINTENANCE.md first
MAINTENANCE.md is the authoritative document for changing this project,
and it is written for whoever has to do the changing — human or agent. It carries what used to
live in this file: the project goals, the Go reference implementation and its architecture, the
dependency versions and their ABI rules, the four ways an embedded build collides, the
libakerror error convention, the coordinated error-code range map, the test lists, the
documentation-example harness, and the style and commit rules.
There is one copy of all of that, on purpose. Anything you would have added here, add there instead — the maintainer needs it as much as you do, and a second copy is a second thing to keep true.
akbasic is a C rewrite of the Go BASIC interpreter in deps/basicinterpret, written in the
idiom of the ak* C libraries it builds on, and meant to end up embedded in libakgl as a
scripting engine for game authors.
| Read | For |
|---|---|
MAINTENANCE.md |
Everything above. Start here |
| the issue tracker | Outstanding defects and gaps. Labelled by kind and blast radius; status::grooming means the scope is not settled yet |
TODO.md |
The record: settled design decisions, the deviation register, defects already fixed, and the reasoning behind the measurements. §0.1 first — it retires the byte-for-byte fidelity constraint several later sections were written on |
README.md |
What the project is and why, for somebody who has not seen it |
docs/ |
The language itself: eighteen chapters, verb and function reference. Chapter 14 is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. Chapter 15 is the error-code appendix. Chapters 17 and 18 are tutorials that build the games in examples/breakout/ |
deps/libakerror/AGENTS.md |
The ATTEMPT/CLEANUP/PROCESS/HANDLE/FINISH protocol, authoritatively |
deps/libakerror/UPGRADING.md |
1.0.0's status registry. Required before writing an error code |
deps/<library>/AGENTS.md |
Per-repo rules. Read the relevant one before editing a submodule |
Before doing anything else in a fresh clone:
git submodule update --init --recursive
Rules that are on you rather than on a test
Most of the conventions in MAINTENANCE.md are enforced by something — a sorted-table test, a
WILL_FAIL list, a Doxygen gate, a byte-compared corpus. These are not, so they are worth
repeating where you will see them:
- Add tests in the same commit as the behaviour change, and assert the correct contract
even where the code is currently wrong. A known-failing test goes in
AKBASIC_KNOWN_FAILING_TESTSwith an open issue; it does not get pinned to the buggy behaviour, because that turns the eventual fix into a test failure. - Never work around a missing dependency capability here. Open an issue in that
repository's tracker on https://source.starfort.tech — what the BASIC verb requires, what
the entry point should look like, what tests would cover it.
MAINTENANCE.mdexplains why, and names the four gaps this closed upstream. Recording it here instead is not filing it: twoakgl_uigaps sat inTODO.mdfor a release because changing a submodule is that repository's decision — which is true of changing it and not of reporting it. - Never edit generated output —
build/trees, the generatedakerror.h,akgl.pc,include/akgl/SDL_GameControllerDB.h. Change the template or the generator script. - Do not reformat code you are not otherwise changing. Several files mix tabs and spaces and there is no repo-wide formatter; style conversions get their own commit.
- Do not edit
tests/reference/. Those expectations came from the Go implementation and are never edited to suit this interpreter. A deliberate divergence goes intests/reference/README.md's divergence table anddocs/13-differences.md. - Open an issue for outstanding work; do not add it to
TODO.md. https://source.starfort.tech/andrew/akbasic/issues, ortea issues create --repo andrew/akbasic. Name the file and line, the functional consequence, and what closing it would touch. Publishing a problem you cannot fix yet is a contribution — and when you learn something about an open issue, say so in the issue, including that it is worse than recorded, already fixed, or resting on a premise that has expired. - Add yourself — program, model and version — as a commit co-author.
libakgl'sAGENTS.mdrequires it and this repository follows the same rule.