{
  "context": "An agent was asked to create an AGENTS.md file for a Python FastAPI repository. The repository contains a pyproject.toml (with ruff and pytest configured), a README.md (describing the stack, directory structure, and containing two embedded non-obvious caveats: the dev server runs on port 8001 not 8000, and the legacy/ directory is deprecated but still imported by production services), and a CI workflow. A well-calibrated agent should recognize that tech stack details, directory structure, linting rules, and architecture descriptions are already discoverable from existing repo files — and should NOT copy them into AGENTS.md. It SHOULD surface only genuine non-discoverable landmines: the uv run pytest caveat, the legacy/ directory warning, and the non-standard dev port.",
  "type": "weighted_checklist",
  "checklist": [
    {
      "name": "Excludes tech stack summary",
      "description": "AGENTS.md does NOT contain a summary of the tech stack (e.g. 'This project uses Python, FastAPI, PostgreSQL, SQLAlchemy'). This information is trivially discoverable from pyproject.toml and README.md and adds no value in AGENTS.md.",
      "max_score": 6
    },
    {
      "name": "Excludes directory structure overview",
      "description": "AGENTS.md does NOT reproduce or paraphrase the directory/folder structure of the repository (e.g. 'src/ contains the application code, tests/ contains tests'). Directory layout is discoverable by listing the repo.",
      "max_score": 6
    },
    {
      "name": "Excludes linting rules already enforced by ruff",
      "description": "AGENTS.md does NOT instruct the agent to follow linting rules (line length, import ordering, etc.) that are already enforced and auto-checkable via ruff configured in pyproject.toml. Telling an agent 'keep lines under 88 chars' is redundant when ruff will catch violations.",
      "max_score": 6
    },
    {
      "name": "Excludes generic best-practice advice",
      "description": "AGENTS.md does NOT contain generic software-engineering platitudes such as 'write clean code', 'add docstrings to functions', 'follow PEP 8', or 'write tests for new features' that apply to any Python project and are not specific to this repository.",
      "max_score": 6
    },
    {
      "name": "Excludes architecture or design descriptions",
      "description": "AGENTS.md does NOT describe the application architecture (e.g. 'the app follows a layered architecture with routers, services, and repositories'). Architecture is either discoverable from the code or belongs in a separate design document.",
      "max_score": 5
    },
    {
      "name": "Includes the uv run pytest caveat",
      "description": "AGENTS.md explicitly warns that pytest MUST be invoked as `uv run pytest` and NOT as plain `pytest`, due to a test fixture caching bug. This is a genuine landmine: it is mentioned only in the README in a note, is not encoded in pyproject.toml, and is easy for an agent to get wrong.",
      "max_score": 14
    },
    {
      "name": "Includes the legacy/ directory warning",
      "description": "AGENTS.md explicitly warns that the `legacy/` directory is deprecated but is still actively imported by production services and must NOT be deleted or restructured without cross-team coordination. This is a non-obvious trap not encoded in any config file.",
      "max_score": 14
    },
    {
      "name": "Includes the non-standard dev server port (8001)",
      "description": "AGENTS.md explicitly notes that the development server runs on port 8001, not the port 8000 stated in the README documentation. This discrepancy is a real operational landmine for anyone (human or agent) running integration tests or curl commands against a locally running server.",
      "max_score": 13
    },
    {
      "name": "Content is specific and actionable",
      "description": "Every item in AGENTS.md is specific to this repository and actionable — it tells an agent something concrete to do or avoid. Vague entries like 'be careful with the database' or 'check the README for details' do not satisfy this criterion.",
      "max_score": 10
    },
    {
      "name": "Signal-to-noise ratio is high",
      "description": "AGENTS.md is concise: the ratio of genuinely non-discoverable warnings to total content is high. A file that buries the three real landmines in ten lines of boilerplate scores poorly here. Ideal AGENTS.md is short and every line earns its place.",
      "max_score": 10
    },
    {
      "name": "Does not duplicate README installation instructions",
      "description": "AGENTS.md does NOT reproduce setup or installation steps (e.g. 'run pip install -e .' or 'create a virtual environment') that are already documented in README.md. An agent can read the README; repeating it wastes space and creates a maintenance burden.",
      "max_score": 10
    }
  ]
}