Skip to content
All posts

The Re-Explain Tax in AI Coding

OTFOTF Kit
6 min read
A clay-style character in an orange hoodie stands beside a dark-framed panel showing three folders and text lines, with puzzle pieces on the tan background.

You have explained your stack and conventions to a coding agent before. The next session asks you to explain them again.

That repetition is the re-explain tax: project facts that could live with the code are copied into a temporary chat, then disappear from the next task. A repository cannot remove every clarification, but it can keep stable guidance available and leave the prompt to describe the work at hand.

Repeated setup notes beside durable project guidance in a repository

Separate project context from task context

Project context stays true across many changes. It includes the package manager, major directories, established naming rules, validation commands, and constraints that are easy to miss. Put those facts in a maintained project instruction file or link to the document that owns them.

Task context changes each time. It includes the outcome, the files or behavior involved, the boundaries for this edit, and how you will verify the result. Keep that in the request.

Mixing the two creates avoidable work. A chat prompt that repeats the whole repository guide gets harder to maintain. A project guide that tries to predict every future task becomes a stale instruction dump. Keep one source for durable rules and a small request for the current change.

Use the instruction format your agent reads

Do not assume that every coding agent loads the same file. OpenCode’s current documentation describes AGENTS.md as project guidance and explains how it discovers that file in the workspace. It also documents how configured instruction files can be included. Other tools have their own conventions. Check the documentation for the agent your team uses, then commit the right file so teammates can use the same project context.

A useful project note is specific, stable, and easy to verify. For example:

# Project guidance

## Structure
- Feature routes live in the routes directory.
- Shared UI belongs in the shared components package.
- Follow the nearest maintained example before adding a new pattern.

## Validation
- Run the package type-check after changing TypeScript.
- Run the tests for the affected package.

## Boundaries
- Preserve public API behavior unless the task says otherwise.
- Do not edit generated files or include credentials in commits.

Treat this as a shape to adapt, not a drop-in map for every repository. Replace its generic directory labels and commands with facts you have checked in your own codebase. Remove rules that no longer match the project.

12 production screens. Login and database wired.

The SaaS Dashboard Kit includes login, a database, and a working dashboard. Live demo at saas.otf-kit.dev.

See the live demo

Keep the task prompt short and concrete

Once reusable context is in the repository, describe the change without retelling the whole project:

Add the account-usage panel to the existing settings area.
Inspect the current settings implementation and use it as the reference.
Keep the route and public props stable; do not add a dependency.
Run the relevant package type-check and tests.
Report the changed files and any check that could not run.

The request identifies the desired outcome, boundaries, and evidence. The repository supplies the shared rules. If the agent cannot find a relevant example or a required command, ask it to inspect and report what is missing instead of asking it to guess.

A focused coding request paired with project rules and a nearby example

Store less, but keep it useful

A project instruction file should not become a transcript of past conversations. Keep details that help across sessions: how to run checks, where a source of truth lives, and which compatibility constraints matter. Put one-off product requirements in the task. Link to longer documents instead of copying them into several instruction files.

Never put secrets, customer data, temporary incident details, or assumptions about an unreviewed change into shared agent guidance. If the team learns a durable convention, update the maintained source and review it like code. This keeps the next session from inheriting stale or sensitive context.

Review the work instead of promising a first-try result

Persistent context can make a request more precise, but it does not guarantee a correct edit. Ask the agent to inspect before editing, keep the change within a bounded area, and run the checks that fit the code. Then review the diff and verify behavior that automated checks cannot establish.

A type-check can catch certain classes of type errors; it does not confirm that a screen looks right or that a permission boundary is safe. A test can cover the expected case without covering every failure path. Treat the agent’s report as a handoff with evidence, not as approval.

A developer reviewing an agent's changes against the repository and its checks

Check the starter before you buy it

If you want project context ready in a starter, inspect the actual kit files and validation scripts. As checked on 15 October 2026, the OTF templates catalog lists SaaS Dashboard, Fitness, and Arcade as available. OTF’s OpenCode guide describes the selected kit’s agent files and its task prompt library; the guide records that the kit’s own type-check passed in a fresh install on 13 October, with no type errors introduced by the test change. That is a dated result for the documented check, not a promise about your edits or every runtime behavior.

The kits include AGENTS.md, CLAUDE.md, .cursorrules, and between 22 and 27 task prompts, as checked on 15 October 2026. These provide a starting point for tool-specific context; inspect the files and confirm they fit your workflow. You can start with the SaaS Dashboard kit and its current repository.

For a related guide to keeping a codebase navigable, read how to make a repository easier for an agent to navigate.

Sources

Keep reusable project rules beside the repository, put the current change in the prompt, and review every diff. When you are ready to work from a codebase with AI context files, start here.

#ai-toolsarchitecturebackend
OTF SaaS Dashboard Kit

Ship the product, not the setup.

  • 12 production screens — auth, team, analytics, and settings
  • Login and a real database are wired in
  • AI configs pre-tuned so your agent extends instead of regenerates
Free starter

Ship your first screen tonight — free starter in your inbox

The quickstart, the SDK repo and the live kit demos, on this screen and in your inbox.

No spam. Unsubscribe any time.

Free with your email

Get the free AI configs pack

The AI files every kit ships with. Drop them in and your AI tool knows your project.

  • CLAUDE.mdProject context
  • .cursorrulesRules for Cursor
  • prompts/Task prompts

No spam. Unsubscribe any time.