The Project Rules I Give My AI Coding Assistants

Some requirements come up in almost every session with a coding assistant. Use the project's conventions. Check the installed framework documentation. Keep existing links working. Run the checks before calling a change complete.

I want those requirements available when work starts, instead of having to repeat them across several prompts. That's why I've been creating project-specific instructions, reusable skills, and guardrails as part of my AI-assisted workflow.

The details vary between repositories, but the useful categories stay fairly consistent: project facts, decisions worth preserving, and a clear way to check the work.

Start with the facts of the repository

The first useful information is concrete: the stack, the package manager, where important code lives, and the commands that verify a change. An assistant can discover some of this, but an instruction file gives it a reliable starting point.

I also want to know where the guidance lives for each tool. When several assistants work in a repository, keeping the core rules consistent helps avoid conflicting expectations.

The tools have their own instruction mechanisms. Codex documents AGENTS.md as durable repository guidance, while Copilot supports repository instructions in .github/copilot-instructions.md. I check the relevant tool's behavior rather than assuming every assistant loads every file automatically.

Record decisions that matter to changes

The most useful rules explain something an assistant could otherwise get wrong.

One useful rule is to check the documentation for the installed framework version before using its APIs. A familiar-looking implementation copied from an older version can still be unsuitable for the current project.

Other rules might identify shared validation helpers, the existing component library, or the approved way to access a database. Naming the relevant module is more actionable than asking the assistant to follow best practices. It gives the assistant a place to check before introducing another pattern.

Compatibility requirements deserve space too. An internal cleanup may need to preserve an API response, a stored value, or an existing URL. Those boundaries should be visible before a refactor starts.

A small instruction example

This is a generic example of the kind of guidance I'd include, rather than a complete configuration for a particular repository:

# Working in this repository

- Check the installed framework version and its documentation.
- Reuse existing helpers, components, and data-access patterns.
- Preserve public contracts unless the task explicitly changes them.
- For unclear tasks, use plan mode and ask focused questions.
- Review suggestions and revise the plan before implementation.
- Run the repository's documented checks and report the results.
- Review the final diff for changes outside the task.

In a real instruction file, I'd replace general references with the relevant paths and exact commands. That makes the guidance easier to use and avoids making the assistant guess what counts as a check.

Separate rules, skills, and the current request

I think about these as three different places to put information.

• Project instructions hold requirements that apply repeatedly in the repository.
• Reusable skills describe a task-specific process that can be used when that work comes up.
• The current prompt explains the particular change I want now, including its scope and acceptance criteria.

For example, preserving an API contract belongs in the project rules. A repeatable process for reviewing a database migration could be packaged as a skill. The specific schema change and its acceptance criteria belong in the current request.

That division keeps a long procedure from filling the instructions for every unrelated task. It also makes it easier to update a particular workflow when the process changes.

Claude Code's guidance on short instruction files and task-specific skills is useful here. It also explains why instructions should be treated as guidance rather than guaranteed enforcement.

Make room for planning questions

For an unclear or substantial change, I want the assistant to enter plan mode and help work through the requirements. I ask it to inspect what exists, raise questions, and suggest alternatives. I review the answers and ask for changes to the plan until the behavior and verification steps are clear.

Several rounds can be useful when each one resolves a real decision. For example, a migration plan may need another pass to account for old records or a rollback path. I want those assumptions checked before implementation builds on them.

This has helped me reduce the debugging and rework that come from coding against the wrong requirements. The rule gives the assistant permission to ask; the current task determines how much discussion is needed. A small, well-defined edit usually needs much less planning.

Keep the rules current and verify the work

An instruction file needs maintenance alongside the project. When a command, dependency constraint, or convention changes, the guidance needs to change too. Conflicting instructions give the assistant another problem to resolve.

I also don't treat a written guardrail as an access control. Tests, permissions, and CI still have their own jobs. Asking an assistant to run the build doesn't prove it passed; I want the result and a clear account of anything it couldn't check.

The benefit I'm aiming for is less repeated explanation and fewer avoidable corrections over time. I haven't measured a token-saving percentage. The instructions themselves also take context, so I want them to earn their place.

I've also written about my first year using coding assistants and context and token usage, including how I use compaction during longer sessions.