Guide to Writing an AGENTS.md File for a Python Project

# AGENTS.md - AI Developer Instructions

## 1. Project Domain & Context

- **Project Name**: FastQuery
- **Domain**: High-performance asynchronous database wrapper for PostgreSQL using `asyncpg`.
- **Target Environment**: Python 3.11+ / Dockerized Linux containers.
- **Core Goal**: Provide type-safe, low-latency query execution with automatic connection pooling.

## 2. Setup & Environment Management

- **Dependency Manager**: Poetry (do NOT use raw `pip` or `requirements.txt`).
- **Virtual Env Activation**: `poetry shell`
- **Installation Command**: `poetry install --with dev`
- **Lockfile Policy**: Never run `poetry update` unless explicitly requested. Only use `poetry add [package]`.

## 3. Coding Conventions

- **Formatting**: Code must strictly conform to Ruff's formatting rules. Run `poetry run ruff format`.
- **Type Hinting**: Mandatory for all function signatures. Use `from typing import ...` or native subscription types (e.g., `list[str]` instead of `List[str]`).
- **Concurrency**: Use `async`/`await` paradigms. Avoid blocking synchronous calls inside async loops (e.g., do not use `time.sleep()`, use `await asyncio.sleep()`).
- **Error Handling**: Always catch specific exceptions. Never use bare `except:` clauses.

## 4. Project Structure

```text
fastquery/
├── src/
│   └── fastquery/
│       ├── __init__.py
│       ├── pool.py         # Connection pooling logic
│       └── client.py       # Main API client interface
├── tests/
│   └── test_client.py      # Integration and unit tests
├── pyproject.toml          # Poetry and tool configurations
└── AGENTS.md               # This file
```

---

## Lean vs. Sprawling: The Science of Context Windows

When writing an `AGENTS.md` file, there is a common temptation to include every single detail, error log, and architectural decision record (ADR). This leads to a "sprawling" file.

### The Cost of Context Bloat
1. **Attention Dilution (Lost in the Middle)**: Large Language Models use self-attention mechanisms. When you feed an LLM a massive context file, the model's ability to recall instructions located in the middle of the document drops significantly.
2. **Latency and Token Costs**: Every prompt sent to the LLM will prepend the `AGENTS.md` content. A 5,000-word file adds latency and drives up API costs. Using an aggregator like [n1n.ai](https://n1n.ai) to test models like Claude 3.5 Sonnet reveals that keeping instructions lean directly correlates with faster response times.
3. **Conflicting Instructions**: The larger the file, the higher the probability of introducing contradictory rules (e.g., demanding strict type safety in one section but showing dynamic, untyped examples in another).

### Keep it Lean: The "Need to Know" Principle
*   **Keep it under 150 lines**: If your `AGENTS.md` exceeds 150 lines, split it. Keep core operational instructions in `AGENTS.md`, and put architectural deep-dives into a separate `/docs/architecture.md` file which the agent can read only when necessary.
*   **Use Declarative Bullet Points**: Avoid long paragraphs. Use clear, imperative statements (e.g., "Use Ruff for linting" instead of "We have chosen to transition our styling standards to Ruff because...").

---

## Interactive Quiz: Test Your Understanding

Test your knowledge of writing effective instructions for AI agents in Python projects. Select your answers and review the explanations below.

### Question 1: Context Management
**An agent keeps writing code that violates your formatting standards despite your `AGENTS.md` specifying Ruff. The file is currently 350 lines long and contains detailed histories of your architectural decisions. What is the most effective way to resolve this?**

*   A) Add more examples of properly formatted code to the `AGENTS.md` file.
*   B) Delete the architectural history, trim the file down to under 150 lines, and place the formatting command at the top of the "Quality Gates" section.
*   C) Switch to a different LLM because the current one is incapable of following instructions.
*   D) Write a custom script that runs Ruff automatically every time the agent saves a file.

*Answer Explanation:*
**B** is the correct answer. Adding more examples (Option A) increases context bloat and worsens the "lost in the middle" effect. While automated scripts (Option D) are useful, they fix the symptom rather than the cause of agent misalignment. Trimming the file reduces attention dilution, allowing the agent to parse and execute the formatting constraints successfully.

### Question 2: Python Dependency Constraints
**Your Python project uses Poetry. The AI agent needs to add a dependency (`httpx`) to write a new feature. Which instruction in `AGENTS.md` best prevents the agent from breaking your lockfile?**

*   A) "Install dependencies using pip."
*   B) "Run `poetry update` to make sure all packages are up to date."
*   C) "Only add packages using `poetry add [package]`. Never run `poetry update` or modify `pyproject.toml` directly."
*   D) "Dependencies are managed automatically. Do not add any new packages."

*Answer Explanation:*
**C** is the correct answer. Running `poetry update` (Option B) can update unrelated dependencies, potentially introducing breaking changes. Modifying `pyproject.toml` manually without running the lock command causes inconsistencies. Explicitly instructing the agent to use `poetry add` ensures the lockfile is updated safely.

### Question 3: Formatting & Syntax Safety
**Why must you escape characters like `<` (as `&lt;`) or avoid raw curly braces `{}` in markdown files read by certain MDX parser integrations?**

*   A) It prevents the markdown parser from interpreting the symbols as HTML tags or React/JavaScript components, which would break the rendering engine.
*   B) LLMs cannot read the `<` symbol and will hallucinate if they encounter it.
*   C) It is a Python-specific requirement for parsing markdown metadata.
*   D) It increases the semantic density of the prompt.

*Answer Explanation:*
**A** is correct. Many modern documentation sites and agent interfaces use MDX (Markdown + JSX). Raw `<` signs followed by text or raw curly braces `{}` can cause build-time errors because the parser attempts to evaluate them as JSX code. Keeping files clean and escaped ensures compatibility across parser engines.

---

## Pro Tips for Python-Specific AGENTS.md Files

1. **Leverage Pyproject.toml Integration**: Instead of listing all your linting rules in `AGENTS.md`, configure them in `pyproject.toml` under `[tool.ruff]` and `[tool.mypy]`. Then, in `AGENTS.md`, simply tell the agent: "Run `ruff check .` to verify formatting." This keeps your markdown file clean and leverages the configuration files the agent is already reading.
2. **Dynamic Agent Routing**: Different tasks require different models. For code refactoring, a reasoning model like OpenAI o3-mini or DeepSeek-R1 is ideal. For standard documentation or boilerplate generation, Claude 3.5 Sonnet excels. Using [n1n.ai](https://n1n.ai) allows you to dynamically route these tasks to the optimal model while passing your structured `AGENTS.md` file as context.
3. **The "Agent Verification" Step**: Always include a rule in `AGENTS.md` that instructs the agent to run the quality gate command *before* returning its response. This forces the agent to self-correct errors in its own workspace before presenting the solution to you.

Get a free API key at [n1n.ai](https://n1n.ai)