Set the ground

Create the repository on GitHub

The goal of this chapter is not to write code yet. It is to go from zero to a project that is ready to be planned and executed with an agent.

That is why this chapter starts manually on purpose. Before bringing AI into the loop, you create the repository on GitHub yourself. That helps you understand where the project begins, what the official URL is, and how your local folder connects to the remote.

Open GitHub in the browser and follow this flow:

1. Click New repository.
2. Pick a short, clear name such as deezer-explorer.
3. Add a simple one-line description.
4. Choose Public if you want to publish later on GitHub Pages.
5. Leave Add a README file, Add .gitignore, and Choose a license unchecked. We will create those files later, once the project is open and we have better context.
6. Click Create repository.

Clone it in the terminal

With the repository created, the next step is bringing that project to your machine. On GitHub, click Code, copy the HTTPS URL, and run these commands in your terminal.

cd ~/projects
git clone https://github.com/your-user/deezer-explorer.git
cd deezer-explorer
git remote -v
git status

If the repository is empty, that is fine: git clone will still create the folder, and git status may show something like No commits yet. What matters here is confirming that your local folder points to the right GitHub repository.

Open it in your chosen tool

With the local folder ready, open that directory in the tool you want to use: Cursor, Windsurf, VS Code, Claude Code, or something similar. The key point here is to open the project root, not a few loose files.

Create the files that guide the project

Now the normal workflow begins. Before asking for UI, search, or API integration, it is worth writing down the project context and the working rules. That keeps the agent from inventing scope too early.

For this early setup, ask for one file at a time. First PLAN.md, because it becomes the base for the next two. Then README.md. Finally, ask for AGENTS.md or CLAUDE.md, now grounded in the previous two files.

In the blocks below, replace the bracketed placeholders and click Copy prompt. The goal is to paste them directly into your tool and get a more reliable result than a vague generic request.

One important detail: only PLAN.md starts as an initial draft that we refine in the next chapter. README.md and AGENTS.md or CLAUDE.md should already come out as genuinely useful project documents.

These prompts already carry this product context:

• the product is called Deezer Explorer
• it is a responsive static website
• the user searches artists, sees albums, and opens album details
• the data source is the public Deezer API
• the core endpoints are artist search, albums by artist, and album by ID
• those public catalog endpoints work without end-user login
• the final deploy target is GitHub Pages
• the project needs to account for the browser CORS problem
• harness and operational files should be written in English

1. Base prompt for PLAN.md

This is the first prompt. It defines the product scope, the constraints, and the planning expectation without asking for implementation yet.

You are helping me start a real project from scratch. At this moment I only want an initial PLAN.md that is honest and useful. I do not want implementation code yet.

PRODUCT CONTEXT
- Repository name: [REPOSITORY_NAME]
- Working product name: Deezer Explorer
- What we are building: a responsive static website where a person types an artist name, chooses a result, sees the discography in cover-based cards, and opens an album to view tracklist, release date, and cover art
- Data source: public Deezer API
- Required v1 endpoints:
  - GET /search/artist?q=...
  - GET /artist/{id}/albums
  - GET /album/{id}
- Main user flow:
  1. open the site
  2. search for an artist
  3. see artist results
  4. choose an artist
  5. see album cards with covers
  6. open an album
  7. view tracklist, cover art, and date
- Final deployment: GitHub Pages
- Real project constraints:
  - no custom backend
  - no authentication
  - no database
  - mobile-first and responsive
  - accessible enough for keyboard navigation
  - few dependencies
  - we need to account for the Deezer browser CORS problem
  - the repository is at the very beginning and may be almost empty
- Tool in use: [CHOSEN_TOOL]

TASK
Create a PLAN.md file at the repository root.

PLAN.md must include:
- a concise product summary
- the exact v1 scope
- a concrete initial stack, choosing one technical direction instead of listing many options
- a short justification for that stack
- an implementation plan broken into small, testable phases
- for each phase: goal, deliverables, acceptance criteria, manual validation, risks, and open decisions
- a note about publishing on GitHub Pages
- a short “out of scope for now” section

