STANDARDS AND CONVENTIONS

HOW SUCH FILES DOCUMENT BUILD COMMANDS, CONVENTIONS, AND PITFALLS A good instructions file is short, concrete, and organized under clear headings. Most contain four kinds of content. First, commands. A build command is the exact text typed to turn the source code into a working program, such as npm run build. A test command is the exact text that runs the project's automated checks, such as npm test. Listing these removes guesswork, and it matters a great deal because the verification gates of Chapter 61 depend on the agent running the correct tests. Second, project layout. A short map says what lives in which folder, so the agent does not wander. Third, conventions. These are the team's habits, such as naming rules, how to format code, how to write commit messages, and which libraries to prefer. A commit is a saved set of changes in Git, and a commit message is the short note describing it. Fourth, pitfalls. A pitfall is a known trap, a mistake that someone already made and does not want repeated. Examples include a folder of automatically generated files that must not be edited by hand, a date format that differs from the usual one, or a test that is slow and should be run only at the end. Write the reason beside non-obvious rules. An agent that understands why a rule exists can apply it sensibly in a new situation. Keep the file short, because every word costs context space each time it loads, as you learned in Part Five. Put the most important rules at the top. Avoid long essays, and avoid vague advice such as write good code, which tells the agent nothing. Never put secrets such as passwords or keys in the file, since the file is committed to the repository and may be seen by many people. Treat the file as living documentation. When the agent makes a mistake that the file could have prevented, add a line to prevent it next time. This is a small feedback loop of the kind described in Chapter 60.