Use code instead of repeated AI prompts when the same explicit inputs should produce defined outputs through known operations. Keep AI at the interpretation boundary: it can help explain an unfamiliar case or draft code, but deterministic execution should be inspectable, tested, and repeatable.
Define the contract
Before scripting, write:
Inputs:
Outputs:
Files or systems changed:
Valid and invalid conditions:
Expected failures:
Verification:
Rollback:
For example, renaming assignment files by a documented convention can be deterministic. Deciding whether a student’s reflection demonstrates understanding requires judgment and should not be hidden in a rename script.
Make repeated execution safe
An idempotent operation reaches the same intended state when run again. A script that creates a missing folder can first check whether it exists. A script that blindly appends the same line on every run is not idempotent.
Not every useful script can be fully idempotent. When repetition has side effects, detect prior work, require explicit confirmation, or record a unique operation identifier.
Provide a dry run
A dry run should display proposed actions without making them:
WOULD RENAME: draft 1.md -> 2026-07-24-draft-1.md
SKIP: 2026-07-23-notes.md already follows convention
ERROR: final?.md contains an unsupported character
The preview must use the same selection and validation logic as the real operation. A misleading dry run is worse than none.
Fail clearly
Reject invalid input before partial changes. Report:
- which input failed;
- which condition was violated;
- what changed before failure, if anything;
- how to recover; and
- a nonzero exit status for automation when appropriate.
Do not silently “repair” ambiguous data. Stop and request human judgment.
Test the script
Create a temporary practice directory and cover:
- expected input;
- empty input;
- already-correct state;
- invalid name or value;
- repeated execution;
- dry run versus real run; and
- partial-failure recovery.
Inspect files and diffs after every test. Never test destructive automation on valuable coursework. Use synthetic names and data.
Let AI assist without becoming the runtime
AI can help identify requirements, propose edge cases, explain code, and review a diff. You remain responsible for every line, dependency, permission, and test. Once the deterministic workflow is verified, run the script rather than asking a model to recreate the operation differently each time.
Keep genuinely ambiguous decisions outside the script or expose them as explicit inputs decided by a person.
Common mistakes
- Automating before performing the process manually.
- Treating likely output as a defined contract.
- Claiming idempotence after one run.
- Providing a dry-run flag that still changes state.
- Catching errors and returning success.
- Letting AI-generated code touch real files before review.
Do this now
Choose a harmless repeated task. Write the contract, implement or pseudocode a dry run, and test expected, invalid, and repeated execution in a temporary folder. Record observed results, not predicted results.
Log what you learned
Record only:
- Result: What did the action produce?
- Evidence: What observation, test, or source supports that result?
- Next action or unresolved question: What should happen next?
Next, record
durable repository guidance in AGENTS.md.