Editorial starter example. Original guide created for the Devex launch; not research, a user testimonial, or a report of community activity.

Repository instructions help when they shorten the path from a task to a verifiable change. General slogans such as “write quality code” leave almost every meaningful decision open.

A small map of a large place

Start with a brief explanation of the product, the main parts of the repository, and where to find deeper context. Link to existing documents instead of copying them. Identify generated directories and files that should not be edited by hand.

Commands people can run

Document installation, the development command, and checks appropriate to the scope of a change. Explain prerequisites without including secrets. If a check requires a local service or special access, say so; otherwise its success or failure can be misleading.

Boundaries with a reason

Choose a few rules that prevent real mistakes: preserving an existing interface, avoiding generated files, separating configuration from code, or handling customer data. Explain why each rule exists and point to a correct example.

A definition of done

Specify the expected report: changed behavior, checks performed, remaining limitations, and deployment status. Writing code, saving a commit, and publishing to users are different steps. Instructions should make it clear which step has been reached.

A starting template

Product: [one sentence]
Repository map: [directories and architecture link]
Local setup: [command and prerequisites]
Verification: [checks by area]
Boundaries: [rule, reason, and example]
Completion report: [change, checks, and gaps]

Choose the filename and location for your tool and verify that it actually reads them. Different tools may apply instructions differently; a familiar filename is not proof that instructions were loaded.

A small experiment: Give a well-defined task to someone unfamiliar with the repository. Wherever they get stuck, ask whether instructions are missing, documentation is hard to find, or the process itself needs to change.