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.
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.
Which two files do you open first in an unfamiliar project, and why?
What is the difference between a manifest and a lockfile?
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