A project instruction file that actually gets followed

The common experience is writing careful project instructions and watching them get partially applied, then gradually not applied at all as a session goes on. The conclusion people draw is that the mechanism does not work.

Usually the file is the problem. It is too long, it describes things that are visible in the code anyway, it states preferences without saying what to do, and the three rules that actually matter are buried in the middle of forty that do not.

Instructions are read as context, and context competes for attention with everything else in the session. A short file of specific, actionable rules holds. A long file of general guidance does not.

'Write clean, maintainable code' is not an instruction. Nothing can be done differently as a result of reading it, and nothing can be verified afterwards.

Compare: 'Every new module gets a test file in the same directory, named the same with a test suffix.' That is checkable. It changes behaviour. It either happened or it did not.

Go through your file and delete every line that fails this test. Most files lose half their length and become more effective, because what remains is no longer competing with filler.

Directory listings, framework names, dependency lists, the general shape of the architecture — all of this is discoverable by looking, and restating it consumes space while adding nothing. Worse, it goes stale, and stale instructions are actively harmful because they are trusted.

Write down instead the things that are not visible:

• Decisions and the reason for them — why this approach and not the obvious one.
• Traps: the thing that looks wrong and is deliberate, the file that must not be edited directly.
• Commands that are not obvious from the repository.
• Constraints from outside the code — a client requirement, a platform limit.

This is the category that saves real time, because it is the category nobody can infer.

Attention falls off through a file, so ordering carries weight. Put the rules that must never be broken at the top and the conveniences at the bottom.

Use short headed sections rather than prose. Use imperative sentences: 'run the build before committing', not 'it is generally a good idea to run the build'. Hedged language reads as optional and is treated as optional.

Keep the whole thing readable in under a minute. If it is longer than that, the useful rules are being diluted by the rest, and the fix is deletion rather than reorganisation.

The file rots. A command changes, a directory moves, a rule stops applying — and the instruction remains, now actively misleading.

Two habits keep it honest. Delete a rule the moment it stops being true rather than leaving it in case it comes back. And when you notice yourself correcting the same thing twice in a session, that is a missing rule — add it while the example is in front of you.

The file should shrink as often as it grows. Most that fail have only ever been added to.

Automatic behaviour. 'Always run the formatter after editing' is a hook, not an instruction — a rule the harness enforces rather than one that has to be remembered.

Long procedures. A multi-step workflow belongs in its own document that gets loaded when relevant, not permanently in context.

Personal preferences that span projects. These belong in a global file, not repeated in every repository where they will drift out of sync.

The project file is for what is true of this project and not inferable from it. Anything else dilutes it.