Workspace instructions

Workspace instructions are the standing notes you keep in files beside your work, so DataMind Oda follows the same rules every time it works in that folder. They add to the rules your company sets for every chat; see Manage DataMind Oda for your company.

Which files Oda reads

Oda finds instruction files in two places, broadest first:

1. Your Oda home folder. An AGENTS.md in your Oda home folder applies wherever you work on this computer. Oda's home folder and settings files shows where that folder is.
2. Your project, from the top down. Oda walks from the top of the project toward the folder the chat works in, reading the files it finds on the way. The top is the nearest folder at or above the working folder that holds a .git folder; when there is none, the walk starts at the working folder itself. The folder a chat works in is its workspace.

In each folder, Oda reads a base file named AGENTS.md or CLAUDE.md, and a local overlay named AGENTS.local.md or CLAUDE.local.md beside it.

• More specific instructions win. A file deeper in the tree takes precedence over one nearer the top.
• Same folder only. A file must sit directly in the folder it applies to; a name that contains a path is not read.
• Read once. When two files in the same folder hold the same text, Oda uses the text once.
• Links are followed. An instruction file reached through a symbolic link is read.

Add or edit an instruction file

1. Create a plain text file named AGENTS.md in the folder the instructions should cover: your workspace folder for the whole project, a subfolder for just that part of it, or your Oda home folder for your work everywhere.
2. Write the instructions in plain text or Markdown. Say what should always happen, what to avoid, and how finished work should look.

# Project notes
- Run the test suite before reporting a task done.
- Keep generated reports in the reports folder.

To change the rules later, edit the file. The change is picked up as work goes on, and the chat records it.

When Oda picks up your files

• A new chat loads the instructions with its first message.
• Oda re-reads them after it reads, writes or edits files in the folder, so a file in a subfolder joins when work reaches that folder.
• A chat you come back to brings them up to date.

When a file joins, changes or is removed, Oda notes it in the chat's records:

System prompt, context and compaction shows where these records live and how to open them.

When the files do not all fit

Oda sends the instruction files within a fixed budget.

• When the files do not all fit, Oda leaves out whole broader files before it cuts the most specific one, so the instructions closest to the work survive.
• Instructions are never summarised: a file that is cut is cut, not rewritten.
• Oda notes in the chat's record which files were left out and which file was cut.

To keep everything in play, keep the files short, and move detail that concerns one part of the project into that part's folder.

What Oda does not read

• Lowercase names such as agents.md.
• A .claude/rules/ folder.
• @path imports written inside an instruction file.

Write the notes in the file itself, and name it AGENTS.md or CLAUDE.md, or the matching local overlay.

Questions, answered

Where does an instruction file belong?

In the folder the instructions should cover: your workspace folder for the whole project, a subfolder for just that part of it, or your Oda home folder for your work everywhere. The file must sit directly in that folder; a name that contains a path is not read.

Which file name should I use, AGENTS.md or CLAUDE.md?

Either. Oda reads AGENTS.md and CLAUDE.md the same way, and an AGENTS.local.md or CLAUDE.local.md overlay beside them. When two files in one folder hold the same text, Oda uses the text once.

Do folder files replace the company's Organization instructions?

No. The company's Organization instructions are added to every Oda chat, and the files in a folder add the rules for work there. Company-wide rules belong in the company settings, not in a folder file.

When do my instructions start applying?

A new chat loads them with its first message. Oda checks them again after it reads, writes or edits files in the folder, and a chat you come back to brings them up to date.

Why has my change not applied yet?

Oda re-reads the files as work goes on, not the moment you save. The change is picked up after Oda next reads, writes or edits files in that folder, or when the chat is resumed; right after a save, the older text can still be in use for a moment.

What do the instruction notes in the chat mean?

They name a file whose instructions joined or changed.

• Updated instructions from: <path>: the file changed after it was loaded, and the new text is used from this load on.
• Instructions removed: <path>: the loaded file is gone. The note adds The previously loaded instructions from this file no longer apply.
• Additional instructions from: <path>: a file for a more specific folder joined. The note adds These instructions apply to work under <scope>.

What happens if the instruction files are too large?

Oda sends them within a fixed budget. When they do not all fit, Oda leaves out whole broader files before it cuts the most specific one, so the instructions closest to the work survive; a file that is cut is cut, never rewritten. Keep the files short, or move detail that concerns one part of the project into that part's folder.

Are symbolic links to instruction files read?

Yes. An instruction file reached through a symbolic link is followed and read.

Does Oda read lowercase names, a rules folder or imports?

No. Lowercase names such as agents.md are not read, a .claude/rules/ folder is not read, and an @path import written inside an instruction file is not interpreted. Name the file AGENTS.md or CLAUDE.md, and write the notes in the file itself.

Where can I see which instruction files Oda loaded?

In the chat's records: the instruction record shows which workspace files were loaded, added, updated or removed, and opening it shows the material itself. System prompt, context and compaction covers the records.