# Week 2: Specs and self-portrait
> The brief poses the problem, the spec is the contract, and your response is a self-portrait of the developer you want to be
# Welcome
---
# Week 2
## Specs and self-portrait
---
the brief poses the problem
the spec is the **contract**
---
## what changed this week?
DeepSeek Flash v4
[Ten advances in mathematics and theoretical computer science](https://openai.com/index/ten-advances-in-mathematics/)
Qwen 3.8
---
## today's beats
explore, plan, implement, verify
interrogating the brief and spec with the agent, before it builds
putting each instruction in the right artefact
why a page rendering is no evidence that it's right
demo: from brief and spec to the smallest interactive slice
---
## demo: yes, and
> Read this week's hall-of-fame pick and the Assignment 1 brief and spec. Plan
> the smallest interactive explainer its subject could become: one idea, one
> mechanic, nothing else. Write the plan to `PLAN.md` — my working file, not the
> spec. Do not build yet.
then we leave it running and talk about specs
---
# brief, spec, response, plan
---
## defining some terms
the **brief** poses the problem (no single right answer)
the **spec** is the fixed contract that every response has to satisfy
your **response** is the particular thing you decide to make
the **plan** is a set of concrete steps to 'build it out'
(the course's split; [spec-kit](https://github.com/github/spec-kit) has its own)
---
# **words**; what do they even mean?
---
## a spec line, and a plan line
from [assignment 1's spec](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/assessments/assignment-1/) (fixed, on the course
site):
```yaml
- the visitor does something that changes what they see — state the core
interaction plainly enough to write a test for it
```
from the `PLAN.md` this week's demo wrote (yours, in the repo, disposable):
```md
**The visitor changes who they know, and the dex responds.** All 151 render as a
grid. … One control adds people to their world — a friend with the other
version, then a second friend — and each addition recolours cells from
unobtainable to obtainable.
```
the plan is one answer to the spec; a different response would need a different
plan
---
## make claude argue with you
aka "adversarial review"
before it builds anything:
> Here are the brief and spec. List what's ambiguous, what you'd have to assume,
> and what we've missed. Don't propose a design yet.
back comes a list of decisions you didn't know you were making
---
## instructions are distributed
([Claude Code docs: how `CLAUDE.md` files load](https://code.claude.com/docs/en/memory#how-claude-md-files-load);
`/context` lists what loaded)
---
I made something, is it **good**?
---
## could a human tell?
"make it look good" fails; "exactly one top-level heading" passes:
```ts
expect(doc.querySelectorAll("h1").length).toBe(1);
```
every crit spec is deliberately a mix of human- and machine-checkable
`/comp4020:start` helps you turn the machine-checkable stuff into tests, so you
can focus on the other stuff
---
## Claude Code cheatsheet
`shift+tab` cycles the permission mode; the status bar names the one you're in
**manual**: it asks before every edit and every command
**accept edits**: edits land unasked, commands still stop
**plan**: it reads and proposes, and edits stay blocked until you accept
**auto**: the course recommendation — a classifier vets each action instead of
asking you
---
back to the **demo**
---
## demo: happy with this plan?
before I switch across: what do you reckon it did?
then we read it together — the response it wrote up, and the decisions in it
that we never made
---
## now **you** try
> One thing this plan is still missing is \_\_\_\_\_\_.
thirty seconds with a neighbour, then one call goes into the plan
---
## demo: build it
> Add that to the plan, then build the smallest slice the plan describes. Run
> the checks and report what they say. Don't let the scope grow.
then we leave it running and go looking at browsers
---
# which box does what?
---
## the browser builds another artefact
([MDN: how browsers work](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/How_browsers_work);
[the DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction))
---
## the source, in full
```html
How deep is the deep sea?
How deep is the deep sea?
```
---
## it renders, so it's fine?
HTML parsing is error-tolerant
[by spec](https://html.spec.whatwg.org/multipage/parsing.html#an-introduction-to-error-handling-and-strange-cases-in-the-parser):
the broken sea page renders with no error anywhere
so the starter's invariant checks parse `dist/` the same way and test the tree:
a declared language, a real title, a viewport meta, a nav landmark, one `
`,
alt text on every image
the missing `
` passes all of them (there's still exactly one `
`); only
a test that checks what's inside the heading catches it
---
so how do you **see**
what the browser built?
---
## DevTools
**Elements** (`cmd/ctrl+shift+C`): the DOM, not your source — the broken page
shows both paragraphs nested inside `
`
**Console**: parse errors in your JS, failed fetches, 404s for assets
**device toolbar** (`cmd/ctrl+shift+M`): both marking viewports, 1920×1080 and
390×844
the agent can't open DevTools itself — paste what you see, or give it a browser
to drive (week 3)
---
## Ben uses…
[Ghostty](https://ghostty.org)
the (pseudo)terminal the agent runs in, native and fast, configured from one
text file I can diff
---
# Predict, then watch
---
## your prediction
discuss with your neighbour: what's gonna happen?
(hold the verdict until we've all seen it)
---
## demo: read it against the spec
_interactive_ means the visitor **does** something that changes what they see
how much of the result came from the spec and plan, and what still needs a
person's judgement?
we read what it reported, not what the page looks like
---
## now **you** try
> At 390×844, the one thing I would refuse to ship is \_\_\_\_\_\_.
thirty seconds with a neighbour, then one call goes straight back to the agent
---
## that's what assignment 1 is about
an interactive explainer of something you think more people should know — one
strong idea, one dataset or mechanic, and nothing else
doesn't have to be "real"
due **noon, Monday 17 August**
---
## examples
[**Elevators**](https://john.fun/elevators): change the traffic and the
algorithm, then watch the wait-time distribution move
[**Mechanical Watch**](https://ciechanow.ski/mechanical-watch/): Ciechanowski
takes a movement apart, one draggable diagram at a time
[**Waveforms**](https://pudding.cool/2018/02/waveforms/): The Pudding, where the
explainer plays the thing it is explaining
[**The Deep Sea**](https://neal.fun/deep-sea/): neal.fun, where scrolling is the
only interaction
---
## C2: unsolicited redesign
find a real organisation you like with a website you don't, and build them a
better one
for the crit: explain why yours is better
stack note: Astro becomes the course default with C2; any static stack you can
defend is fine
---
## don't be a meat proxy
[Gruhn, 3 August](https://gruhn.me/blog/2026-08-03/)
---
## the existential bit
the maths result we opened on: ten open problems, moved along by a model
whither humans?
---
## the other half of the title
the agent writes the code; you decide what code there should be
_what did this work change about who I want to be as a software developer?_ —
you answer that in writing with every deliverable
what's yours: the response, the plan, the harness, the checks you wired in, the
things you said yes (or no) to
---
## deadline radar
**this week**: `/comp4020:start` for C2, then turn its spec into tests before
you build
**your week-3 cutoff**: C2 live at its URL, reflection in the repo
**noon, Monday 17 August**: assignment 1 — same canvas, static and client-side
---
## your Claude budget now resets **Thursday 9am**
the first one was **this morning at 9** (everyone reset fresh)
also; cache set to 60min (up from 5min)
same weekly amount ($100), same cap; details on Ed
---
## week 9: Monday groups
Monday 5 October is a public holiday, so neither Monday crit runs in its usual
slot
**Shítāo**: Tuesday 6 October, 14:00–15:30, usual room
**Bādà**: Wednesday 7 October, 15:30–17:00, **Room 3.05**
your C8 cutoff moves with your session
---
## tl;dr
the brief poses the problem, the spec is the fixed contract, the plan is yours
your instructions go in four places; don't mix them up
source, DOM and screen are three different artefacts
software as self-portrait
---
## ask your agent
ask until you can explain these back:
- **source, DOM and screen**: where can they differ, and which panel shows me
- **error tolerance**: what broken markup does a browser render anyway, and what
does a screen reader do with it
- **permission modes**: which one am I in, and what can you do without asking
- **the brief and spec**: what is fixed, and who is allowed to change it
---
# See you in the studio
Source: \
Licence: [CC-BY-NC-SA-4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)\
Cite as: Swift, B. (2026). _COMP4020/COMP8020 Agentic Coding Studio_ [Course materials]. ANU School of Computing. https://doi.org/10.5281/zenodo.21395760
```
---
## it renders, so it's fine?
HTML parsing is error-tolerant
[by spec](https://html.spec.whatwg.org/multipage/parsing.html#an-introduction-to-error-handling-and-strange-cases-in-the-parser):
the broken sea page renders with no error anywhere
so the starter's invariant checks parse `dist/` the same way and test the tree:
a declared language, a real title, a viewport meta, a nav landmark, one `