EC1B1 Python Coding SupportFollow-up resources for LSE BSc Economics
← Back to resources

AGENTS.md Writing Guide

How to write a concise, high-value AGENTS.md file for coursework projects that use AI coding tools.

Updated 2026-02-20

Why this page exists

In Session 5, we discussed that good AI results come from good project structure. A central part of that structure is AGENTS.md: a short project instruction file that your coding agent reads before working on tasks.

This guide turns that idea into a practical checklist you can use immediately.

What AGENTS.md does

Think of AGENTS.md as your project constitution:

  • It sets the goal and constraints.
  • It defines the coding and data rules.
  • It keeps outputs consistent across multiple tasks.

Without this anchor, projects drift more easily, especially when you use skills and sub-agents in parallel.

Core rule: keep it concise

A long AGENTS.md usually performs worse than a short one.

Why:

  • The agent reads this file before each task.
  • Very long instructions add noise and reduce precision.
  • Short, specific rules are easier to follow and verify.

What to include vs avoid

Include:

  • Project goal in 2-4 lines.
  • Coding standards (language, style, reproducibility).
  • Data handling rules (for example: never overwrite raw files).
  • Clear quality checks and acceptance criteria.
  • Communication markers (for example [TODO], [REVIEW]).

Avoid:

  • Full coursework text copied into the file.
  • Long implementation plans for every section.
  • Full variable dictionaries unless essential.
  • Repeating every repository folder detail.
  • Generic advice that does not affect decisions.

Recommended drafting workflow

  1. Read the coursework brief first.
  2. Ask your tool to draft an AGENTS.md from that brief.
  3. Trim aggressively:
    • remove anything that is too detailed
    • keep only constraints that guide decisions
  4. Add one or two non-negotiable project rules.
  5. Iterate once after your first coding pass.

Minimal template

# AGENTS.md

## Project Goal
State the question and intended outputs in plain language.

## Scope
What is in scope this week, and what is out of scope.

## Coding Standards
- Python version and core packages
- Style conventions
- Reproducibility requirements

## Data Rules
- Never overwrite raw source files.
- Keep derived datasets in a separate folder.
- Document transformations.

## Workflow Rules
1. Plan before execution.
2. Implement in small steps.
3. Verify outputs before accepting changes.

## Quality Checks
- Code runs in a clean environment.
- Variable definitions stay consistent across files.
- Written interpretation matches actual results.

Worked example from this repository

The mock coursework project contains a concrete example at CourseworkMock/AGENTS.md.

Useful patterns from that file:

  • explicit target audience and skill level
  • clear coding standards
  • clear data/content constraints
  • communication tags for collaboration ([TODO], [REVIEW], [CLARIFY])

Common mistakes

  • Treating AGENTS.md as a notebook of everything you know.
  • Copying long references without turning them into actionable rules.
  • Forgetting data safety rules (especially around raw CSV files).
  • Never revisiting the file after project scope changes.

Related resources

Primary references