Use CLAUDE.md and AGENTS.md to Steer Local Agent Runs

CLAUDE.md and AGENTS.md files are where many AI coding workflows become repeatable.

One prompt can tell Claude Code or Codex what to do today. Repository instructions tell the agent how the project works every time: package manager, test commands, branch rules, review expectations, forbidden areas, and local gotchas that should not be rediscovered in every session.

Junction is a local-first control surface, so those files matter. The daemon runs on your machine, the agent works in the repository where the instruction files live, and the browser or phone gives you the control surface for output, approvals, diffs, and session state.

The goal is not to make instruction files huge. The goal is to make them useful enough that every local agent run starts with the same basic map.

What The Provider Docs Say

Claude Code and Codex use different instruction-file conventions.

The official Claude Code memory docs explain that Claude Code reads CLAUDE.md, not AGENTS.md. Those docs also describe a pattern for repositories that already use AGENTS.md: create a CLAUDE.md that imports AGENTS.md, then add Claude-specific guidance below the import.

OpenAI's article on the Codex agent loop describes Codex reading AGENTS.override.md and AGENTS.md from the relevant folders, subject to size limits and configuration.

The practical result is simple:

• Use AGENTS.md as a shared project map when Codex is part of the workflow.
• Use CLAUDE.md for Claude Code.
• If you want one shared source, import or point from one file to the other in the way each provider supports.
• Keep provider-specific details in provider-specific sections.

Do not assume every provider reads every file the same way.

What Belongs In Repo Instructions

Good instructions are short, operational, and testable.

Include:

• package manager and install command,
• focused test commands,
• typecheck and lint commands,
• branch and pull request expectations,
• directories that should not be edited casually,
• local setup caveats,
• coding conventions that are not obvious from the code,
• when to stop and ask before editing.

Avoid:

• long architecture essays,
• stale product roadmaps,
• vague style preferences,
• duplicated README content,
• secrets or credentials,
• instructions that contradict tests or CI,
• rules that only one person understands.

An instruction file should act like a map, not a novel.

Example Instruction File

Agent Instructions
 
Use `pnpm` from the repository root.
 
Before changing code:
- inspect the nearest tests,
- keep changes scoped to the requested package,
- do not modify pricing, auth, or provider setup unless the task explicitly asks for it.
 
Useful commands:
- `pnpm --filter @junctionpanel/site run test`
- `pnpm --filter @junctionpanel/site run typecheck`
- `pnpm --filter @junctionpanel/site run lint`
 
Pull request expectations:
- include the focused verification command,
- call out any skipped checks,
- do not open a PR with unrelated generated files.

That file gives the agent useful defaults without crowding out the task.

How Junction Uses This Context

Junction does not turn repository instructions into a magic guarantee. It gives you the surfaces to see whether the agent followed them.

Because the agent runs in your local repository, instruction files can be part of the same workspace the agent sees. The Junction app then lets you inspect the transcript, terminal output, file browser, approvals, Git diff, and session state.

That combination matters:

• instructions say what should happen,
• the transcript shows what the agent attempted,
• terminal output shows what commands ran,
• the file browser shows where the agent looked,
• the diff shows what changed,
• approvals let you stop risky actions before they happen.

If the agent ignores the instruction file, Junction will not pretend otherwise. The control surface helps you catch it.

Instructions vs Prompt Templates

Instruction files and prompt templates solve different problems.

Use repository instructions for stable project facts:

• package manager,
• test commands,
• project boundaries,
• review expectations,
• local development rules.

Use prompt templates for repeatable tasks:

• "write a focused regression test,"
• "review this diff for risk,"
• "summarize a failed run,"
• "turn this issue into an implementation plan."

If you put task-specific prompts into the repo instruction file, every session carries irrelevant context. If you put stable project facts into every prompt template, the templates become harder to maintain.

For templates, read Custom Prompt Templates for AI Coding Agents.

Review Instructions Like Code

Treat instruction files as part of the development workflow.

Review them when:

• test commands change,
• package boundaries move,
• CI changes,
• a provider changes how it loads instructions,
• agents repeatedly make the same mistake,
• a new high-risk directory appears.

Do not let the file become a junk drawer. A short accurate instruction file beats a long stale one.

Tradeoffs

Instruction files can create false confidence.

An agent may still misunderstand the task, ignore a rule, or apply it too broadly. Instructions also consume context. If they are too long, they can reduce the room available for the actual task and relevant code.

The right posture is trust but verify:

• write concise instructions,
• watch the first files and commands,
• review approvals,
• inspect the final diff,
• update the instruction file only when the lesson is durable.

The Local-First Advantage

Because Junction runs agents where your code already lives, repo instruction files stay close to the work. You do not have to copy project rules into a separate hosted environment just to supervise a session from your phone.

Start with the Junction setup guide to connect one daemon. Then inspect how your current CLAUDE.md and AGENTS.md files appear in real local runs before moving more work into automation.