Working With AI Coding Agents While Learning

AI agents are expected to help build Forge, but the project is also your course. The workflow should speed up implementation without outsourcing understanding.

A good task prompt for an agent

Provide:

1. the current course lesson path;
2. AGENTS.md;
3. the exact relevant architecture document(s);
4. current failing test/output when applicable;
5. a narrow desired result.

Example shape:

We are on Lesson 05 (`docs/course/lessons/05-sqlite.md`).
Follow `AGENTS.md` and the architecture docs linked by that lesson.
Implement only the DB open + migration mechanism and its tests.
Do not add Task repositories yet.
Explain any non-obvious `database/sql`/SQLite connection behavior in simple language after the change.
Run the lesson's relevant tests and report the exact commands/results.

Require explanations where learning matters

Useful requests:

• “Explain why this interface belongs here rather than in domain.”
• “Show me which crash boundary this Operation protects.”
• “Explain what would break if this Review were not revision-bound.”
• “Tell me what part of this code is provider-specific.”

Do not require a huge tutorial after every trivial edit.

Human review is mandatory for agent changes

Before accepting a substantial agent patch:

• read the diff;
• understand new dependencies;
• make sure the patch did not broaden scope;
• run tests yourself when practical;
• reject clever abstractions you cannot justify.

Context discipline

Do not stuff the whole docs tree into every agent context. The layered docs are designed to prevent that. Start with the current lesson and linked current-truth docs. Add research/ADR detail only when reasoning about that decision.

If an agent finds the plan wrong

That is allowed. Ask for concrete evidence. If the change is real:

evidence
  ↓
update canonical docs
  ↓
ADR if important
  ↓
change course/plan sequencing if needed
  ↓
update STATUS

Do not force code to match a bad document simply because the document came first.