Moon Development
Use progressive disclosure to load only the Moon and MoonBuild context relevant to the change. Do not read or reproduce the entire developer-document corpus.
Route the work
- Read
CONTEXT.mdbefore naming, changing, or reviewing MoonBuild concepts, command communication, package execution, or native-build behavior. Use its canonical terms and respect its avoided synonyms. - Open
docs/dev/README.md. Use its task table to select the relevant ADRs, designs, implemented-behavior references, migration notes, and testing guidance. - Read the selected documents together with the affected source and tests. Do not assume a design or migration document describes implemented behavior.
- Establish which build engine owns the changed path. Rupes Recta is the
default; inspect legacy
moonbuildonly when the path still uses it or the requirement includes compatibility. - Surface conflicts with an ADR or behavioral reference explicitly. Do not silently replace an existing decision or leave an implemented-behavior reference stale.
- Route
crates/moonrunruntime-internal work through its ownCONTEXT.mdand developer index rather than treating it as MoonBuild implementation.
Deepen before layering
Before adding a MoonBuild planning or lowering type, projection, or seam:
- Identify the closest existing module and prefer deepening, moving, or extending it over adding a parallel representation.
- Apply the deletion test to the proposed module. If deleting it would concentrate its rules in an existing owner instead of scattering them among callers, do not introduce it.
- State the unique invariant owned by a new representation and why a real seam needs it. Overlapping fields or a single fixed adapter do not justify one.
- Design the merged end state before splitting the work. Intermediate commits may carry compatibility code, but the PR should replace or materially shrink the old model rather than merge two peer models into the default branch.
- Mark every intentionally retained compatibility representation, known seam
violation, or deferred deletion in source with a searchable
FIXMEorTODOthat states the removal condition. Ordinary comments, design documents, and PR descriptions do not replace the source marker. - Separate semantic changes from optional terminology cleanup. A rename is not an architectural benefit.
Keep each fact in one home
- Put domain vocabulary in
CONTEXT.md. - Put accepted, hard-to-reverse trade-off decisions in
docs/adr/. - Put cross-cutting designs and invariants in
docs/dev/design/. - Put implemented MoonBuild behavior in
docs/dev/reference/and update it with the implementation. - Put migration sequencing in its named migration document.
- Put user-facing command behavior in
docs/manual/anddocs/manual-zh/. - Treat source and tests as the final evidence for the current revision.
- Update
docs/dev/README.mdwhen adding, renaming, superseding, or changing the required audience of a developer document.
Avoid copying the task-to-document table into this Skill. The developer index owns the route; linked documents own the facts.
Validate proportionally
Use the task route in the developer index instead of prescribing one universal command. Preserve behavior across commands and both build engines when the feature applies to both. Prefer the narrowest test surface that proves the changed phase, and add end-to-end coverage only when the behavior crosses command or process seams.