Prompt, rules and handoff templates

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: Prompting · Markdown

Step 1: Create a library and separate purposes

Create a templates folder in your practice directory and add the files below using an editor. On Windows, check that Save As did not add .txt; on macOS use plain text; on Linux save UTF-8 in your preferred editor. Work from the practice root on all three systems and keep filenames consistent. The folder has no special loading behavior and requires no packages, additional website login or global configuration.

templates/
  task.md
  bug.md
  review.md
  handoff.md
  rules.example.md
  connection-check.md

Step 2: Turn a request into a testable task

# Task
Goal: Verify the active-task filter and repair it only if the acceptance case fails.
Context: Use the complete reference copy in this practice folder.
Inspect first: index.html, app.js, core.mjs, style.css and core.test.mjs.
Scope: Only files needed for the filter and its focused tests.
Behavior: All shows every task; Active shows tasks whose completed value is false.
Preserve: Existing task IDs, titles, ordering and stored data format.
Acceptance: With three tasks (two complete), Active shows exactly one.
Boundary: An empty list shows a useful empty state and does not throw.
Validation: Run node --test core.test.mjs and verify the browser behavior; report actual results.
If the existing behavior passes, report that evidence without unnecessary edits.
Delivery: Explain changed behavior, tests actually run and remaining limitations.

This filled example targets the Small Steps exercise, not every repository. Confirm the five code files in your expected copy. Instructions are in README.md at the download root, not inside expected; other projects use their own README to verify commands. To discuss feasibility, use Plan mode with a proposed sequence and unresolved decisions as the deliverable. For implementation, clearly state the editable scope.

Rewrite 'tidy up my website' using this structure. A usable request identifies the screen, preserved behavior, acceptance data and whether release is included. When filenames are unknown, ask to locate and report the list-rendering files rather than inventing a path. Write prose in your preferred language while preserving identifiers, paths and conditions from the example.

Step 3: Preserve evidence in bug reports

# Bug report
Environment: <OS, browser/runtime and version>
Practice folder or branch: <actual location>
Starting state: <fixture or steps to create it>
Reproduction:
1. <first action>
2. <next action>
Expected: <observable result>
Actual: <observed result>
Error: <exact message, with secrets removed>
Frequency: <always / intermittent / unknown>
Already tried: <one change and its result, or none>
Fix scope: <allowed behavior and files>
Verification: Reproduce first, fix, rerun the original case and a boundary case.

Angle-bracket text marks fields to fill, not terminal syntax. For the bug exercise, specify the broken copy, adding Read and Build, completing only Read, and Completed incorrectly showing Build. Actual contains your own observations; use NOT RUN if unperformed instead of treating the example as a test. Do not prefill an unconfirmed database diagnosis. If no error message appeared, write none observed and describe the behavior and steps.

After a fix, repeat the original steps and an empty-data or duplicate-title boundary case. Separate failed tests from tests not run: expected to pass is not a result. If execution is unavailable, report the limitation and a reproducible command rather than treating the Verification field as completed work. No pass counts are prefilled, preventing old evidence from being reused as new.

Step 4: Separate review and handoff

# Review request
Compare: <base branch or exact before-state> -> <current change>
Purpose: <user-visible behavior>
Read first: <requirements and relevant files>
Review for: correctness, regressions and missing meaningful tests.
For each finding: give the trigger, impact, file/location and suggested correction.
Evidence: <commands actually run, exit codes and relevant output>
Unknowns: <tests or environments not checked>
Report no findings if none are supported; do not invent issues to fill a quota.
Do not modify files in this review task unless I request a fix.

# Handoff
Goal:
Working directory and branch:
Current commit:
Existing uncommitted changes and owners:
Completed work with evidence:
Pending work:
Decisions and constraints:
Files to inspect next:
Last command and result:
Known limitations:
Next smallest action:
Before continuing: verify the current files and Git state against this record.

