This chapter ends with three files in the repository: ROADMAP.md,
AGENTS.md or CLAUDE.md, and DEV_PLAN.md.
Together they form the project harness: product context, agent operation
rules, and a phased execution plan.
Order matters. ROADMAP.md comes first because it becomes the source of truth for the other two. Then the agent operation file, which uses the ROADMAP to generate coherent rules. Finally, DEV_PLAN.md, which uses both to create testable phases.
Repository created, cloned, and open in your tool. If you have not done this yet, go back to the previous chapter.
1. Create ROADMAP.md
ROADMAP.md is the shortest harness document but the most important. It defines the product in 2–3 lines, chooses a concrete stack, and organizes development into clear steps. Everything that comes next relies on it.
In the placeholders below, replace [REPO_NAME] with your
repository name and [CHOSEN_TOOL] with the tool you are using
(Cursor, Claude Code, Windsurf, etc.).
I am going to build a live news newspaper published on GitHub Pages. I want to start with a simple, executable ROADMAP.md.
PROJECT CONTEXT
- Repository name: [REPO_NAME]
- What we are building: a news newspaper that fetches the top 10 Hacker News stories and displays them as a newspaper page: headline, articles section, and listing
- Public API: https://hacker-news.firebaseio.com/v0/
- Top stories: GET /topstories.json (returns array of IDs)
- Individual story: GET /item/{id}.json (returns { id, title, url, score, by, time, descendants })
- Deployment: GitHub Pages
- Tool in use: [CHOSEN_TOOL]
REAL CONSTRAINTS
- no custom backend
- no database
- no authentication
- the site is 100% static and runs in the browser
- few dependencies, prefer Vanilla JS + HTML/CSS, or a minimal framework (Vite + Vanilla, Parcel, etc.)
- do not use React, Vue, Angular, or any SPA framework, because simplicity is the goal
TASK
Create a ROADMAP.md file at the repository root.
ROADMAP.md must include:
- product summary in 2-3 lines
- chosen stack with a short justification (choose ONE concrete direction, do not list options)
- the three core features: fetch IDs, fetch details, render newspaper layout
- expected file structure at the end of the project
- development sequence in 3 to 5 steps, from simplest to most complete
- acceptance criteria for the complete project
- note about deploying to GitHub Pages
IMPORTANT RULES
- write in English
- be specific and avoid generic filler
- do not implement code
- do not invent features beyond the described scope
- generate only the final ROADMAP.md contentRead the generated ROADMAP.md before moving on. If the stack seems too complex or the scope is inflated, adjust with the agent before continuing.
ROADMAP.md exists in the repository, you have read it, and it makes sense to you.
2. Create the agent operation file
With ROADMAP.md ready, ask the agent to create the operation file. This file tells the agent what the project is, what the rules are, what must not be invented, and how to validate work.
The file name depends on the tool you are using:
- Claude Code →
CLAUDE.md - Any other tool →
AGENTS.md
The prompt already includes this rule. The agent will generate the file with
the correct name if you specify the tool in [CHOSEN_TOOL].
The ROADMAP.md already exists in the repository. Use it as the primary source of truth.
PROJECT CONTEXT
- Repository name: [REPO_NAME]
- What we are building: static news newspaper with the top 10 Hacker News stories, published on GitHub Pages
- Tool in use: [CHOSEN_TOOL]
TASK
Create the agent operation file at the project root.
FILE NAME RULES
- if I am using Claude Code, the file must be named CLAUDE.md
- for any other tool, the file must be named AGENTS.md
The file must include the following sections:
1. Project overview
- what this project is and what it delivers
- what the final goal is
2. Stack and constraints
- technologies chosen in ROADMAP.md
- what must not be used (no SPA frameworks, no backend, no database)
3. File structure
- list of expected files and folders at the end of the project
4. Main commands
- how to run locally
- how to create a production build
- if commands do not exist yet, state that explicitly
5. Code conventions
- naming patterns
- how to organize functions and modules
- how to handle fetch errors
6. Deploy process
- how GitHub Pages deployment works for this project
- deploy branch and output folder
7. What NOT to do
- clear list of what the agent must not invent, change, or assume without explicit alignment
IMPORTANT RULES
- write in English
- base everything on the existing ROADMAP.md
- do not invent stack, commands, or structure that contradicts ROADMAP.md
- generate only the final content of the correct file: AGENTS.md or CLAUDE.md⚠️ Read the file as soon as it is generated. If it contains a command that does not exist, invented scope, or a rule that contradicts ROADMAP.md, fix it with the agent before continuing.
AGENTS.md or CLAUDE.md exists, you have read it, and it is aligned with ROADMAP.md.
3. Create DEV_PLAN.md
DEV_PLAN.md turns ROADMAP.md into execution phases. Each phase has an objective, deliverables, and acceptance criteria you can validate in the browser. In the next chapter, you will execute these phases one by one.
The prompt uses ROADMAP.md as its source of truth and suggests a phase sequence. The agent will adapt if the chosen stack requires different steps.
The ROADMAP.md and the agent operation file (AGENTS.md or CLAUDE.md) already exist in the repository. Use them as the primary source of truth.
PROJECT CONTEXT
- Repository name: [REPO_NAME]
- What we are building: static news newspaper with the top 10 Hacker News stories, published on GitHub Pages
- Tool in use: [CHOSEN_TOOL]
TASK
Analyze the ROADMAP.md and create a DEV_PLAN.md file at the repository root.
DEV_PLAN.md must organize development into atomic, testable phases. Each phase must:
- have a short, descriptive name
- have a clear objective in one sentence
- list concrete deliverables (files created or changed)
- have acceptance criteria that can be manually validated in the browser
- be small enough to complete in one agent session
- indicate initial status as TODO
Structure the phases in natural build order. A suggested sequence:
- Phase 1: Initial project structure (HTML, basic CSS, main JS file)
- Phase 2: Top stories fetch (fetch IDs and details via HN API)
- Phase 3: Newspaper layout rendering (headline, articles, listing)
- Phase 4: Loading and error states (skeleton, fallback message)
- Phase 5: GitHub Pages deploy (config, build, gh-pages branch)
Adapt the phases to the existing ROADMAP.md. If the chosen stack requires different steps, reflect that in the plan.
IMPORTANT RULES
- write in English
- use ROADMAP.md as the source of truth for stack and structure
- each phase must be independent and have clear manual validation
- do not implement code
- generate only the final DEV_PLAN.md contentReview the DEV_PLAN.md phases carefully. Each phase should be small enough to complete in a single agent session. If a phase seems too large, ask the agent to split it before moving on.
DEV_PLAN.md created, reviewed, and with testable phases. You understand what each phase delivers.
With these three files, the agent has context (ROADMAP.md), rules (AGENTS.md or CLAUDE.md), and a plan (DEV_PLAN.md). In the next chapter, you will execute DEV_PLAN.md phase by phase.
Save your work in Git before moving on. This gives you progress checkpoints, history, and safe rollback points.
git add .
git commit -m "[summarize what changed in this chapter]"
git pushReplace the commit message with a short, real summary of what changed in this chapter.
Chapter 2
0 of 3 checkpointsComplete all checkpoints to unlock the next chapter.
Next up: Build in parts →