Skip to main content

​
Overview

A structure file tells Qontext how a folder is organized: what belongs in it, how files are named, and how careful automatic updates must be before changing anything. Agents read this guidance every time they work new information into your repository, so content keeps landing where your team expects it. Any folder can carry one structure file, named .qontext.structure.md and stored directly in the folder. The workspace root can also have a structure file: /.qontext.structure.md. Structure files are folder configuration, not knowledge: they are never retrieved as content and never appear in the context your AI tools get from Qontext. A self-maintaining repository is only useful if it stays organized. Structure files are how you keep control of the layout without reviewing every change yourself:
  • Consistent placement. New information lands in the folders and files your team decided on, following your naming rules.
  • Per-folder confidence. Strictness sets how sure an update must be before it touches a folder, so curated folders stay conservative while working areas stay flexible.
  • No forced fits. Content that has no good home under your structure is skipped rather than squeezed into the wrong folder.

​
Anatomy of a structure file

A structure file has two parts:
  • Strictness (front-matter) sets how confident the continuous update agent must be before changing the folder or its contents.
  • Guidance (the body) is plain prose: what belongs, how files and folders are named, and what does not belong here.

​
Strictness levels

A folder without a structure file, or without a recognizable strictness value, uses moderate. When new information clears no folder’s bar, continuous updates skip it and explain why; they never force it in or invent a new folder for it.

​
Inheritance

Guidance flows down the folder tree:
  • Guidance from the workspace root and parent folders applies to their descendants.
  • When two rules conflict, the structure file closest to the content takes precedence.

​
Structuring the guidance

A folder holds files and subfolders, and a continuous update agent acts on both: it adds a file or folder, edits an existing one, or deletes one. Prose that only says what belongs leaves editing and deletion to improvisation. Curated folders stay cleanest when the guidance is written in named sections that cover all of it:
  • What belongs here: the content the folder holds, how it maps to files and subfolders, and where near-miss content goes instead.
  • File and folder requirements: naming, the one-to-one mapping from each source item to a stable file or folder, and the shape every file follows.
  • Allowed changes: what an update may do on its own, such as adding, updating, and small corrections.
  • Disallowed changes: what needs your confirmation, such as rewrites, splits, merges, renames, moves, deletions, and placeholder files.
Not every folder needs all four. A loose working area can be two lines; reach for the full shape when a folder is curated, mirrors a source, or has a fixed layout, because that is where an unguided update does the most damage. An aggregating folder with a fixed per-file structure, written in this shape:
.qontext.structure.md

​
Setting up a structure file

1

Find the Structure row

In the Context tab, open a folder and select Structure at the top. The workspace root has the same entry above its top-level items.
2

Write the guidance

Click the row to create or open the folder’s .qontext.structure.md. Describe how the folder is organized, and set the strictness in the front-matter.
3

Let it work

From now on, continuous updates follow the guidance whenever they place or change content in this folder. Every update still shows up in the Changes tab, so you can watch the structure hold.
Delete a structure file to remove its guidance from the folder. Structure files are Markdown files, so you can edit them directly or ask a context agent to draft one for you.

​
Best practices

An update agent acts on the file’s words without you reviewing each change. Everything below follows from that:
  • Write testable rules, not intentions. The agent follows what the words check for, not what you meant. “One file per customer, named after the company” is testable; “keep it organized” is not.
  • Cover adding, editing, and deleting. The agent does all three, to files and folders. Guidance that only says what belongs leaves the rest to improvisation, so state what it may do alone and what needs confirmation.
  • Resolve the ambiguity yourself. Any choice you leave open, the agent makes for you. Spell out the tie-breaker for content that could sit in two places (say which folder wins), and say where content that fits nowhere goes instead of landing here.
  • Design against compounding. Every rule runs on every update, so a small gap becomes a pile. Tie each item to a stable identity so updates land on it rather than beside it, and forbid empty or placeholder files.
  • Set strictness by the cost of a wrong change. Strict for canonical records and mirrors, permissive where capturing beats precision. Start at moderate and adjust from what shows up in the Changes tab.

​
Prompts to get started

You don’t have to write structure files yourself. Ask a context agent:
  • “Look at how /Customers is organized today and write a structure file that keeps it that way.”
  • “Which folders don’t have a structure file yet? Suggest guidance for the three busiest ones.”