AGENTS.md vs. System Prompt: Scope, Priority, and Purpose

AGENTS.md is a Markdown file committed to a repository that AI coding tools read at the start of each session to learn project-specific conventions. A system prompt is a message an application sends with every API request to configure how the model behaves in that application. Both give an AI assistant instructions, but they operate at different scopes and serve different purposes. Tools like fenbs hold the decisions, rules and progress that belong in neither: the live project record that changes as work progresses.

Choosing correctly between the two, and knowing what belongs in each versus what belongs in a shared project record, keeps instructions current and prevents them from conflicting.

What is AGENTS.md?

AGENTS.md is a convention for a Markdown file at the root of a repository that AI coding tools, including Claude Code, read automatically when they open a session in that directory. The file typically contains the project's language, framework, coding conventions, build commands, testing approach and any constraints that should apply to every AI session in that codebase.

The key property is that it is part of the repository. It is checked in with the code, versioned alongside it and available to any tool that supports the convention. Team members who join the project and connect an AI coding tool get the same instructions automatically. For examples of what to include, see AGENTS.md examples.

Not every coding tool reads AGENTS.md. Claude Code does. Tools that use different file names, like GEMINI.md for Gemini CLI, follow the same principle with a different convention. Does Claude Code read AGENTS.md? and does GitHub Copilot support AGENTS.md? cover the current support status for those tools.

What is a system prompt?

A system prompt is a message an application sends to the model with every API request, before the user's input. It tells the model what role it plays in that application, how it should format output, what it is and is not allowed to do, and any standing instructions that apply to every conversation in that app.

A system prompt is set by the application developer or the platform, not by the user or the repository. When you use a custom GPT, a configured Claude project, or any AI-powered product, there is usually a system prompt behind the interface that shapes the model's behavior. For examples and patterns, see system prompt examples.

The key property is that a system prompt is outside the codebase. It is not checked into the repository, and it is not visible to someone reading the source code unless the developer chooses to share it. It applies at the application level, not the repository level.

How they differ

Which takes priority?

When both are present, the application's system prompt typically takes priority over an instruction file because the system prompt reaches the model first in the context hierarchy. In Claude Code, a system prompt set by the application combining Claude Code's capabilities with a custom configuration would outrank the AGENTS.md. In a direct Claude Code session with no application wrapper, the AGENTS.md instructions are prominent in the starting context.

In practice, conflicts between AGENTS.md and a system prompt are unusual because they operate at different levels. AGENTS.md says how code in this repository should be written; a system prompt says how the application should behave. A conflict usually means one of them is trying to control something the other should own.

What belongs in each

AGENTS.md is the right place for project-specific facts that every coding session needs and that belong with the code: naming conventions, forbidden patterns, test commands, architecture notes, pointers to important files.

A system prompt is the right place for application-level configuration: the model's role in the product, global formatting preferences, topics it should not address, and safety instructions specific to that application's use case.

Neither is the right place for decisions that change over time. A decision about the database schema, an agreement to use a particular library, or a rule about which endpoints require authentication is a project decision. It belongs in a record where it can be updated, superseded and linked to the discussion that produced it. Putting a mutable decision in a static instruction file means it will eventually be wrong. For agent memory systems that handle changing context, see choosing an agent memory system and context engineering for multi-agent systems.

When an AGENTS.md file starts accumulating project decisions alongside code conventions, those decisions belong in fenbs. Write the decision once with the reason, the person who made it, and the context behind it. Connected assistants read it at the start of each session. Update the decision when the project changes and the old one is superseded, keeping the history of what was decided and when.

How to do this with fenbs

1. Create a free account and add your project.
2. In your repository, create or update AGENTS.md with stable code conventions: language, framework, build commands, architectural constraints.
3. In your application configuration, set a system prompt with application-level instructions: persona, global format preferences, safety rules.
4. Connect Claude Code or another supported tool from Integrations. Add the project to fenbs.
5. In Decisions and rules in fenbs, write the decisions that change over time. When AGENTS.md or a system prompt references a decision, move it to fenbs and replace the text with a pointer.

The division of responsibility is: AGENTS.md owns the stable code conventions, the system prompt owns the application persona, and fenbs owns the decisions and progress. Each stays current within its scope without conflicting with the others.