Open the project and check the baseline
Run the project's existing checks and inspect Git status. Write down any failure or change that already exists.
Terminal coding agent guide
Set up the agent, then run a loop you can recover
A terminal coding agent can read files, propose edits, run commands, and respond to errors. Daily work still belongs to the operator. Scope the task, place instructions at the right level, review the diff, run the checks yourself, save state, and keep a tested way back.
Setup
Begin from a known, boring state
Install one supported terminal agent from its current official documentation. Start it inside the project repository, leave the conservative permission profile in place, and confirm that Git can show you the files already changed before the agent touches anything.
The course setup lab comes first for a reason. You should be able to move around the terminal, run a script, read the bottom line of a traceback, inspect a diff, and restore one bad edit before an agent begins changing the project for you.
Start one agent inside the repository
Use the official setup path for your chosen tool. Keep the default approval behavior while the habits are new.
Add the project instruction file
Record the project, commands, conventions, intentional oddities, and actions that always require approval.
Create a known-good checkpoint
Begin work only when you can name the commit or clean state that recovery should return to.
Project instructions
Teach the repository once
A project instruction file should hold constraints the code cannot explain on its own. Keep task requests, project rules, personal preferences, reusable procedures, and enforced policies in separate layers so each instruction has the correct scope.
A compact project file
# Project instructions
## What this is
Weekly report formatter. It reads a local CSV and writes a Markdown summary.
## Conventions
- Keep the first release local and command-line only.
- Run tests with the command documented in README.md.
- Map every accepted test to requirements.md.
## Intentional choices
- The fixture with a missing column stays. It proves the ugly case.
## Never
- Never read a real customer export in tests.
- Never print values from .env.
- Ask before adding a dependency.The “never” lines help the model behave. Permission profiles, environment boundaries, and tests decide what the process can do when guidance is ignored or misunderstood.
The daily loop
One change, one review, one known-good state
| Stage | What you give the agent | Evidence you keep | Stop condition |
|---|---|---|---|
| Scope | One outcome, one important constraint, and a named non-goal. | The accepted task or plan. | The proposed diff is too large to explain or review. |
| Propose | Read scope, write scope, allowed commands, and approval points. | The files and commands proposed before execution. | The request reaches secrets, deletion, money, or an external write without approval. |
| Review | A request for a plain explanation of every changed file. | The diff and your one-sentence explanation. | The explanation and the diff disagree. |
| Test | A known case, an ugly case, and the project's normal checks. | Commands, output, and any mapped acceptance criterion. | A test was weakened, deleted, or made to agree with the implementation. |
| Commit | A concise description of the accepted change. | The commit and clean status. | The project cannot return to a working state. |
Permissions
Match authority to the work
Supervised profile
Your daily driver
Name the allowed roots, action classes, network destinations, secret exclusions, and actions that always come back to you. Read each approval before it runs.
Unattended profile
A narrower boundary
Give background and scheduled work less filesystem access, no secrets by default, named network destinations, a stop method, and notification on every final state.
A worktree isolates repository state
Separate worktrees protect files and branches from parallel edits. Credentials, network access, processes, shared databases, and paths outside the repository still need their own permission and environment boundaries.
Handoffs
Make a fresh session cheap
Keep four artifacts with separate jobs. The plan records the stages and their closing tests. Progress records what happened and where the evidence lives. Decisions keep resolved choices from reopening. The handoff gives a reader with zero session memory the exact next move.
A handoff another session can use
# Handoff
Current state
- CSV parsing is complete at commit 8c2f1a4.
- The normal and empty-file tests pass.
Evidence
- Test output: artifacts/test-run.txt
- Accepted plan: plan.md
Next action
- Add the missing-column error message from requirement 3.
Do not redo
- The parser choice was decided in decisions.md.
- Do not replace the fixture or weaken the empty-file test.Recovery
Stop the run before fixing the run
Interrupt the loop
End repeated variations and stop any background or scheduled work that can keep changing state.
Collect evidence
Save the exact error, triggering input, expected behavior, current diff, and last known-good commit.
Check the diagnosis
Make the agent state its belief in one sentence. Verify that belief before another edit starts.
Choose the safe path
Change one variable, shrink the stage, or return to the known-good state and plan the work again.
Prove the recovery
Run the smallest failing check, then the normal project checks, and record the clean result before resuming.
Questions and answers
Questions this page should settle
How large should one coding-agent task be?
Keep it small enough that you can describe the diff in one sentence and run a direct check when it finishes. If the change is too large to review, split the request before more work piles on top.
Does a project instruction file enforce safety rules?
No. It guides the agent. Permission settings, environment boundaries, tests, and hooks enforce rules. Anything involving secrets, money, deletion, or an irreversible external action still needs a real approval gate.
What belongs in a handoff?
Record the current state, evidence paths, decisions already made, the exact next action, and a do-not-redo list. A fresh session should be able to resume without reconstructing the transcript.
What should I do when the agent keeps trying failed fixes?
Stop the loop. Capture the exact error, the input that triggers it, and the result you expected. Ask the agent to state its diagnosis in one sentence, check that belief, then change one variable or return to the last known-good commit.
Keep building
Turn the loop into a full build practice
The course starts with terminal and Git basics, then uses the same loop for a small application, hosted model connection, provider adapter, data systems, agents, evals, safety, reliability, and a capstone.