TL;DR
- Place general ai instructions in your repository, for example at
src/docs/ai/ai-instructions.md - Specific instructions per coding assitant are symlinks to your general ai-instructions.md
AI Coding Assistants?
In recent years, generative artificial intelligence has become a part of everyday life. Apart from text, image and video generation, there also exist AI coding agents. The “I” for “intelligence” in AI is slightly misleading in that context. You need to give coding assistants precise instructions so they carry out tasks the way you want them to.
AI Assistant Instructions?
Different coding assitants require differnt instructions. While GitHub Copilot needs a copilot-instructions.md in the .github folder of a repository, windsurf and cursor need a “rules file” (.windsurfrules and .cursorrules respectively).
The whole point of using AI is to have less work you need to do. Maintaining a whole set of instructions is quite the opposite. Implementing the idea of an RFC proposal of Sasha Levin regarding the usage of AI coding assistants in the Linux Kernel project mitigates this overhead:
Tip
Adding unified configuration files fore the various AI coding assistants that are all symlinked to one general AI instructions file.
Structure of AI Assistant Instructions
My experience has been that it is best to structure the instructions file. You need to give information about the codebase, which is relevant, such as the tech stack, key software components and the basic business logic workflow. A second section with development instructions such as “follow coding standards and best practices” or “use functional expressions in PHP and Javascript” is followed by general AI instructions like “If you write any code mention yourself within the commit in the format: “Co-developed-by: {Provider} {Model}” Example: ‘Co-developed-by: Claude claude-4-sonnet’”.
All instructions depend on the tech stack and the software you use. The following folder structure and exemplary instructions file are based on this Symfony skeleton repository for showcase purposes.
Repository Structure
Exemplary AI Instructions
Below pdf shows what instructions might look like for a Symfony project that uses docker and just.
View PDF