Skip to content
build-3000
fundamentals

Projects, Files and Structure

What a project folder is, why structure matters, and the files every project has.

Before this: Terminal Basics

Objective

Recognize the standard files in any modern project folder and explain what each one is for, so agent-created structures stop looking random.

Vocabulary

The words to use when directing your agent.

project
One folder holding everything an application needs - code, settings and description files.
config file
A file that stores settings so tools know how to treat the project.
dependency
Someone else's pre-built code package your project uses instead of rewriting it.
README
The front-door document explaining what a project is and how to run it.
entry point
The file where a program starts executing.

Understand it

Reading a project folder like a map

Top level: manifest files (what this project is and needs), README (how to use it), source folders (where code lives), config files (how tools should behave). When your agent generates a new project, walk this map out loud with it once.

Structure is communication

Folders group things that change together: UI code near UI code, settings near settings. Good structure makes the next change easy to find; bad structure makes even the agent guess.

Core concepts

Conventions carry meaning

Tools expect certain names: package.json tells JavaScript tools what your project needs, README.md introduces it to humans. Following conventions lets every tool - including agents - orient instantly.

Dependencies are borrowed strength

Modern apps are mostly assembled from packages other people published. A manifest file lists what you borrow; a lockfile pins exact versions. More dependencies mean more power and more surface area to maintain.

Examples

Two files every repo has

README.md answers 'what is this and how do I run it'; the manifest (like package.json) answers 'what does it depend on'. Open both first in any unfamiliar project.

node_modules is rented furniture

Downloaded dependencies land in a folder you never hand-edit and never need to back up - it can be rebuilt from the manifest anytime.

Common mistakes

Common mistake

Letting the agent scatter files randomly across the project.

Fix

Insist on one conventional layout: 'Follow standard Next.js structure and explain the role of each top-level file.'

Common mistake

Hand-editing lockfiles or downloaded dependency folders.

Fix

Change the manifest through the package manager command; regenerate the rest.

Working with your AI agent

After any scaffold, ask: 'Show me the project tree and label each top-level entry: mine-to-edit, tool-generated-but-readable, or never-touch.' Keep this map in your head for every future project.

Build it

The module’s real project. Your agent builds; you direct and inspect.

Project: Project Blueprint

Create the skeleton of a real web project - not a working app yet, just the honest bones: README, manifest-style metadata and an organized folder plan you generate with your agent.

Requirements

  • A project folder named blueprint with a README.md describing purpose and how someone would run it
  • A valid package.json with name, version, description and license fields
  • src/ and public/ folders present with a one-line placeholder file in each explaining its future role

Context for your agent

Scaffold a minimal static web project folder called blueprint: package.json with sensible metadata, README.md written in plain language for a newcomer, src/ and public/ directories each containing a PLACEHOLDER.md one-liner about the folder's purpose. Use standard conventions only; no installed dependencies, no build tooling.

Verify it - twice

Check every item yourself first. Then hand your agent the prompt and compare verdicts.

Self-verified0/5
Functional
Architecture
Testing

Verification prompt - paste into your AI agent

Review my Project Blueprint folder. Check against this Definition of Done and answer PASS or FAIL per item using evidence from the actual files: (1) contains exactly README.md, package.json, src/ and public/ with nothing stray at the root, (2) package.json is valid JSON with name, version, description, license, (3) README states purpose plus a plausible run instruction, (4) each placeholder file describes its folder's role in one line. Then tell me which convention a professional reviewer would say I got most wrong, if any.

Run this against “Projects, Files and Structure” after your own checklist pass. Where the agent and you disagree, investigate before moving on.

Review questions

Answer out loud. If you cannot, revisit before moving on.

  1. Which two files do you open first in an unfamiliar project, and why?

  2. What is the difference between a manifest and a lockfile?

  3. Why should you never hand-edit downloaded dependency folders?

You can now

  • Read any project folder's structure and explain its parts
  • Instruct an agent to follow conventions instead of inventing layouts
  • Explain what dependencies are and where they live

Up next

Working With AI Coding Agents