Begin with the business and the expected result
Explain what the project does, whom it serves and which outcome it needs to preserve. This opening gives meaning to subsequent instructions and helps assess changes proposed by the agent. Use concrete business information rather than a lengthy company introduction that does not affect how the relevant work should be performed.
In a hypothetical example, an internal portal might allow the team to prepare proposals and obtain approval before sending them. That purpose guides permissions, statuses and notifications. Calling it a modern AI application does not explain who uses it or what must happen for it to fulfil its objective.
Add the scope and what has been excluded. If the portal does not accept payments or give customers access at this stage, record those decisions. The agent can suggest developments, but documentation should distinguish present requirements from features that might appear attractive in a broader product with a different purpose.
Planning before developing an application supplies the foundation. The instruction file does not need to repeat the whole plan: it can summarise stable points and indicate where detailed requirements are available. That guides execution without creating two lengthy descriptions that will be difficult to keep consistent as the project develops.
To prepare your next step, explore Developing applications with AI.
Write boundaries that can guide a task
Translate preferences and restrictions into instructions specific enough to guide a choice. State which actions need approval and which decisions should not be reopened without a reason. A useful rule explains what the agent should do in a real situation instead of merely declaring a general intention to produce high-quality work.
In my project, recording the use of European Portuguese and distinguishing assistant suggestions from confirmed decisions helps guide collaboration. These instructions remain relevant when the task changes. Nobody needs to reconstruct the conversation in which each arose to understand how they should apply to the next piece of work.
A business project may need to state that preparing a message does not authorise sending it, or that changing commercial conditions requires a decision from the responsible person. The wording should identify the boundary and the decision-maker. Avoid vague statements that leave the agent to decide which actions seem too important to execute.
Written rules should correspond to application access and controls. A document prohibiting consultation of particular data does not replace technically restricting that access. Use instructions for expected behaviour and necessary references while keeping credentials and confidential information outside documents that circulate with the project or are shared with other people.
Record stable decisions and point to the detail
Keep decisions that continue to constrain future work in the file and refer detailed material to separate documents. A choice of language, approval process or visual identity may deserve permanent visibility; one execution's result can remain in history. Judge inclusion by whether it helps guide the next relevant task in the project.
If the company uses a particular visual identity, identify the approved reference and the location of original materials. Asking for a consistent appearance is insufficient without showing what it should match. Equally, preserving that decision does not require inserting every image and every design discussion into the main instruction document.
Selecting relevant context for AI helps choose the appropriate level of detail. A short rule can point to a lengthy specification, provided the reference is clear and accessible. The agent should be able to tell when it needs that detail and which document represents the current decision.
Explain the reason when it prevents misinterpretation. Preserving an old address because distributed materials still use it is different from keeping every address out of habit. The decision's context helps assess a future change without turning the rule into a prohibition whose purpose nobody understands or can explain.
Include how to work and how to verify
Indicate how to find the project, perform relevant checks and report the results of a change. Match detail to the team and actual environment, retaining instructions someone can verify. The objective is checkable work, without confusing a suggested list of tests with evidence that those tests were actually performed and passed.
For software, it may make sense to reference existing validation commands and explain which changes require permission tests or interface review. If you do not know the commands, ask the agent to identify and confirm them in the project before recording them. Copying a generic list can create instructions nobody can fulfil.
Define how completion should be described: what changed, what was verified and which limitation remains. Distinguish a local preview from a version placed online and an attempted action from a confirmed one. These details make status understandable to the person who will decide the next step in the work.
Preparing the first working session helps identify environment and access references worth documenting. Record where information can be found and who can provide it without copying secrets. Instructions should facilitate authorised work and make it possible to recognise when a necessary condition for performing that work is missing.
Maintain a primary reference and confirm it is read
Choose a primary source for project instructions and keep files used by different tools consistent. Check reading behaviour in the installed environment instead of assuming that different filenames work identically. Review rules when decisions or processes change, removing contradictions from active instructions while preserving history wherever it remains useful to the team.
CLAUDE.md and AGENTS.md are filenames used for agent instructions, but that does not mean every product loads them in the same way. Location, configuration and support can differ. Before relying on a rule, confirm that the agent received the relevant document and understood how it applies to the current task.
If you maintain versions for different tools, avoid editing them independently without a shared reference. An updated approval rule in one file and an outdated rule in another can produce inconsistent behaviour within the same project. Choose and test the technical method for sharing instructions in the environment used, without assuming automatic compatibility.
Finally, read the document as someone arriving at the project for the first time. They should understand its objective, boundaries, active decisions and where to verify the work. When discovering those answers requires reading the entire history, reorganise the file and return detailed records to their appropriate locations.