Preparing Your Project Before Asking an AI for Code

Series "Learning to Code with AI" — Article 2/7

TL;DR

A coding agent works best when the need, stack, conventions, and validation criteria are explicit. Preparing the project isn’t about writing a fifty-line prompt. It’s about making the decisions that structure learning yourself.

The First Prompt Shouldn’t Ask for Code

When discovering Claude Code or Codex, the temptation is immediate: describe an application and watch the agent build it.

For our mini-dashboard, this might look like:

Create a modern Next.js dashboard that displays the status of my servers.
Add API calls, tests, and a nice interface.

This prompt can generate many files. Yet it says almost nothing.

Which metrics should be displayed? Where do they come from? What does the user see while loading? How to signal an unavailable API? Is authentication part of the scope? What allows us to consider the work complete?

When these decisions are missing, the agent makes them. The junior then discovers an architecture they neither chose nor understood.

Start with a Short Requirements Sheet

Our first version can fit into a few lines:

# Mini-dashboard — V1 Scope

## Objective

Display a synthetic server status from a simulated API.

## Metrics

- service status;
- CPU load as a percentage;
- used and total memory;
- used and total disk space.

## States to Handle

- loading;
- success;
- API unavailable;
- invalid response.

## Out of Scope

- real authentication;
- database;
- metric history;
- real-time graphs.

This document forces us to distinguish the real need from ideas that might come later.

Define What "Done" Means

A vague task encourages the agent to stop when it deems the result satisfactory. A verifiable task gives it a limit.

For the CPU card:

## Acceptance Criteria

- The card displays a value between 0 and 100.
- A `%` unit is visible.
- A missing or invalid value doesn’t cause a crash.
- An explicit state replaces the invalid metric.
- The main behavior is covered by a test.

These criteria aren’t reserved for project managers. They teach developers to turn an intention into observable behavior.

Choose a Stack Without Collecting Dependencies

Our foundation will be intentionally classic:

• TypeScript to make data structures explicit;
• React to build components;
• Next.js for the application framework;
• Vitest and React Testing Library for targeted unit tests;
• runtime validation for external data, if the need is confirmed.

Next.js directly integrates TypeScript and provides its configuration when creating the project. Its TypeScript documentation remains the reference for current behavior. For testing, the official guide presents several options, including Vitest, Jest, Playwright, and Cypress.

The choice of a tool should answer a question. "The AI knows this library" isn’t an architecture criterion.

Design an Architecture Small Enough to Be Understood

A first organization could be:

src/
  app/
    page.tsx
  components/
    MetricCard.tsx
    ServerOverview.tsx
  features/
    server-status/
      api.ts
      schema.ts
      types.ts
  test/

This structure isn’t a universal truth. It simply materializes three responsibilities:

• fetch data;
• verify its shape;
• display it.

If the junior can’t explain the reason for a folder, that folder may be premature.

Write the Repository’s Permanent Rules

Claude Code can read project instructions in CLAUDE.md. Codex notably uses AGENTS.md for the repository’s durable conventions. The official documentation describes Claude Code’s memory and instructions as well as Codex customization.

Our rules file could contain:

# Project Rules

- Use TypeScript in strict mode.
- Don’t use `any` without written justification.
- Don’t add a dependency without explaining the need and alternatives.
- Separate API access from display.
- Validate all external data before use.
- Modify few files per step.
- Present a plan before any significant modification.
- Run typing, linting, and relevant tests.
- Clearly signal what couldn’t be verified.

This file shouldn’t become an unreadable constitution. A rule deserves to be included when it’s stable, concrete, and verifiable.

Ask for an Analysis Before Implementation

The first useful exchange with the agent might look like this:

Analyze the requirements sheet and repository rules.
Don’t modify any files.

I want you to:
1. identify any missing decisions;
2. propose a breakdown into tasks of less than one hour;
3. list technical risks;
4. indicate how to verify each step;
5. ask me questions instead of choosing silently.

The junior should then challenge the plan. Why this dependency? Why a client component? Why this test? What happens with an invalid response?

Prepare Git Before Letting the Agent Act

Before the first modification:

• initialize the repository;
• check tracked files;
• create a clean first commit;
• ensure secrets and local files are ignored;
• learn to display a diff and return to a known state.

A clean history isn’t just for fixing errors. It allows comparing what the agent announced with what it actually modified.

Preparation Is Already Part of Learning

At this stage, we’ve barely coded anything. Yet we’ve worked on fundamental skills: scoping, breaking down, choosing, anticipating, and verifying.

This is precisely what the prompt "build me the whole application" would have made invisible.

In the next article, we’ll see how to find, inspect, and adapt skills without turning the project into a collection of contradictory rules.