Project Instructions

CodeWork adds AGENTS.md and CLAUDE.md files to its system prompt. Use them for what every session should know: how to build and test, conventions, and things to avoid.

This is the built-in codework.prompt.instruction plugin. It’s on by default.

File Names

In each directory, CodeWork uses the first readable file of:

1. AGENTS.override.md
2. CLAUDE.override.md
3. AGENTS.md
4. AGENTS.MD
5. CLAUDE.md
6. CLAUDE.MD

Only one file per directory is used. An .override.md file is handy for personal instructions you keep out of git. An empty file still claims its directory and adds nothing.

Which Directories

CodeWork walks from the session’s working directory up to the sandbox root. Each directory adds at most one file.

• Parents are included. Subfolders are not.
• There’s no global file. ~/AGENTS.md loads only when you work under your home folder.
• In a virtual or remote sandbox, files on your machine aren’t read.
• In a git worktree nested inside the main checkout, the main root’s file is skipped if the worktree has one with the same name.

How They Appear in the Prompt

Files go into <project_context>, farthest directory first, so the closest file has the final word:

<project_context>
Project-Specific Instructions & Guidelines:

<project_instructions path="/home/me/work/api/AGENTS.md">
...
</project_instructions>

<project_instructions path="/home/me/work/api/services/billing/AGENTS.md">
...
</project_instructions>
</project_context>

There’s no size limit, and every file is sent with every request, so keep them short. Files are read again before each model call, so edits apply from your next message.

Example

# API

- Use pnpm. Never npm or yarn.
- Run `pnpm check` and `pnpm test` before you call a task done.
- Database access goes through `src/db/`. Don't write raw SQL elsewhere.
- Ask before adding a new dependency.

Turn It Off

Disable the plugin in your settings:

{
	"plugins": [{ "plugin": "codework.prompt.instruction", "enabled": false }],
}

To add your own sections to the system prompt, write a prompt plugin.