The review base must resolve in the current Git repository. If it does not, consult Git and diffs rather than assuming main exists. A handoff records the current location and state and must be refreshed each time. A commit reported in an earlier task does not establish a clean current directory; list uncommitted work and ownership to avoid overwriting active changes.

A handoff file can live in the project when the location is appropriate for sharing. Private client data, credentials and entire conversations are usually unnecessary; paths, a problem summary and verifiable results restore context. Saving handoff.md does not mean a new task has read it. Request that explicitly and check the proposed next action. See Context and handoff.

Step 5: Rule and external-tool templates

# Practice project rules
Read index.html, app.js, core.mjs and core.test.mjs before changing this practice app.
Preserve task IDs and the existing data format.
Keep changes within the requested behavior.
Run node --test core.test.mjs and report actual results.
Do not commit credentials or private practice data.
If required files are missing, report the missing paths before making assumptions.

rules.example.md deliberately remains a reviewable draft rather than AGENTS.md. After confirming it fits your project, follow AGENTS.md to merge it into the appropriate scope, reading existing rules and preserving others' constraints. For a one-off task, include it in the request. Consider SKILL.md for repeated work with stable scope instead of installing every temporary prompt as a skill.

# Connection check
Surface / host / version:
Plugin or MCP server name and source:
Configured:
Authenticated (if required):
Tool available in a new task:
Read-only target (fictional or public):
Expected marker or source:
Actual tool call and result:
Original data unchanged:
Disconnect or disable action, if performed:
Retest after change:
Never include tokens, passwords or one-time login URLs in this report.

Fill configured, authentication, capability and actual invocation separately. Use not required for inapplicable authentication and not checked for unverified fields. A configuration file does not prove a working connection, and prefilled true values make a report misleading. With Plugins or MCP, record only the tested surface and host; an identically named server elsewhere can have different settings.

Turn a contradictory template into one task

Consider this faulty request: “Review expected read-only, but also fix and commit it; run npm test and report three passes.” It mixes reading with editing, applies a command to a fixture without package.json, and preassigns an unobserved result. Choose a read-only check for this run and save the complete version below as adapted-task.md in the practice root, preserving the six original templates.

# Read-only practice check
Goal: Verify the existing Active-filter behavior in this expected copy.
Confirm the absolute working directory and the five expected source files first.
Read core.mjs and core.test.mjs; explain the filter condition and test coverage.
Run node --test core.test.mjs and report the actual exit code, passes and failures.
Do not edit, stage, commit, push or deploy anything in this task.
Browser behavior: NOT RUN unless actually checked; core tests do not prove it.
If required files are missing, report the paths and stop before guessing commands.
Delivery: observed evidence, unverified behavior and the next smallest step.

A clean expected copy has a reference result of three passes and zero failures; still record your current output and leave source files unchanged. A broken copy should instead be reported as two passes and one failure with a different starting state. Correct the path or create a separate repair task instead of ignoring the failure because the template said expected. This applies the official prompting guidance on goals, context, boundaries and usable outcomes to this fixture.

Mistakes, restoration and exercise

First, unresolved placeholders: search for < before submitting and replace each field or remove it if inapplicable. Second, stale commands copied into another project: read its README and verify the working directory. Third, conflicting instructions such as read-only review plus incidental edits: choose one goal. Preserve an existing same-name template as another copy or inspect its Git diff. Restore only the templates you changed, leaving other project work intact.

Exercise: fill bug.md with an observed practice failure and handoff.md with the next step. Give both to someone unfamiliar with the original task: they should locate the folder, reproduce the symptom and identify unchecked items. Add a missing host or data field where needed instead of lengthening every template. Keep an unfilled original template and save a separate task copy so yesterday's result does not become tomorrow's default answer.

These original teaching templates carry no execution privileges and do not change your account. Acceptance is six readable templates, a filled bug report and handoff, and at least one ambiguity you identified, without requiring a model to use a particular sentence. Continue with MCP setup and apply connection-check.md to an actual read-only tool test.

Back to the Codex learning hub

Read the full description

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI tools
• Tutorials
• Codex