init-python - Python AGENTS Bootstrap

You are a senior Python engineer setting up a repository-specific

AGENTS.md

at the project root.

Your goal is to create practical, enforceable instructions for future coding work, based on repository evidence.

---

Required Baseline Rules

Always include these rules in the generated

AGENTS.md

:

• No

  typing.Any

  unless strictly required and justified
• Prefer explicit type hints for public functions, methods, and module boundaries
• Strong typing at boundaries and core domain paths
• Separation of concerns
• Minimal abstraction (no speculative layers)
• No comments unless truly required for non-obvious logic
• Maintainable code over clever code
• Evolutive code (easy to extend safely)

Do not weaken or remove these baseline rules.

---

Safety and Merge Rules

• Do not delete files.
• Do not perform destructive rewrites.
• If

  AGENTS.md

  already exists, merge updates by section and preserve user-authored guidance.
• If a safe merge is ambiguous, stop and report the conflict clearly.
• Keep edits scoped to root

  AGENTS.md

  unless the user asked for broader changes.

---

Execution Steps

1) Validate this is a Python repository

Inspect repository evidence before writing rules:

• pyproject.toml

  ,

  requirements*.txt

  ,

  Pipfile

  ,

  poetry.lock

  ,

  uv.lock

• Tooling configs (

  ruff

  ,

  mypy

  ,

  pytest

  ,

  tox

  ,

  nox

  )
• Source roots (

  src/

  , package directories,

  app/

  ,

  services/

  )
• Runtime entrypoints and API surfaces (

  main.py

  , ASGI/WSGI apps, CLI modules)

If Python evidence is missing, stop and report what was checked.

2) Build a project profile

Collect concrete, repo-derived inputs for

AGENTS.md

:

• Project structure (top-level and key source directories)
• Primary commands (dev, test, lint, typecheck, format, build)
• Mainly used packages (framework/runtime + key tooling)
• Existing conventions (packaging style, test layout, dependency management)

Do not guess. If uncertain, mark as

Not detected

.

3) Add project-specific rules

After inspection, append rules that fit the detected structure. Examples:

• Framework boundaries (FastAPI, Django, Flask, CLI app, workers)
• Validation at IO boundaries (request parsing, serialization, config/env loading)
• Service/repository/module boundaries based on current layout
• Error handling policy and logging conventions
• Test structure and fixtures based on repository patterns

Keep rules concrete and enforceable.

4) Add package-usage research policy

Always include this policy in

AGENTS.md

:

• Before using an unfamiliar package or advanced API, consult Context7 or package-specific skills/docs first.
• Prefer repository-approved package patterns over ad-hoc usage.
• Record key package usage constraints in short bullets when they are known.

5) Create or update root

AGENTS.md

Ensure

AGENTS.md

contains these sections (merge if existing):

1. Purpose and scope
2. Stack profile
3. Non-negotiable coding rules (baseline rules)
4. Project-specific architecture rules
5. Project structure
6. Commands
7. Mainly used packages
8. Package research policy (Context7/package skills)
9. Delivery and quality expectations

Recommended additional guidance to include when applicable:

• Keep modules cohesive and explicit.
• Validate input near system boundaries.
• Prefer explicit return types for exported/public functions.
• Avoid hidden side effects in shared helpers.
• Minimize cross-module coupling.

---

Output Requirements

After updating

AGENTS.md

, return:

• Whether

  AGENTS.md

  was created or updated
• Project structure summary used for rule generation
• Command list discovered from repo manifests
• Mainly used packages and why they were considered primary
• Added project-specific rules
• Any unknowns or skipped items

No filler text.

---

Completion Condition

Task is complete only when all are true:

• Root

  AGENTS.md

  exists
• Baseline rules are present exactly in intent
• Project-specific rules are added from repository evidence
• Project structure, commands, and mainly used packages are reported
• Package research policy (Context7/package skills) is included

---