Learn
Working with agents ๐Ÿค– AI-on ๐Ÿ’ป On your computer โฑ ~6h Difficulty 1/5 v1

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.

Join free to start โ†’ Read the brief and materials. Join Build and Ship an AI App to start, submit and ask the tutor. Log in

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:

  1. Your variant: the roles, the URLs, the form fields and the rules.
  2. 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 is config.settings and manage.py is next to SUBMISSION.md. - Only Django 5.2 (it is in requirements.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 group coordinators. - 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+Tab until "plan mode", or claude --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 edit eval/ 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

  1. Set up: git init, a virtual environment, pip install -r requirements.txt. Commit.
  2. 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.
  3. 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.
  4. Commit a checkpoint after each step that works (git commit). If the agent breaks something, you can go back.
  5. 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.
  6. Run neugen test for 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.
  7. 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_required or 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 coordinators user 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 (or CLAUDE.md / GEMINI.md);
  • optionally, agent transcripts in .neugen/logs/;
  • SUBMISSION.md with 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 (paste git 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

  1. 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.settings loads, SQLite, complete migrations, no frontend build or framework, an instruction file. - Your own tests (gate: at least 5, all passing).
  2. 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.
  3. 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)

  1. Read the required material and DJANGO-WALKTHROUGH.md (35 minutes; more if you need the Django tutorial).
  2. Install your harness and try it on something small. Write AGENTS.md (25 minutes).
  3. Plan with the agent, then build in small steps with tests and commits (about 3 hours).
  4. Use the app as each user after every step (the Try it boxes). Run neugen test and fix what fails (1 hour).
  5. Write SUBMISSION.md and 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).