Class 07 · Movement 01
Files, Repos
& Structure
Session 07 · AI Engineering
Session 07 · Know your files

Every file is a contract — with a different reader.

The browser reads
.html.css.js

Public by definition — every byte inspectable in DevTools. The dining room has no locked drawers.

Build machines read
package.jsonnext.config.mjs

The app’s ID card — name, dependencies, scripts — read once at build time, before any user exists.

Git & the host read
.gitignore_redirects

Readers you configure, not code: git obeys .gitignore — node_modules/ · out/ · .env never enter history — and Netlify obeys _redirects for routing.

The database reads
.sql

Schema: the declared shape of your data — tables, columns, types. Migration: a versioned, scripted change to it.

The model reads
CLAUDE.mdAGENTS.mdSKILL.md

The newest reader in the building. No parser needed — the parser is the model. Prose in, behavior out.

The runtime alone reads
.env

Keys and passwords, handed to the app from outside the code — no human, no repo, no browser, just the process at startup. Never committed.

Session 07 · The true history · 2024–2026

The war over a filename.

1 · The mess
CLAUDE.md.cursorrulescopilot-instructions.mdGEMINI.md

Four vendors, four filenames. Teams running three tools kept three near-identical files — drifting apart.

2 · AGENTS.md ships · Aug 2025

“A README for agents.” Plain Markdown, no schema, no required fields — the minimalism is the strategy: nothing to standardize, nothing to fight about.

3 · It wins by shipping
20,000 → 60,000+ repos, launch → Dec 2025
28+ tools read it natively, mid-2026
4 · The blessing · Dec 9, 2025

The Linux Foundation’s Agentic AI Foundation launches on three donations — MCP (the connector standard behind our own /connect), goose (Block’s open agent), AGENTS.md. It ratified a fait accompli — blessed what had already won.

5 · The holdout is your own tool

Claude Code still reads only CLAUDE.md — against a 5,200+ reaction issue cluster (captured Aug 2026). The community’s bridge is one line:

CLAUDE.md  →  @AGENTS.md
How to read any standards fight, forever: count shipped implementations, not foundation logos.
Compendium: “The Agent-Instruction File Wars” · “How Standards Win” · counts dated on-slide
Session 07 · Secrets hygiene

The most important file never ships.

The rule
.env→.gitignore→host env vars

Two separate dangers, one file dodges both: anything shipped to a browser is public — and anything committed is in history forever. So keys live in a file git never sees, and production gets them from the host (Netlify → Site settings → Environment variables).

23.8Mnew credentials leaked on public GitHub in 2024 alone (+25% YoY)
70%of 2022’s leaked secrets were still active years later
+81%surge in leaked AI-service keys (2026 report) — every student now has one to lose
May 2026 · the near-miss that wasn’t

A public GitHub repo literally named Private-CISA — kept by a contractor for the US cyber-defense agency — sat exposed Nov 2025 → May 2026 with AWS GovCloud admin keys in it. If CISA’s contractor can commit secrets, so can you.

A secret that ever touched a commit is burned.

Git history is forever — rotate it, don’t delete it. In Movement 3 your team holds a partner business’s keys. This reflex is part of what the CTSBDC is trusting us with.

GitGuardian, State of Secrets Sprawl 2024–2026 · Krebs on Security, May 18 2026 · compendium: “Security for AI-Era Shippers”
Session 07 · Writing for the newest reader

Five sections. ~200 lines. Hand-written.

The skeleton — and nothing else
  1. 1build / test / lint commands
  2. 2project map — where things live
  3. 3conventions a linter can’t enforce
  4. 4verification — run before claiming done
  5. 5repo-specific gotchas
Universally applicable instructions only · no generic advice — “write clean code” wastes tokens · prune it periodically
The receipt — ETH Zürich, AGENTbench · Feb 2026
−3%LLM-generated file vs no file at all: task success went down — and cost 20% more
+4%Hand-written file vs no file at all: success went up

Pasting a generated 400-line file made the agent worse than having nothing. Short beats long; written beats generated.

One source of truth

Write AGENTS.md; add a one-line CLAUDE.md — @AGENTS.md — and work identically in Codex, Cursor, Copilot and Claude Code. For a partner business, writing this file is a diagnostic deliverable: you can’t write it without understanding their repo. That’s Movement 3.

Compendium: “The Agent-Instruction File Wars” · ETH Zürich AGENTbench, Feb 2026 (138 instances, 12 repos)
Session 07 · The living exhibit

Label this repo.

package.jsonnpmthe app’s ID card — dependencies and scripts
data/curriculum.jsevery page of this sitethe declared single source of truth
app/globals.cssthe browserbrand tokens — navy, crimson, the fonts
public/_redirectsNetlify/apply → /assessment lives here, not in code
.gitignoregitwhat never enters history — .env, node_modules, out/
CLAUDE.mdthe modelpre-paid context — curated once, loaded every time the agent starts
out/your browser, right nowthe built artifact — this very slide

Your first critique: the guidance says agent files stay under ~200 lines — ours is 394 (as of Aug 2026), and still growing. And it’s a lone CLAUDE.md with no AGENTS.md bridge — breaking both of today’s rules. What would you cut, and would you migrate it?

Next class → you label a repo that is yours: build & present your app.
Connect.AI logoConnect.AI
Class 07 · Files, Repos & Structure01 / 06
1 / 6
Checking access…