You open the project your agent built and the sidebar is a wall of files: a .ts here, a .json there, a .env, a README.md, a Dockerfile with no extension at all. Most of them you will never edit by hand. This chapter gives you the quick read: glance at any file and know what it is for, and whether it is yours to touch.
4.3.1Every file is code, config, or data
Almost every file falls into one of three buckets, and sorting them is most of the battle:
| Kind | Holds | Looks like |
|---|---|---|
| Code | the logic that runs | .ts, .js, .py |
| Config | settings and wiring | .env, .yaml |
| Data | information the app reads | .json |
Name the bucket first and no file looks like noise.
4.3.2JSON and YAML hold your data
Two formats carry most of the data and settings you will see. JSON is the everyday one, used by data files and by package.json:
YAML says the same kind of thing with less punctuation, and shows up in config and deploy files:
Both just store labeled values. You can read them straight off the page, which is the whole point of them.
4.3.3Config and secrets stay out of the code
Configuration is everything that changes between your laptop and the live server: the database address, an API key, a feature toggle. It lives apart from the code so the same code runs anywhere.
The values that differ per machine are environment variables, usually listed in a file named .env:
A secret like that key lives in .env, never pasted into the code, because code gets shared and read while .env stays private. The Secure part covers why that line matters and how to keep it airtight.
4.3.4The rest you just need to recognize
A handful more you only need to recognize, not master:
- Markdown (
.md) is plain text with light formatting. YourREADME, the front-door notes for a project, is Markdown. package.jsonand its lockfile list the outside code your app depends on, and pin the exact versions.- A
Dockerfileand other infra files describe how the app is packaged and run on a server. Your agent writes these, and the Ship part is where they matter.
You recognize the shape and move on. The agent handles the contents.
Do this now: paste the prompt over your repo and have the agent label every file type in plain words, so the sidebar stops being a wall of unknowns.
