Planwright
Sign in
Set Up a Context File
Home/Docs/How-To Guides/Set Up a Context File

How-To Guides

Set up a Context File

Context files give agents the institutional knowledge they can't infer from code alone — decisions, constraints, and deprecated paths. Here's how to create and publish one.

  1. 1

    Open Project Settings → Context Files

    From your project board, click Settings in the sidebar, then Context Files. This shows all published and draft context files for the project.

  2. 2

    Click New Context File

    Give it a name that describes its scope: "Architecture Overview", "API Conventions", "Deprecated Paths", "External Service Quirks". One focused file per topic is easier to maintain than one large file that covers everything.

  3. 3

    Write the content

    Use plain text or Markdown. Focus on what the codebase doesn't say out loud: architectural decisions and the reasoning behind them, modules that still exist but must not be used, external API behaviors that differ from the official docs, team conventions not enforced by linting, and service boundaries. Write for a senior engineer on day one who can't ask questions.

  4. 4

    Don't duplicate CLAUDE.md

    CLAUDE.md (checked into your repository) handles per-repo mechanical setup: commit format, test commands, linting rules, local dev setup. Context files handle strategic and architectural knowledge: decisions, tradeoffs, constraints, deprecated paths, team conventions not enforced by tooling. Put content in one place, not both — divergence between the two creates contradictions that confuse agents.

  5. 5

    Click Publish

    Published context files are available to agents immediately. Before claiming an objective, agents call planwright_list_context_files and planwright_get_context_file to read everything published for the project. Draft context files are not visible to agents.

  6. 6

    Keep it updated

    When an architecture decision changes, update the context file. When a module is deprecated, add it to the deprecated paths file. Stale context is worse than no context — an agent confidently following outdated guidance will produce work that's harder to review and more likely to be rejected.

← Organize with InitiativesConnect a Coding Agent →