Designing AGENTS.md Files

Welcome back! In the previous lesson, we successfully normalized our raw Netflix dataset and loaded it into a Postgres database. We now have a solid foundation of data, but before we start writing the backend code to serve this data, we need to onboard a crucial member of our team: Codex, our AI assistant.

Imagine hiring a new developer. On their first day, you wouldn't just tell them, "build a backend," and walk away. You would show them where the files are, explain the database structure you just built, and share the team's coding guidelines. If you skip this, they might write code that doesn't fit your system or reinvent wheels you already have.

In this lesson, we are going to create that "onboarding handbook" for Codex. By doing this, we ensure that when we ask Codex to write complex SQL queries or Python endpoints later, it understands exactly how our specific project works.

The tool we use to onboard Codex is a file named AGENTS.md.

While Codex is trained on billions of lines of public code, it does not know the specific decisions we made in this project — like the fact that we split movies and tv shows into a single shows table with a type column.

The AGENTS.md file acts as the "long-term memory" or the "source of truth" for the AI. It is a simple Markdown file placed at the root of your repository. When Codex works on your project, it looks at this file to understand:

1. Context: Where files are located.
2. Data: How the database is structured.
3. Rules: How you want code to be written.

A well-written AGENTS.md transforms Codex from a generic coding bot into a specialized teammate that knows your project inside and out.

To make effective use of our AGENTS.md file, we rely on two specific Codex commands.

The /init command is the handshake. When you run this command in the chat, Codex scans your repository to build an initial understanding of your project and write an AGENTS.md file.

The /review command is the quality control. After you or Codex writes some code, you can use /review to ask Codex to check the work.

Codex will compare the code against the guidelines in AGENTS.md. For example, if your guidelines say, "Always use snake_case for variables," and the code uses camelCase, the /review command will flag it. This helps maintain consistency without you having to manually nitpick every line.

A good AGENTS.md file should contain:

• Project Structure & Modules: A clear outline of your repository’s folders and what each contains. This helps Codex understand where to find and place files.

• Database Schema: A concise summary of your database tables, their key columns, and relationships (such as primary keys, foreign keys, and junction tables for many-to-many relationships). This enables Codex to write accurate queries and understand your data model.

• Setup Commands: The exact commands needed to install dependencies, run scripts, or set up the environment. This ensures Codex knows how to execute or modify scripts correctly.

• Coding Style & Naming Conventions: Guidelines for language, formatting, naming, and any other conventions you want Codex to follow. This keeps generated code consistent with your team’s standards.

• Testing Guidelines: Any instructions or notes about how code should be tested or validated, even if you don’t have automated tests yet.

By including these sections, your AGENTS.md will provide Codex with the essential context it needs to work effectively within your project.

In this lesson, we designed the brain for our AI teammate. We learned that AGENTS.md is a context file that helps Codex understand our project's structure, database schema, and coding rules.

We also discussed how the /init command loads this context and the /review command checks against it.

In the upcoming practice, you will create this AGENTS.md file yourself. This is a critical step; once this file is in place, we can start building our API endpoints with the confidence that Codex understands exactly what we are building.