Best Practices: Bootstrap Prompt – Gunther Popp – Software Architect & AI‑Driven Development Expert

A good bootstrap prompt gives AI coding agents exactly the context they need for a task. What belongs in it, what does not, and how should it be designed?

Introduction

A professional AI-Driven Development process requires more than choosing an AI coding tool. It needs control mechanisms that structure the collaboration between humans and machines and help produce consistent results. One of the most important of these mechanisms is the bootstrap prompt.

AI coding agents are session-based: they start with an empty context and only build it up over the course of a session. A bootstrap prompt is an instruction that is executed at the beginning of each session to provide the agent with the project context it needs. Without a bootstrap prompt, the agent has to discover on its own which architecture, conventions, documentation, and rules apply in the project. Even if that works, it is at least inefficient and expensive. There is also a risk that inconsistencies creep into the generated artifacts because the agent did not find important information or interpreted it incorrectly.

Bootstrapping is not just about writing a prompt once. It is Context Engineering: the systematic provision of relevant context as part of the development process.

Types of Bootstrap Prompts

A bootstrap prompt is a best practice, not a specific file format or fixed template that must always be copied 1:1. There are different ways to integrate a bootstrap prompt into the development process, but in practice it usually comes down to two variants:

Always-on Instructions (AoI): Project-wide or even globally valid rules that are loaded automatically, for example AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md. They should be concise and contain only the most important rules that apply globally or across the whole project.
Session Bootstrap: A manually loaded prompt at the beginning of a new session. It assumes that the Always-on Instructions already apply and adds the specific context for the current session depending on the task at hand, for example implementation or code review.

AoI Prompts

The most popular alternatives for Always-on Instructions are:

AGENTS.md: The most important open standard for AoI prompts. Behind AGENTS.md is the Agentic AI Foundation under the umbrella of the Linux Foundation, which makes it a cross-vendor, neutral organization. The standard is supported by Codex, Cursor, and GitHub Copilot, among others, but interestingly not by Claude Code (see below). Codex, for example, considers a global ~/.codex/AGENTS.md file and individual AGENTS.md files in the project structure, from the root down into individual directories. Developers can also define their own rules in an AGENTS.override.md file, which is typically added to .gitignore. All discovered files are appended “from top to bottom” and used as the starting point for the session context. The official website https://agents.md provides many examples for designing AGENTS.md files.
CLAUDE.md: As mentioned above, Claude Code uses its own AoI variant with CLAUDE.md. Similar to AGENTS.md, you can define a global AoI prompt (~/.claude/CLAUDE.md) or add specific prompts in the project structure. There is also CLAUDE.local.md as a local override variant. If, like me, you work with several AI coding tools, you should define the actual AoI prompts via AGENTS.md files and then include them in CLAUDE.md via an @AGENTS.md import.

There are other variants, such as Copilot Instructions or Claude Code Rules, but I will not cover them in detail here. In my view, AGENTS.md and CLAUDE.md are sufficient as AoI prompts for most use cases. Session bootstrap prompts are the better choice for all task-specific rules.

Session Bootstrap Prompts

A good session bootstrap prompt answers five questions:

What is the project context? The agent needs to understand what it is dealing with. Good sources are usually READMEs, architecture documentation, the semantic data model, and the most important project files.
Which rules always apply? This is about constraining the agent’s room for action, for example “No refactorings without asking first, no changes outside the workspace”, compliance with the architecture, coding conventions, test requirements, documentation language, and existing patterns.
Which commands verify the result? Build, tests, linting, type checks, formatting, and project-specific smoke tests where applicable.
How should the agent handle uncertainty? For example, I specify that agents should ask instead of guessing when in doubt, explicitly state assumptions, and discuss contradictory documentation or specifications with me.
How does the development process work? Agents need to understand the AI-Driven Development process before they can execute it. For example: the starting point is always a feature file, an implementation plan is created from it as a Markdown file, the plan must be approved before implementation begins, and the implementation result is documented in a separate Markdown file so it can feed into the next iteration.

Using a session bootstrap prompt is straightforward: paste it into the chat window or ask the agent to load the bootstrap prompt from the prompt file. There are certainly fancier options with custom commands or skills, but the KISS variant has worked well for me so far.

I created two examples of session bootstrap prompts that you can look at: a bootstrap prompt for implementation of features in a Java project with Maven and a bootstrap prompt for code reviews.

What Does Not Belong in a Session Bootstrap Prompt?

The biggest risk when designing session bootstrap prompts is that they become too large and hard to understand. It is important to keep the bootstrap limited to the information that is truly relevant. Here are some things that do not belong in the session bootstrap prompt:

Separate bootstrap and task: The bootstrap builds context. The concrete implementation task comes afterwards, directly in the chat window.
No secrets: Tokens, API keys, passwords, and internal access credentials do not belong in prompts.
No repetition of Always-on Instructions: If a rule already exists in AGENTS.md or CLAUDE.md, the bootstrap should not copy it. It should only add what applies to this session or work mode.
No repetition of project documentation: Architecture documentation, semantic data model, coding guidelines, specifications, and similar documents must not be copied into the bootstrap. Instead, the bootstrap should instruct the agent to read the relevant documents and extract the most important information from them.
No rules that are better enforced technically: Formatting, linting, type checks, and similar concerns should be enforced by tools. The bootstrap points to these commands; it does not replace them.

Conclusion

In my view, the bootstrap prompt is not an optional extra but a central artifact in professional AI-Driven Development. It ensures that agents understand the project context before they start working. The time invested in a well-maintained bootstrap prompt pays off through more consistent results and fewer corrections.

I recommend creating a very lean AoI prompt and putting most rules and context information into session bootstrap prompts, which can then be adapted depending on the work mode (implementation, code review, refactoring, …). Personally, I also largely avoid hierarchical AoI prompts (for example AGENTS.md files in multiple directories), because they make it harder to keep an overview and increase the risk of inconsistencies.

Besides the bootstrap prompt, there is another important control mechanism in AI-Driven Development: the implementation plan, which breaks execution down into controlled, verifiable tasks. But more on that in the next post.