June 17, 2026 — admin

CLAUDE.md

Notes on CLAUDE.md configuration

Core Project Guidelines:

  • You must create a timestamped dev log file in game/doc/devlog folder after each change
  • Devlog must include the list of tasks and the plan that initiated the changes
  • Devlog must include the section of critical analysis of each document and identify potential issues with implementation; add identified issues and challenges to the CHALLENGES.md document
  • Ignore PROMPTS.md in the workspace root
  • When starting on a new task (usually a new chat), create a game/docs/todo/TODO_{TASK}_.md document
  • If there are any structural changes to the project, update the TODO_{TASK}_.md document
  • Future work is located in ‘docs/todo/TODO_FUTURE_WORK.md’, look at it for new tasks and keep it up to date with the ideas we come up with
  • If anything is unclear or you need clarification, you must ask
  • NEVER EVER ASSUME ANYTHING, ask me
  • Always ask me before starting on a task
  • Always work step by step and show reasoning
  • Always ask before committing and pushing
  • Update TODO_{TASK}_.md with any new tasks that you identify during development, and check off completed tasks before committing or pushing

Documentation Guidelines:

  • Documentation for this project is in the doc folder
  • The Game/doc folder contains the following
    • ARCHITECTURE.md - GENERATED ECS map (systems catalog + execution pipeline + system/component usage matrix + component catalog). Regenerated at pre-build by tools/gen_architecture.py; do not edit by hand (it is committed for browsing, but every build overwrites it). Start here for a structural overview of components and systems.
    • CONCEPTS.md - hand-written mental models (identity, dual-field handles, init tags, save/load, task lifecycle, cadence, dynasty/economy, attribute pipeline). The why the generator can’t extract. Edit only when a concept changes, not on implementation tweaks.
    • TDD.md - technical design document
    • todo/TODO_{TASK}_.md - a checkable to-do list of everything we need to work on to complete this project
    • ‘todo/TODO_FUTURE_WORK.md’ - a checkable to-do list of future work, like a collection of ideas for the future, that we can pick up when we finish the current work
    • CHALLENGES.md lists technical challenges for this project
  • Structure (what exists, who touches what) is captured by the generated ARCHITECTURE.md; concepts/invariants live in CONCEPTS.md; point-in-time rationale lives in doc/devlog/ and known sharp edges in CHALLENGES.md. Do not hand-maintain a parallel structural doc — it drifts.