Run an Agent-Guided Project Sprint

Core path: 35 minutes

A coding agent can inspect files, edit code, run commands, and sometimes iterate without waiting for you after every line.

That makes the permission boundary more important, not less.

This lesson controls one feature change through specification, plan review, bounded execution, diff inspection, testing, and recovery. A live repository-writing agent is optional. The control process is required.

Safety boundary

Use only the project and tools authorized by your class.

Never provide:

• credentials or tokens;
• student records;
• private material outside the approved project;
• permissions broader than the task requires.

An agent having the capability to access something does not automatically give it authority to do so.

Write the Feature Brief

Choose a tested project and define:

Goal:
Input:
Expected output:
Edge cases:
Files allowed to change:
Files not allowed to change:
Definition of done:

The file boundary should be specific enough that you can compare it with the eventual diff.

Establish the baseline

Before delegated work:

python -m pytest
git status

Create a known-good checkpoint according to your classroom Git workflow.

Now you have evidence of the state that existed before the agent acted.

Path A — approved live agent

If your class provides an approved repository-writing agent, ask it to inspect first and not edit yet.

Request a plan.

Review every step using labels such as:

APPROVE
QUESTION
REJECT

Only after the plan is acceptable should you grant bounded permission to make the approved change.

Path B — supplied simulated agent

If no approved live agent exists, use this plan:

FEATURE: include players with score >= minimum in a leaderboard
ALLOWED: reports.py, tests/test_reports.py

PLAN
1. Add build_leaderboard() to reports.py.
2. Add boundary tests to tests/test_reports.py.
3. Rewrite storage.py to normalize all score records.

Step 3 violates the allowed-file boundary.

Reject it before inspecting implementation.

Now review the supplied candidate patch:

diff --git a/reports.py b/reports.py
@@
+def build_leaderboard(players, minimum):
+    return [player for player in players if player["score"] > minimum]

diff --git a/storage.py b/storage.py
@@
-def load_players(path):
+def load_players(path="players.json"):

There are at least two problems:

1. > violates the requirement >= at the exact threshold;
2. storage.py changed even though it was not authorized.

A patch can contain correct-looking code and still be unacceptable.

Human verification

For either path:

1. inspect the actual diff;
2. compare changed files with the permission boundary;
3. run the full relevant test suite;
4. manually check the feature;
5. add one adversarial boundary test the agent did not provide.

Do not let the agent's summary replace any of these checks.

Recovery drill

If an unauthorized change exists, restore or revert that part before continuing.

Document:

what changed outside scope:
how you detected it:
recovery command/action:
state after recovery:

Recovery is not something to hide. It is evidence that the boundary worked.

Agent Development Log

Record:

Feature Brief
Plan
APPROVE / QUESTION / REJECT decisions
Allowed files
Actual changed files
Rejected or repaired change
Test results
Manual verification
Final diff summary
Recovery action

Success evidence

The final change must:

• stay inside authorized scope;
• pass the boundary requirement;
• pass relevant tests;
• survive manual verification;
• include at least one independent human review decision; and
• be explainable without asking the agent what it did.

Delegation is useful only while you can still see and control the boundary.