Pair with an agent: build a small Django app
Your first project with a coding agent. Install a harness, write a project instruction file, and build a small Django app with logins from a fixed spec: plan first, work in small checked steps, read every diff and commit checkpoints, and explain how you checked the agent's work.
Preview shown for one variant (Shared reading list). You get your own when you start.
Why this quest
In this course you build most of your code with a coding agent: a program that reads your files, runs commands and edits code for you. Agents are fast. They are also confidently wrong sometimes, and they do not know your project's rules unless you tell them.
This is your first project with an agent, so it sets your habits. You will practise the habits that make agents useful:
- plan first, before any code is written;
- work in small steps, and check each one (run the tests, read the diff);
- commit a checkpoint after each step that works;
- write a project instruction file that tells the agent the rules;
- notice when the agent goes in circles or is wrong, and take over.
You build a small Django app from a fixed spec. The spec is small on purpose, so you can focus on how you work with the agent.
New to Django? Start with DJANGO-WALKTHROUGH.md in your starter kit (about 20 minutes). It
follows one request from URL to view to template to test, and ends with a readiness check. If the
check is hard, work through the Django tutorial in the materials first (allow a few extra hours).
Your app: Shared reading list
A book club keeps one list of books to read next. Members suggest books (title and author) and vote. Coordinators (the Django group coordinators) can delete any book. The tricky parts: no duplicate books (ignoring case and outer spaces, in every alphabet), one vote per member, no votes for your own suggestion, the order of the list, and who voted is private.
The full spec is in your starter kit: specs/reading-list.md. Read all of it before you start.
It has two parts:
- Your variant: the roles, the URLs, the form fields and the rules.
- The contract (the same for every variant): the grader tests your app through HTTP, so a
few things are fixed. The most important ones:
- Create the project with
django-admin startproject config .in your quest folder, so the settings module isconfig.settingsandmanage.pyis next toSUBMISSION.md. - Only Django 5.2 (it is inrequirements.txt). No other packages. SQLite. Django templates with plain CSS. No React, no npm, no build step. - Django's login at/accounts/login/. The second role is the Django groupcoordinators. - Every page needs a login. Actions (buttons that change data) use POST, never GET. A user who may not do an action gets 403. - Your own tests (at least 5, all passing) and a project instruction file (AGENTS.md).
Everything else is your choice: app names, models, views, templates, how it looks.
Step 1: choose and set up a harness
A harness is the program that runs the agent: it sends your request to a model, lets the model read files and run commands, and shows you what it does. Use any of these:
| Harness | Cost | Notes |
|---|---|---|
| Claude Code | needs a Claude plan or API key | Terminal, VS Code, desktop app. Reads CLAUDE.md |
| Codex CLI | needs a ChatGPT plan or API key | Terminal. Reads AGENTS.md |
| Gemini CLI | free tier with a personal Google account (about 1,000 requests a day) | Terminal. Reads GEMINI.md |
| GitHub Copilot, agent mode | small free allowance; free for verified students (Copilot Student) | Inside VS Code. Reads AGENTS.md and .github/copilot-instructions.md |
| Cursor | free Hobby plan with limited agent requests | An editor. Reads AGENTS.md |
| Aider or opencode with a local model | free (runs on your computer with Ollama) | Slower and weaker than the big models, but private and free. For Aider, start Ollama with OLLAMA_CONTEXT_LENGTH=8192 or more, or it forgets your files |
Free limits change often. Check the vendor's page when you start. If you have no access to any of these, tell your mentor.
Permission modes. Every harness lets you choose what the agent may do without asking you. For this quest:
- Start in a plan or read-only mode (Claude Code:
Shift+Tabuntil "plan mode", orclaude --permission-mode plan; Codex:/permissions; Aider:/ask). - Then use a mode where the agent asks before it runs commands or edits outside the project.
- Do not use "skip all permissions" or "full access" modes in this quest.
- Work in your quest folder only. Never give the agent your passwords or API keys in the chat.
Step 2: write your instruction file
Before the first line of code, create AGENTS.md in your quest folder (Claude Code users:
create CLAUDE.md with the single line @AGENTS.md, or write CLAUDE.md directly; Gemini CLI
users: GEMINI.md). The agent reads it at the start of every session. Keep it short, about 20
to 40 lines:
- The stack: Django 5.2, SQLite, templates with plain CSS, the settings module
config. - Commands: how to set up, run the server, run the tests, make migrations.
- What not to do: no new packages, no npm or React, no
csrf_exempt, do not editeval/or.neugen/. - How to work: plan first, one step at a time, run the tests after every change.
- Project rules the agent keeps getting wrong. Add a line each time you correct it twice.
Many harnesses have an /init command that writes a first version. You can use it, but then
edit it: remove what is obvious, and add what the agent cannot guess. A long file is not a
better file. Keep it in your project folder: the grader reads it from your submission.
Step 3: build it with the agent, in small checked steps
- Set up:
git init, a virtual environment,pip install -r requirements.txt. Commit. - Ask for a plan first. Give the agent the spec (
specs/reading-list.md) and ask for a plan in small steps, with a test for each step. Read the plan. Change it if you disagree. No code yet. - One step at a time. For each step: the agent writes the code and a test, runs
python manage.py test, and you read the diff (git diff) before you accept it. If you do not understand a line, ask the agent to explain it. - Commit a checkpoint after each step that works (
git commit). If the agent breaks something, you can go back. - Use it yourself after each step that works (see Try it as a user below). Tests tell you the code does what the spec says; using the app shows you what you actually built.
- Run
neugen testfor the public tests. They check only a few basics. The hidden tests check every rule in the spec, so make your own tests for every rule. - Take over when needed. If the agent fixes the same thing twice and it is still wrong, stop. Look at the code yourself, start a new session with a clearer request, or go back to your last checkpoint.
Keep short notes while you work: what you asked, what went wrong, how you noticed, what you did. You need them for the write-up.
Try it as a user
Not graded, but do it: it's how you find out what the agent's code really does. Run
python manage.py runserver and open http://127.0.0.1:8000/. Create users once, as soon as
logins work: python manage.py createsuperuser for yourself, then in /admin/ two ordinary users
and a third user in the group coordinators. A private browser window makes it easy to be two
users at once.
Try it: after logins. Log out and open any page of your app. You land on the login page. Log in as each user in turn.
Notice: find what sends a visitor to the login page (
login_requiredor a mixin on each view) and the setting that says where the login page is.Try it: after the main workflow. As your first member, open
/books/and suggest a book. Log in as the second member: the book is on their list too, and they can vote for it.Notice: the book you typed went into the database, and the list page reads it back for every user. Find the view that saved it and the template that shows it.
Try it: after the coordinators rule. Log in as your
coordinatorsuser and delete a book. Then log in as a member: there is no delete button for them.Notice: hiding a button only changes the page. Find the check in the view that decides who may do it: that's what keeps other users out.
Step 4: describe your checks
The grader reads your write-up, code and tests. In SUBMISSION.md, describe your plan, your
steps and how you checked them: name the code or rule, the check you used (a test, the diff,
trying the app as two users) and what you concluded. Successful checks count as much as
corrections: you do not need a list of agent mistakes.
Transcripts are optional. If you want the grader and mentors to see a session, copy its
transcript in with neugen log <file> (this also removes API keys it recognises). Leaving them
out never lowers your score.
| Harness | How to get the transcript |
|---|---|
| Claude Code | In the session: /export claude-session.txt writes the conversation to a text file |
| Codex CLI | Session files (.jsonl) are in ~/.codex/sessions/, in folders by date |
| Gemini CLI | In the session: /chat share gemini-session.md |
| Copilot in VS Code | Command Palette: Chat: Export Chat..., or right-click the chat and Copy All |
| Cursor | In the chat panel's ... menu, choose Export Chat |
| Aider | Your whole chat is already in .aider.chat.history.md in your project folder |
| opencode | opencode export writes a session as JSON |
Read a transcript before you add it, and delete any password, API key or personal data.
Optional: a landing page for your product idea
Not graded. If you'd like your first deployment now, make one static web page about the product from your product brief (A1): who it is for, the problem and what it will do. Plain HTML and CSS; no sign-up form or other data collection. GitHub Pages, Cloudflare Pages and Netlify all host it for free. Keep its files in their own repository, not in this quest folder.
What to submit
With neugen submit, from your quest folder:
- your Django project (
manage.py,config/, your apps, templates, migrations, tests); AGENTS.md(orCLAUDE.md/GEMINI.md);- optionally, agent transcripts in
.neugen/logs/; SUBMISSION.mdwith these sections: 1. My setup: the harness and model, the permission mode you used, and why. 2. My instruction file: which file it is, and which lines mattered most, and why. 3. How I worked with the agent: your plan, your steps and checkpoints (pastegit log --oneline), and how you checked each step. 4. Decisions and verification: up to three important decisions, corrections or checks. For each: the code or rule, how you checked it (a test, the diff, trying it by hand) and what you concluded. If the agent made no mistake you caught, say so; a careful successful check counts too.
Do not submit db.sqlite3, .venv/ or .env files (the starter's .gitignore leaves them out).
How you're graded
- Hidden tests run your app in a sandbox with a fresh SQLite database:
- Spec behaviour (gate 90%): every rule in your spec, including edge cases.
- Logins, permissions and privacy (gate 100%): who may see and do what.
- Stack checks (gate 100%):
config.settingsloads, SQLite, complete migrations, no frontend build or framework, an instruction file. - Your own tests (gate: at least 5, all passing). - Rubric review by an AI grader: your way of working with the agent, your instruction file, and your decisions and verification, judged from your write-up, code and tests.
- Defense: a short conversation about your code. For example: "Explain what this view does", "What happens if a user sends this input?", "Why is this permission check here?" You did not type most of the code, but you must understand all of it.
This is an AI-on quest: the agent writes code, and that is the point. The tutor explains ideas and gives hints about working with agents and Django, but it will not write the app.
Suggested path (about 6 hours)
- Read the required material and
DJANGO-WALKTHROUGH.md(35 minutes; more if you need the Django tutorial). - Install your harness and try it on something small. Write
AGENTS.md(25 minutes). - Plan with the agent, then build in small steps with tests and commits (about 3 hours).
- Use the app as each user after every step (the Try it boxes). Run
neugen testand fix what fails (1 hour). - Write
SUBMISSION.mdand submit (40 minutes).
Tips
- Paste the whole spec to the agent. Ask it to list the rules as a checklist before it plans.
- Ask for one test per rule. Then read the tests: a test that checks nothing is common.
- Agents often miss: permission checks on POST (not only hidden buttons), GET requests that change data, case-insensitive checks for non-English letters, the order of the list, and private fields that still appear on the list page.
- If the agent wants to install a package or add JavaScript tooling, say no, and add a line to your instruction file.
- If the agent uses a Django feature you do not know, ask it for the link to the Django docs, and open it.
Interface
# The HTTP contract. The full spec for your variant is in specs/<variant>.md.
django-admin startproject config . # manage.py next to SUBMISSION.md
/accounts/login/ GET, POST username, password (Django's LoginView)
/accounts/logout/ POST
/<prefix>/ GET the list; each entry links to /<prefix>/<id>/
/<prefix>/new/ GET, POST valid -> 302 to /<prefix>/<id>/; invalid -> 200, nothing saved
/<prefix>/<id>/ GET one record; unknown id -> 404
/<prefix>/<id>/<action>/ POST only; not allowed -> 403; done -> 302
Not logged in -> 302 to /accounts/login/?next=... Role = membership of a Django group
Only Django 5.2 is installed. SQLite. No frontend build. AGENTS.md (or CLAUDE.md / GEMINI.md).
Read now
Read 'Give Claude a way to verify its work', 'Explore first, then plan, then code' and 'Course-correct early and often'. Stop before the advanced workflows. The ideas work in every harness.
Use while building
Open these when a step needs them. No need to read them first.
At the login step, look up 'Limiting access to logged-in users' (login_required) and 'Authentication Views'. At the roles step, look up groups. Don't read the whole page first.
When you write your instruction file. Codex, Cursor, Copilot, Aider and opencode read AGENTS.md. Claude Code reads CLAUDE.md, which can import AGENTS.md with one line (@AGENTS.md); Gemini CLI reads GEMINI.md.
Explore further
A Django refresher. Work through it if DJANGO-WALKTHROUGH.md in your starter kit leaves gaps: projects, apps, models, views, templates, forms, POST and CSRF. Allow extra time.
git status, git diff, git add, git commit and .gitignore. Enough to commit a checkpoint after every step and to read what the agent changed.
Three stages. You only move on when the one before passes.
Automated gates
| Metric | Gate | What it checks |
|---|---|---|
| Spec behaviour | โฅ 0.9 | Share of the spec's behaviour tests that pass: forms, validation, edge cases, the order of the list, the workflow. The hidden set tests every rule in your spec. |
| Logins, permissions and privacy | โฅ 1.0 | Share of the permission tests that pass: login required, who may do each action (403 for others), GET never changes data, private fields stay private, CSRF protection. All must pass. |
| Stack checks | โฅ 1.0 | Share of the stack checks that pass: a Django project with config.settings that loads, SQLite, complete migrations, no frontend build or framework, and a project instruction file (AGENTS.md, CLAUDE.md or GEMINI.md). All must pass. |
| Your own tests | โฅ 5 | How many tests `python manage.py test` runs in your project, counted only if all of them pass. You need at least 5. |
Gates run on the public set (which you have) and a hidden set with inputs you haven't seen.
Rubric review need โฅ 60%
The write-up shows a plan before code, small steps, a check after each step (tests run, diffs read, the app tried as two users) and commits as checkpoints (the pasted git log). The checks it names are real: the tests and code it points to exist and do what it says. When the agent went wrong, the student noticed and redirected or took over; a session without mistakes is fine when the checks are concrete. Transcripts are optional: judge from the write-up, code and tests when there are none.
The AGENTS.md / CLAUDE.md / GEMINI.md in the submission is short and specific to this project: the fixed stack, the exact commands to run and test, what not to use or touch, and rules that came from real corrections or foreseeable risks. Generic advice ("write clean code") and long copies of the spec do not count.
Up to three concrete decisions, corrections or successful checks: the code and the spec rule involved, the evidence (test, diff, manual check) and the conclusion. Corrections and successful checks count equally; there is no quota of agent mistakes. Honest and specific beats impressive; invented or vague examples score low.
Defense need โฅ 50%
A 4-question conversation with the AI examiner about your code. It isn't a trick: if you did it and understood it, it's the easy part. A weak defense on strong work gets you a new variant to redo.

