Course Overview

What you will build

A small Node.js + TypeScript command-line tool called noted-cli that imports markdown notes from a folder, indexes them, and answers free-form questions over them with citations. The application code is intentionally simple. The course is not about building a clever search engine — it is about wrapping ordinary code in a harness so that an AI coding agent can extend it reliably across many sessions.

By Module 11 your repository will have:

• a runnable CLI (bin/noted → src/cli.ts)
• a routing instruction file (AGENTS.md) and topic docs (docs/)
• a feature list (feature_list.json) acting as the system of record
• a bootstrap (init.sh) and a three-layer verification pipeline (verify.sh)
• continuity artifacts (PROGRESS.md, DECISIONS.md, session-handoff.md)
• runtime observability (logs/, sprint-contract.md, evaluator-rubric.md)
• a finished ablation study comparing agent behavior with and without the harness

Prerequisites

Skill or tool	Why you need it
Comfortable shell use	Every lab is cd, mkdir, cat, pnpm, and friends.
Node.js 20 or newer	Native test runner (node --test), built-in fetch, no transpilers.
pnpm (or npm)	Course examples assume pnpm. npm works with one substitution noted in AUTHORING.md.
Git	Module 06 onward expects to commit checkpoints.
TypeScript familiarity	You should know what interface and type mean. No advanced types used.
Some prior agent use	You have used Claude Code, Cursor, Codex, or similar at least a few times.

You do not need:

• An Anthropic, OpenAI, or any other LLM API key. noted ask uses naive keyword retrieval. Module 10 includes an optional sidebar showing how to swap in a real model, but the rest of the course works fully offline.
• Prior experience with MkDocs, agent frameworks, or DevOps tooling.

Time budget

Tier	Modules	Reading	Lab work	Total
Basic	00 – 02	30 min	2.5 hrs	~3 hrs
Intermediate	03 – 07	1.5 hrs	5.5 hrs	~7 hrs
Advanced	08 – 10	1.5 hrs	4.5 hrs	~6 hrs
Capstone	11	30 min	2 – 3 hrs	~3 hrs

Total: roughly 18 – 20 hours spread over one to two weeks of evenings. Each module is designed to fit in a single uninterrupted session of 60 – 90 minutes.

Outcomes

After finishing this course you will be able to:

1. Diagnose which of the five defense layers is the weakest in any given codebase.
2. Author a routing AGENTS.md plus topic docs that pass the cold-start test.
3. Define features as machine-executable (behavior, verification, state) triples in a feature_list.json.
4. Build a three-layer termination check (lint → unit → end-to-end) and refuse to declare done until all three pass.
5. Run a session end-to-end under the WIP=1 rule, tracking your verified completion rate (VCR).
6. Hand off a session at clean state across the five dimensions defined in Lecture 12.
7. Measure the impact of a harness on an agent's reliability via an ablation study and a quality-document scorecard.

How to use this course

Each module folder contains exactly one index.md. The structure is uniform:

1. Front-matter blockquote — pairs with lecture, time, difficulty, prerequisites.
2. Why this module — the failure mode it fixes.
3. Concepts — distilled summary, with a link to the matching lecture for depth.
4. Lab — step by step — numbered steps with shell commands, file contents, expected output.
5. Verification — exact command and success signature.
6. Common pitfalls — three to five real mistakes other learners hit.
7. Next module — pointer to the next folder.

Always read the front-matter blockquote first. If the prerequisites list a previous module's checkpoint and you skipped it, go back. The labs compose — Module 09 will not work if your Module 06 init.sh doesn't.

When you get stuck

In rough order of usefulness:

1. Re-read the matching lecture. The lecture link in each module's "Concepts" section is not decorative — it is where the long-form theory lives.
2. Run the verification command early and often. It is cheaper to fix one broken step than to debug ten.
3. Cold-start your own repo. Open the relevant module from scratch in a new terminal and read your own files. If you cannot follow your own work, the harness is the bug.
4. Check the existing project briefs in ../projects/. They were written before this course and cover similar ground from a different angle.
5. Consult the field notes in ../.claude/field-notes/ — short, opinionated takeaways from each skill.

A note on AI assistance

You are encouraged to use Claude Code, Cursor, Codex, or any other agent as you work through the labs. The course is not adversarial to agents — it is about engineering an environment where they thrive. By Module 06 you will deliberately give the agent your AGENTS.md and watch it follow the rules. By Module 11 you will run a structured ablation showing the agent measurably outperforms its prompt-only twin on the same codebase.

The course writes the labs in step-by-step prose so you can follow along whether you are typing every keystroke yourself or pair-programming with an agent. Either is valid.

Open Module 00 when you're ready.