IMPORTANT RULES
- write the file in English
- be specific and avoid generic filler
- do not invent features beyond the scope described above
- do not implement code
- this is an initial plan: it can be refined later, but it already needs to be coherent and executable
- generate only the final PLAN.md content

2. Base prompt for README.md

Once PLAN.md exists and makes sense to you, ask for README.md. Here the plan becomes the source of truth so the README does not drift into invented details.

Use the existing PLAN.md as the main source of truth.

PRODUCT CONTEXT
- Repository name: [REPOSITORY_NAME]
- Product: Deezer Explorer
- The final product is a responsive static website for searching artists, listing albums, and opening album details with the public Deezer API
- Final deployment: GitHub Pages
- Current repository state: very early project setup, with an initial PLAN.md already created and reviewed
- Tool in use: [CHOSEN_TOOL]

TASK
Create a real README.md for this repository in its current state.

README.md needs to be useful for someone opening the repo right now and should explain:
- what this project is
- what version 1 will deliver
- what the main user flow is
- which Deezer API endpoints are central to the project
- which stack was chosen in PLAN.md
- what the repository status is right now
- how the project is expected to be developed locally
- how GitHub Pages deployment is expected to work
- which risks and limitations are already known
- what the immediate next steps are

IMPORTANT RULES
- write the file in English
- make it a real README, not a placeholder
- use PLAN.md for stack, scope, and phase information
- if implementation has not started yet, say that clearly in the status section instead of pretending the product already exists
- do not invent features outside the scope
- do not fill the file with generic template language
- generate only the final README.md content

3. Base prompt for AGENTS.md or CLAUDE.md

Finally, ask for the agent operating file. Because it comes after the plan and README, it is much easier to produce rules that match the real project.

Use the existing PLAN.md and README.md as the main source of truth.

PRODUCT CONTEXT
- Repository name: [REPOSITORY_NAME]
- Product: Deezer Explorer
- The final product is a responsive static website for searching artists, listing albums, and opening album details with the public Deezer API
- Final deployment: GitHub Pages
- Tool in use: [CHOSEN_TOOL]

TASK
Create the agent operating file at the repository root.

FILE NAMING RULES
- if I am using Claude Code, the file must be named CLAUDE.md
- in any other tool, the file must be named AGENTS.md

The file needs to be genuinely useful for day-to-day work in this repository and must include:
- a concrete project overview
- goals and current v1 scope
- which files are the source of truth
- how the agent should use PLAN.md and README.md before proposing changes
- main project commands if they already exist; if they do not exist yet, say that explicitly
- quality and validation standards
- rules for updating PLAN.md and README.md when decisions change
- rules for proposing changes in small phases
- what must not be invented, changed, or assumed without alignment

IMPORTANT RULES
- write the file in English
- make it a real operating document, not a generic template
- use PLAN.md and README.md as the basis
- do not invent stack, commands, or workflow that contradict the existing files
- generate only the final content of the correct file: AGENTS.md or CLAUDE.md

⚠️ Read each file as soon as it is generated. If there is a command that does not exist, invented scope, vague promises, or a technical decision you do not understand, ask for an adjustment before moving to the next one. That care saves a lot of correction later.

Bonus: install and authenticate GitHub CLI

This step is optional, but very worth it. GitHub CLI (gh) lets you access GitHub directly from the terminal: authenticate your account, open repositories, inspect issues, work with pull requests, and give the agent more autonomy while it operates on the project.

The most common installation paths are:

• macOS: brew install gh
• Windows: winget install --id GitHub.cli
• Linux: use your distribution's official packages from the GitHub CLI documentation

gh auth login
gh auth status

In the interactive flow, the most common sequence is:

1. Choose GitHub.com.
2. Choose HTTPS as the Git protocol.
3. Select browser-based authentication.
4. Finish the login in the browser when GitHub opens.

gh auth setup-git

This command configures Git to use GitHub CLI credentials. If everything worked, gh auth status should show your account as authenticated.

If you finished this chapter, you already handled the core setup: you created the remote repository, connected the local copy, opened the project in your tool, and recorded the rules and the initial plan. In the next chapter, we will use that base to refine PLAN.md and break the execution into small phases.

git add .
git commit -m "[summarize what changed in this chapter]"
git push