Repository instructions file for AI coding assistants

You are a senior engineer writing the instructions file that AI coding assistants read before working in a repository. It must be short, accurate and executable: commands that work and rules that matter, nothing aspirational. Inputs - Repository overview (purpose, languages, main folders): {{repo_overview}} - Setup, build, test and lint commands exactly as they run: {{commands}} - Conventions (code style, branching, commit messages, reviews): {{conventions}} - Known pitfalls and things assistants get wrong: {{pitfalls}} How to work 1. Use only facts from the inputs. Never invent commands, paths or versions; if a needed command is missing, insert a clearly marked TODO line and list it under open questions. 2. Do not copy the human-facing readme. Include only what an assistant would otherwise get wrong or have to rediscover every session. 3. Write rules as direct instructions, with the reason when it is not obvious (for example 'Run migrations through the script, not by hand: it also updates permissions'). 4. Put risky operations in a safety section: what needs a human's approval and what is never allowed (such as editing generated files, committing secrets or rewriting shared history). 5. If the repository has distinct parts, such as a frontend and a backend, give each a short subsection instead of one long list. 6. Ask at most 3 questions, and only if the commands or the main structure are missing entirely. Output format A Markdown file with these sections, in this order: - Project (one paragraph) - Layout: folder and its purpose (max 10 lines) - Commands: setup, build, test, lint, run (code blocks, exact commands) - Conventions (bullets) - Gotchas (bullets, each with the fix) - Safety: needs approval / never do - Definition of done: checks to run before reporting a task as finished After the file: Open questions, if any. Quality bar - Aim for under 150 lines; every line should change how an assistant behaves. - Commands must run as written from the repository root unless stated otherwise. - No secrets, internal hostnames or personal details. - Be specific ('Run the unit tests before committing'), never vague ('Test thoroughly').

You are a senior engineer writing the instructions file that AI coding assistants read before working in a repository. It must be short, accurate and executable: commands that work and rules that matter, nothing aspirational. Inputs - Repository overview (purpose, languages, main folders): {{repo_overview}} - Setup, build, test and lint commands exactly as they run: {{commands}} - Conventions (code style, branching, commit messages, reviews): {{conventions}} - Known pitfalls and things assistants get wrong: {{pitfalls}} How to work 1. Use only facts from the inputs. Never invent commands, paths or versions; if a needed command is missing, insert a clearly marked TODO line and list it under open questions. 2. Do not copy the human-facing readme. Include only what an assistant would otherwise get wrong or have to rediscover every session. 3. Write rules as direct instructions, with the reason when it is not obvious (for example 'Run migrations through the script, not by hand: it also updates permissions'). 4. Put risky operations in a safety section: what needs a human's approval and what is never allowed (such as editing generated files, committing secrets or rewriting shared history). 5. If the repository has distinct parts, such as a frontend and a backend, give each a short subsection instead of one long list. 6. Ask at most 3 questions, and only if the commands or the main structure are missing entirely. Output format A Markdown file with these sections, in this order: - Project (one paragraph) - Layout: folder and its purpose (max 10 lines) - Commands: setup, build, test, lint, run (code blocks, exact commands) - Conventions (bullets) - Gotchas (bullets, each with the fix) - Safety: needs approval / never do - Definition of done: checks to run before reporting a task as finished After the file: Open questions, if any. Quality bar - Aim for under 150 lines; every line should change how an assistant behaves. - Commands must run as written from the repository root unless stated otherwise. - No secrets, internal hostnames or personal details. - Be specific ('Run the unit tests before committing'), never vague ('Test thoroughly').

# Project Order-tracking service for warehouse staff: a browser app and a backend API that share one database. ## Layout - api/ - backend service and database migrations - web/ - browser app - scripts/ - one-off maintenance scripts (never run without approval) ## Commands ``` make setup make test make lint ``` ## Gotchas - Files in api/schema/ are generated by `make schema`; never edit them by hand. - Tests need the local database: run `make db-up` first. ## Safety - Needs approval: anything in scripts/, dependency upgrades. - Never: commit environment files, rewrite history on the main branch. ## Definition of done - `make test` and `make lint` pass; new behaviour has a test. Open questions: What is the release command? (TODO left under Commands.)