How to write Claude Code prompts depends on what this task still lacks after project configuration. Project rules already hold the repo map, commands, and long-lived boundaries. Skills already hold repeatable workflows. Hooks and CI run deterministic actions. Permission policy limits tools. The current prompt only needs the state to change, the evidence you already have, the affected range, the authorization boundary, and the result that must appear when the work is done.
The prompt does not need YAML, XML, or a fixed form. A local defect can be short. Context that crosses several owners is added only when that context changes the result. The test is not word count or field count. It is whether the agent can start from the current project, make the change inside authorization, and confirm the software reached the target state.
How to write Claude Code prompts for the current task only
A task prompt is live for this task. It can cite directory-scoped AGENTS.md and CLAUDE.md project rules, a requirement, an error log, or a skill. It should not copy those files. A copy becomes a second source of truth: after a command moves, the old prompt still names a missing entry; after a workflow upgrades, a saved template still runs the old steps.
OpenAI’s Codex prompting guidance(opens in a new tab) says a prompt does not need technical syntax or a rigid formula. Larger work only adds the goal, context, output, and boundaries that change the result. Anthropic’s Claude Code prompt library(opens in a new tab) asks for the outcome, lets Claude find the files, and puts a way to check the work in the same request. The user supplies task facts the repository cannot derive. The agent investigates the implementation path.
| Information | Where it lives | How it appears in this prompt |
|---|---|---|
| Repo map, generated-file boundary, long-lived commands | Project rules | “Read and follow the project rules that apply to the current directory.” |
| The symptom to fix and the target state | Current prompt | State current behavior, the target, and what must stay unchanged |
| A specialist flow reused across tasks | Skill | Name the existing skill or the trigger; do not paste the full steps |
| Formatting, checks, or injection that must run on an event | Hook, formatter, tests, CI | The prompt does not enforce the action; it states the result this run needs |
| Tools the client may, must ask about, or must refuse | Permission policy | The prompt states user intent; the policy limits actual ability |
| Current logs, screenshots, requirements, test data | Current prompt or attachment | Say what the artifact can prove and what it cannot |
| Tokens, cookies, private keys | Secret storage and environment injection | Do not put them in the prompt, rules, log samples, or version control |
“You are a senior full-stack engineer,” “think deeply,” and “keep the code high quality” do not replace a task fact. They name no broken state, no preserved behavior, and no observable result. If the project needs a stable language, architecture, or coding standard, that belongs in long-lived rules. If this run only needs a different audience or format for the delivery note, write the audience and the use in the current prompt.
What a prompt should change in the agent loop
A coding agent that can read, edit, and run commands keeps acting on tool results. It does not emit one block of code and stop. Claude Code’s how it works(opens in a new tab) page describes the loop as gather context, take action, and verify results. The three phases blend as new observations arrive. Each useful line in the prompt should change one decision in that loop.
The target state tells the agent when it may stop. The current symptom and reproduction conditions tell it what to run or read first. Authoritative materials tell it which layer to trust when a requirement, the code, and a running page disagree. Range tells it which producers and direct consumers to follow. Authorization tells it which local actions may continue and which external side effects must stop. An observable result forbids “the code is written” as a substitute for software state.
| Prompt information | Agent action it should change | Common result when it is missing |
|---|---|---|
| Current state and trigger | Reproduce or read current behavior first | Rewrite the implementation without seeing the present |
| Target state and control behavior | Compare before and after | Fix one branch and break an existing path |
| Authoritative materials and known facts | Build a hypothesis from the right source | Treat a screenshot, old doc, or guess as the cause |
| Owner range and non-goals | Find the module that owns the state and its direct consumers | Edit a surface file or refactor a neighbor |
| Authorization and stop conditions | Continue inside the grant, or stop at an exact boundary | Ask about investigable questions, or perform an unauthorized external write |
| Observable completion | Run a check that would fail a wrong implementation | Declare the task done because tests are green |
OpenAI’s Codex best practices(opens in a new tab) use the same idea as a default, not a form to fill every time: goal, context, constraints, and done when. A copy change does not need the database, a worker, and deploy. Those layers enter the prompt only when they take part in the state change.
Describe the software state change first
“Ship account-status display” is a feature name. It has no start and no end. The agent cannot tell what the page currently lacks, who produces the status, which users can see it, or whether new code finished the job.
Turn the task into an observable before-and-after. The product already confirmed three user-visible states. The code path is still for the agent to find:
The service already stores account status. Admin shows the raw value. The user detail page shows one generic message for every non-normal status. The target is for both interfaces to show the three product states: normal, pending review, and restricted. Users without view permission still must not see the field. Existing operations on normal accounts stay unchanged.
Database fields and component names still come from current code. The confirmed present is that the status exists and two consumers disagree. The approved requirement sets the target enum. Permission denial and the normal path are the control results. The agent can look for the producer, the public contract, and the two interfaces, instead of editing the first copy it sees.
Write the result as software state, not as a work action. “Add tests and get the build green” describes a verification method. “An authorized admin page and user detail page show the same account status, and unauthorized requests are still denied” is the result. Tests, builds, and browser checks then prove that result.
Performance, capacity, or coverage targets need measurement conditions. “Load faster” cannot be rechecked. If the approved target is “under the same data and device, a named metric on the target page stays below a threshold,” the prompt should give the metric, the threshold, the baseline source, and the measurement environment. Without an approved threshold, asking the agent to pick a number disguises a product choice as a technical fact.
Anthropic’s prompt library(opens in a new tab) makes the same cut: describe the outcome, not the steps, and state a measurable target when the goal is performance or coverage.
Define scope by responsibility, not guessed files
Range is not a guessed file list. People usually know which software behavior must change and do not know whether an API, a cache, an adapter, or a component owns it. “You may only edit this component” can force a compatibility patch in the wrong layer. “Do whatever you think is best” lets the task spread into unrelated refactors.
The prompt should state the owner boundary and the adjacent behavior that must hold: find the module that produces the wrong state; change only the root-cause boundary and the direct consumers needed to finish the task; do not retune unrelated routes, the visual system, or deploy config. Cite a path when an error stack, a registration map, or a requirement already confirmed it. When the path is unknown, let the agent search from project rules, the entrypoint, and the call chain.
A full-stack task also does not need a mechanical list of backend, database, admin, user UI, worker, and deploy. Follow the direction the state actually travels:
Business state in the requirement
→ module that produces or stores it
→ public contract or event
→ applications that consume it directly
→ user, API, data, or process result
If investigation shows the database shape and the public contract did not change, they do not enter the diff for completeness. If account-status meaning travels through a public contract, “verify direct consumers” cannot shrink to a server unit test. Range grows from a proven impact boundary. It does not grow from template fields.
Non-goals should name adjacent owners that are easy to edit by mistake and that would cost real work. “Keep existing operations on normal accounts unchanged” is more useful than “do not change any other code.” The first supplies a control result. The second can collide with a necessary consumer fix.
Claude Code’s best practices(opens in a new tab) still allow naming a file when you already know it. That is a known path, not a guess written to look precise.
Separate facts from unknowns
A requirement, source code, a log, and a running page answer different questions. Calling all of them “context” lets the agent overwrite current code with an old screenshot, or reject an approved new requirement with the current implementation.
| Source | What it can settle | What it cannot settle alone |
|---|---|---|
| Approved requirement or design | Target behavior, copy, roles, business bounds | Where the current code lives, whether existing data already matches |
| Current source, schema, registration | Implementation owner, dependency direction, generation chain | Whether the running process loaded the current artifact |
| Error logs and network records | Symptom, time, and input range of one run | The only root cause, or that every environment reproduces it |
| Current page or API response | Observable result in this environment | Which build or uncommitted tree produced it |
| Old docs and historical commits | Past design and change clues | The product flow that is still in force |
The prompt can state those boundaries: the requirement sets the target state; current code sets file location and implementation owner; a screenshot only proves a symptom in one viewport; whether the running environment matches current source still needs a check. Source strength keeps approved targets, current implementation, and a one-off run from collapsing into one conclusion. File location is still for the agent to find in the repository.
Known facts should be checkable: the error text, the trigger, approved copy, and the behavior that must stay. Put speculation in a hypothesis to verify: “This may be client cache. Reproduce first and confirm along the request chain. Do not edit on that guess.” When files, commands, and module relationships can be read from the repo, the user does not have to paste them.
Unknowns that need a human decision should be written before any edit. Two mutually exclusive business rules, an irreversible migration, a vendor choice, and a promise to external users cannot be derived from code. Implementation path, test entry, and which module owns an error can usually be confirmed by reading and by commands without side effects. They should not bounce back to the user because of “ask me about anything uncertain.”
Write authorization as actions
“Be careful about security” does not name the action that would cross a line. An authorization boundary should match an external side effect that can actually happen. An implementation task can allow reading and editing the current workspace, starting a local server, and running non-destructive checks, while production writes, outbound messages, deletes, payments, deploys, commits, and pushes wait for a separate grant. If the task never involves a class of action, the prompt does not have to list every dangerous command.
The verb itself also sets the end state. “Explain this code” and “see why it failed” usually stop at a read-only conclusion. “Find the root cause” does not include a fix. “Fix and verify” allows code changes in the target workspace and does not include commit, push, or deploy. Mixing those ends into “handle this” leaves the agent to guess whether the user wants a report, a change, or a release.
| Request intent | End state the agent may reach | Authorization it does not get automatically |
|---|---|---|
| Explain or review | Read the present, give a sourced account | Edit files, send messages |
| Diagnose a root cause | Reproduce, locate the owner and the cause | Apply a fix |
| Fix or implement | Edit the current workspace and run verification that matches the range | Commit, push, external writes |
| Commit | Write verified, in-scope changes to a local commit | Push to a remote |
| Push or deploy | Update the named remote or environment | Other accounts, environments, or release channels |
If “why didn’t this page change” is a diagnosis, the prompt should end at the cause, the evidence, and the unconfirmed boundary. Finding a possible code difference does not authorize an edit. “Fix the page and verify locally” is what brings local writes into the task. Remote actions still need their own sentence.
Text in the prompt cannot enlarge the client’s actual permissions. Claude Code’s agentic harness(opens in a new tab) and Codex sandbox and approval policy(opens in a new tab) still limit tools. Words only state user intent. When a command is allowed in the prompt and refused by policy, the agent should report the block. It should not try to bypass the policy.
Stop conditions should be boundaries that safe investigation cannot resolve: a missing product decision, a required runtime that is unavailable, an unauthorized external write, or a root cause that would change a public contract the prompt already excluded. A missing source path is not a stop; searching the repo is the next step. A failing target test is not a stop; the failure output is evidence for the next loop.
“Ask me about anything uncertain” turns ordinary engineering judgment into an interrupt. “Stop only when the product requirement has two reasonable readings, when continuing needs a larger grant, or when the excluded range must change” lets the agent investigate, and it leaves business and authorization decisions with the user.
A local defect only needs a short prompt
A local prompt should match the impact. A project has a reproducible mobile layout issue. The framework and source file are not confirmed yet:
At 390px width, the account-page detail button text overflows the button. Desktop layout is fine. Read the project rules that apply to the current directory, reproduce the issue, and find the source that owns this layout. Fix the mobile overflow. Keep desktop size, button copy, and click behavior unchanged. Change only the root cause and any direct tests it needs. You may edit the current workspace and run local checks. Do not commit or push. When done, verify once at 390px and once on desktop, and state the actual change, command results, and any external boundary that was not verified.
“Make the font smaller” and “edit this CSS file” stay out, because both are implementations that have not been investigated. Reproduction, the desktop control, the authorization boundary, and two viewport results already constrain the local task. The first round should read rules, reproduce the page or run related tests, and locate the source. It should not invent a global responsive abstraction.
If the target component is already confirmed, attach the path or a screenshot. If the repository requires a UI-verification skill, write “check both viewports with the project’s existing UI verification flow.” Do not paste the skill’s full steps. The more local the task, the more format requirements and role slogans should be deleted.
How a cross-layer task prompt stays complete
A cross-layer task needs more information because the state travels through several owners, not because a template must be filled. When account status passes through a service, admin, and the user detail page, a natural-language prompt can read:
Change account status from “the service already has a status, admin shows the raw value, the user detail page always shows unavailable” to both interfaces showing the three approved states: normal, pending review, and restricted. Users without view permission still must not get the field. Existing operations on normal accounts stay unchanged.
Target behavior follows the requirement attached to this task. Current source, schema, generation config, and registration decide the actual owner modules and file locations. The screenshot only proves a display difference. It is not the root cause. Read the repo-root rules and the nearest rules for the directories involved, then confirm the smallest complete range along the producer, the public contract, and the two direct consumers. Do not invent paths or fields from this description.
You may read and edit the current workspace, update generated files the project requires to stay in sync, run existing checks, and start a local preview. Do not change unrelated pages, the permission model, or deploy config. Do not touch production data, commit, or push. If the three states still have mutually exclusive meanings, if an irreversible migration is required, or if the root cause would change a non-goal above, state the exact conflict and stop before writing.
When done, run the repository’s existing checks, then observe the current result from each direct consumer of the status. The delivery should say what the status changed from and to, which owner modules actually changed, which commands ran, what admin and the user page each showed, and which external environments were not verified.
If the state never passes through an API, a schema, or a page, that layer does not enter the change. The agent should prove where the state actually travels, then keep edits and verification on that chain. For payment status, an admin setting, or an async job, replace the business state, the authoritative materials, the consumers, and the external authorization. Do not copy the account-status nouns.
A Claude Code prompt and a Codex prompt can usually share the same goal, facts, range, and result. Each client still loads its own project rules, permissions, and skills, and commands or tools may differ. Add a client-specific note only when that difference changes execution. Copying two near-identical requirements makes targets and non-goals drift.
Check the prompt from first actions and software results
Prompt quality cannot be judged from formatting before send. Watch the first round: whether the agent reads applicable rules and the present, whether it separates requirement facts from a guessed cause, whether it looks for the module that produces the state, and whether it stops only for a product decision or an authorization gap. Editing a surface component on a guess in the first round usually means the target source or the investigation boundary is still unclear.
Before the agent stops, check whether the software reached the state the prompt named. A local layout defect should disappear at the target viewport with the desktop control intact. A cross-layer state should travel from the producer through the current contract to the direct consumers. Unauthorized commits, pushes, or external writes should not happen. A successful command can support those judgments. It cannot replace them.
| Observation | What a working prompt should produce | What to change first when it drifts |
|---|---|---|
| Gathering context | Reads applicable rules, authoritative materials, and current behavior | Add a source, or remove a guessed path |
| Choosing range | Finds the root-cause owner and the necessary direct consumers | Rewrite the state boundary and non-goals; do not preset file paths |
| Asking for confirmation | Stops only for a product choice, an irreversible action, or a larger grant | Separate investigable unknowns from decisions the user must make |
| Making the change | The diff covers only the owners needed for the state change | Correct range instead of repeating “don’t wander” |
| Verifying the result | Target consumers show the target state; control behavior holds | Add a check that would fail a wrong implementation |
| Delivery note | Distinguishes passed, unverified, and blocked boundaries | Name result evidence; do not prescribe a decorative report format |
The first prompt does not have to predict every fact the investigation will find. OpenAI’s prompting guidance is to state the need in your own words, then shape the result with follow-up messages. Claude Code also allows interrupting or adding information during a run. When a new message joins the same task, say how it relates to the old requirement. Otherwise “the account list should show it too” can replace the original page, and “don’t change permissions yet” can be read as a temporary suggestion.
| What the new message does | Natural wording | How the agent should treat the old state |
|---|---|---|
| Add a fact | “Addendum: this page comes from the last build. Confirm source and running artifact first.” | Keep the original target; change investigation order with the new evidence |
| Add a requirement | “On top of the original requirement, the account list must show the same account status.” | Keep the original range; bring the new consumer into the change and the verification |
| Replace a requirement | “Correction: do not change admin this time. Only fix the user detail page. The earlier admin requirement is void.” | Drop the conflicting target; recheck work already done |
| Change authorization | “Diagnose only now. Do not edit files. Read-only checks already running may finish.” | Stop the next unauthorized action immediately |
After the team confirms a follow-up as a business rule every later task must follow, write it back to project rules once it does not conflict and the write is authorized. A correction in the session only governs this run. Long-lived rules still need their own file. Restoring an old session does not keep them in force.
When the same class of task keeps appending the same background, do not blame model memory first. Long-lived facts go back to project rules. A repeated flow with the same decision branches belongs in a skill. A mechanical check that must run every time belongs in a hook or CI. The current prompt keeps only this change, so an update to rules, a skill, or a hook does not require a matching giant prompt.
When a prompt fails, move the content
When a prompt gets long, decide whether the repeated content belongs in project rules, a skill, or a hook. Do not compress the original into denser abbreviations first. Pasting the same repo map and test commands every time means project rules are missing or not loaded. Describing the same research, generate, and review flow every time means it should be a skill. Asking the agent to “remember to format” every time means a mechanical action never entered a hook or the existing toolchain.
| Recurring symptom | Likely cause | Where it should move |
|---|---|---|
| Every task pastes the same architecture and commands | Long-lived project facts have no single source | Repo-root or nearest-directory rules |
| The same class of task always copies multi-step judgment | A reusable flow is trapped in chat history | A skill, plus its scripts, references, or templates |
| The agent often skips a mechanical action that must run | A soft reminder is carrying a deterministic duty | Hook, formatter, tests, or CI |
| The prompt needs absolute paths before a module is found | The project map or launch directory is unreliable | Project rules and the current working directory |
| A new requirement fights leftover limits from an old task | Stale task state remains in the session | State the replacement; start a new task when the goal has changed |
| The agent’s done claim does not match the page | Completion was written as a work action | Observable result in the current prompt |
Are longer Claude Code prompts better? No. Keep only the information that changes this task. Long-lived facts belong in project rules. Repeatable workflows belong in a skill. Mechanical actions belong in a hook or CI. Tool ability is limited by permission policy.
Do I have to list file paths in a Claude Code or Codex prompt? No. Cite a path when it is already known and authoritative. When the path is unknown, state the owner boundary, the symptom, and the result, and let the agent find the files from project rules, registration, and the call chain.
Do Claude Code and Codex need two task prompts? Usually not. Goal, facts, range, and result can be shared. Client-specific commands, permissions, and extensions still follow each client’s config and the current environment.
How should a coding-agent completion criterion be written? Write a state a user, API, dataset, or process can observe, plus the control behavior that must stay unchanged. Test commands are evidence. They are not the software result.
When how to write Claude Code prompts for this repository is stable, a new change only states this run’s variables. If the same flow already repeats across tasks, and the trigger, input boundary, decision steps, and result check are stable, move that flow into a skill. The next prompt then supplies only this run’s input.