Structure by Concern and the Router File
Goal — Organize the project by what things are, and make CLAUDE.md a router that points rather than repeats.
By the end — A project sorted into clear kinds of place, with a short CLAUDE.md that points to docs/design.md and docs/notes.md instead of duplicating them.
Map first — What kinds of things live here? What is the smallest set of files a task needs?
1Understand structure by concern
Group files by what they are, not by when you made them. Notes go with notes, code with code, generated files on their own.
Explain what "organizing a project by concern" means and why it helps an AI agent work in it.2Give the project a notes home
Create a docs folder with a design.md that describes this site's look in a few lines, and a notes.md for decisions.Now the project has three clear kinds of place: docs for thinking, css/js for code, and the pages themselves.
3Learn the router pattern
A router file points to detail that lives elsewhere; it never copies that detail in. One fact, one home.
Explain the "router" pattern for a CLAUDE.md — pointing to other docs instead of duplicating them.4Turn CLAUDE.md into a router
Rewrite CLAUDE.md so it briefly describes the project and points to docs/design.md and docs/notes.md, without repeating their contents.Open it and read. The root file is now short and stable; the details live in the files it points to.
5Test that it holds
Check that the pointer actually works by asking a question the router should answer.
If I want to change the site's look, which file should I edit?It should send you to docs/design.md, because CLAUDE.md pointed there. That is the router working — context is findable, not scattered.
Recap — You sorted the project by concern and turned CLAUDE.md into a router that points to its docs instead of repeating them.