How to Turn Handoff Notes into Agent Instructions

Handoff Notes Reveal The Real Workflow

The best agent instructions often start as human handoff notes. A teammate writes, """Remember to run the site typecheck before opening a PR,""" or """Do not touch billing logic for this copy change,""" or """Use the existing route helper instead of adding another client."""

If that note appears once, it can stay in the issue. If it appears every week, it should become durable instruction for Claude Code and Codex.

Junction supports workflows with repo instructions, prompt templates, custom commands, and local agent sessions. The useful habit is deciding which human notes deserve promotion.

Identify Repeated Guidance

Look for notes that repeat across runs:

• Test commands.
• Package boundaries.
• Naming conventions.
• Review expectations.
• Files not to edit.
• Setup quirks.
• Design or copy rules.
• PR description format.

Repeated guidance is a sign that the repo has an implicit rule. Agents do better when implicit rules become explicit.

Keep Issue-Specific Context In The Issue

Not every handoff note belongs in a template. Issue-specific context should stay near the issue:

• Customer report details.
• Screenshots.
• One-off reproduction steps.
• Temporary constraints.
• Product decisions for that task only.

Durable instructions should describe how work is generally done. Temporary notes should describe this particular task.

Convert Notes Into Three Layers

Use three instruction layers:

For example, a repo instruction might say:

Use pnpm commands from the repository root. Run pnpm --filter @junctionpanel/site run typecheck for site changes.

A prompt template might say:

For a copy-only site change, inspect the relevant component, avoid product logic, update only user-facing text, and run the site typecheck.

The session prompt then includes the actual copy request.

In Junction, this separation maps cleanly onto how people actually work. A repository instruction carries stable context. A prompt template carries the repeated run shape. The active Junction session carries the issue, transcript, approvals, and diff that belong to the current task.

A Before And After

Before:

Fix the setup page copy. Also remember that the setup page uses public provider wording and should not mention unapproved providers. Run the site checks if you touch code. Do not change pricing.

After:

Repo instruction:

Public site copy must use approved provider positioning. Pricing changes must come from packages/site/src/data/pricing.ts.

Template:

Copy update: inspect the target page, update only user-facing copy, avoid unrelated formatting, and run the relevant site validation command.

Session prompt:

Update the setup page paragraph to make daemon onboarding clearer.

The session prompt becomes shorter because the durable context is already available.

The next time a teammate starts the same kind of run from a phone, they do not need to retype the whole policy. They choose the reusable shape, add the issue-specific request, and review the agent output in Junction.

Review Instructions Like Code

Bad instructions create bad runs. Review durable guidance before adding it:

• Is it specific?
• Is it still true?
• Does it conflict with another instruction?
• Does it tell the agent what not to do?
• Does it include commands that actually work?
• Is it short enough to be followed?

Do not add a vague rule like """write clean code.""" It consumes attention without guiding behavior.

Use Handoffs To Improve Automation

Switchboard benefits from better instructions because automated runs have less back-and-forth. If every Switchboard issue needs the same handoff note, that note probably belongs in route instructions, repo instructions, or a template.

For example:

For issues labeled docs-only, do not edit source files outside packages/site/content.

That rule is useful because it turns a recurring human reminder into a route-level constraint.

Manual runs benefit too. When you start Claude Code or Codex from Junction, a reusable template can carry the boring parts of the handoff: where to look, what to avoid, which command to run, and what the final summary should include. The human prompt can stay focused on the actual work.

This is especially useful for mobile workflows. Typing a long, careful prompt on a phone is slow and error-prone. A short session prompt plus a durable template is easier to send and easier to review.

For Switchboard, the same move reduces ambiguity before the run even starts. A Linear issue should contain the task. Route instructions should contain the recurring operating rule. The Junction activity feed then shows whether the agent followed that rule or needs human correction.

Tradeoffs

Durable instructions can get stale. A command changes, a package moves, or a team standard evolves. Treat instruction files and templates as living project assets.

The other risk is overloading agents with every preference your team has ever discussed. Keep only rules that affect correctness, safety, reviewability, or repeated workflow quality.

Review the instruction layer whenever a run fails for a preventable reason. If the agent ignored a rule that was never written down, that is a process bug, not just an agent mistake.

Where Junction Fits

Junction is the control surface where you can reuse templates, start local Claude Code and Codex sessions, inspect output, and turn handoff lessons into better future runs. It keeps the execution local while making the operating pattern visible.

For related guidance, read Use CLAUDE.md and AGENTS.md to Steer Local Agent Runs and Custom Prompt Templates for AI Coding Agents. The next useful step is to promote one repeated handoff note into a template and use it on the next run.