Project Files That Matter

A new repo shows folders and dot-files and it’s tempting to think you must hand-make all of it. You don’t: tell a coding assistant “scaffold a web project with a clean structure and local env files” and it creates the starter set. Your job is knowing what the important files do, so you can direct it and check the result.

The usual layout

my-project/
├── AGENTS.md            # Rules for coding agents
├── CLAUDE.md            # Rules for Claude Code
├── package.json         # Dependencies and scripts
├── .env                 # Private keys (stays on your machine)
├── .gitignore           # Tells Git what never to commit
├── src/                 # Application code
│   ├── components/      # UI pieces and layouts
│   ├── pages/           # Routes and endpoints
│   └── lib/             # Helpers and data models
└── public/              # Images, icons, files served as-is

• src/ — the app itself. Most agent edits land here.
• public/ — logos, hero images, downloads. Served directly, no build step.
• package.json — what the project installs and the commands it runs (npm run build, npm run dev).
• AGENTS.md / CLAUDE.md — instructions the agent reads each session: style, libraries, no-go directories.

Why .gitignore matters

Git records files and can push them to GitHub. A private config file with no exclusion rule goes along for the ride. .gitignore lists the files Git must skip.

How it works

Git checks the patterns when you stage: a match stays out of the commit, so it never reaches GitHub in that commit.

What to list

For a project with secrets and build output:

# Secrets - never commit
.env
.env.local
.env.*.local

# Installs and build output
node_modules/
dist/
.astro/

.env in .gitignore stops most accidents. Still glance at staged files before each commit.

Steering with AGENTS.md

AGENTS.md (or CLAUDE.md for Claude Code) loads at session start. Put standing rules there instead of retyping them:

• “Run the build check after editing components.”
• “Tailwind utilities only; no raw custom CSS.”
• “Don’t touch files outside src/ without asking.”

Small first version, reviewed diffs, checks green — that’s the loop.