Galaxy Game — Project Conventions

This repository hosts the Galaxy Game project.

Sources of truth

ARCHITECTURE.md — global architecture, project-wide rules and links to the implemented services.
galaxy/<service>/README.md - service conventions and agreements for the implemented or planned to be implemented service.

Planning of service implementation and Implementing Plan

galaxy/<service>/PLAN.md — staged implementation plan for the service. May be already complete and resides for historical reasons.
galaxy/<service>/docs/ — per-stage decision records (one file per decision, re-organized after full implementation of PLAN.md).

Decision records when implementing stages from PLAN.md

Stage-related discussion and decisions do NOT live in README.md or ARCHITECTURE.md. Those files describe the current state, not the history.
Each non-trivial decision gets its own .md under the module's docs/, referenced from the relevant README.md.
Any agreement reached during interactive planning that is not obvious from the code must be captured — either as a decision record or as an entry in the module's README.

Scope of PLAN.md changes

The existing codebase of galaxy/<service> may be modified or extended when a plan stage requires it. All such changes must be covered by new or updated tests and reflected in documentation when they affect documented behavior.

Documentation discipline

Code and docs are kept in sync. If an implementation changes behavior described in a .md or .yaml file, update that file in the same patch.
If existing docs are incomplete or wrong for behavior you are already touching, fix them in the same patch.
Do not silently remove commitments from galaxy/<service>/README.md or galaxy/<service>/docs/*.md. When a rule changes, either update it in place with the new agreement, or move the section to a more appropriate doc with a reference kept.
Cross-module impact: if a new agreement requires changes in already-implemented modules, make those changes — code, tests, docs — in the same patch, and record the new rule in ARCHITECTURE.md.

Dependencies

Before adding a new module, check its upstream repository for the latest stable version and use that.
When a well-maintained library clearly outperforms stdlib for a concrete need, do not adopt it silently — propose a short list of 1+ candidates for the user to pick. Default remains stdlib.

Language

All code, comments, identifiers, commit messages, docs, and filenames are written in English.
User-facing chat responses follow the Russian-translation rule from the user-level CLAUDE.md.

2.7 KiB Raw Blame History