python-fastapi

Imported from FunnyNjK/ai (by-tool-and-stack/augment/python-fastapi/AGENTS.md). Install upstream with npx skills add FunnyNjK/ai --skill python-fastapi. Copyright stays with the author.

Augment + Python + FastAPI Starter

This starter is optimized for Augment using a balanced team style.

Target stack: Python + FastAPI

Stack Defaults

FastAPI defaults centered on typed request and response models, explicit dependency injection, and pragmatic async behavior.

Naming

• Use snake_case for modules, functions, variables, and fixtures.
• Use PascalCase for classes and Pydantic models.
• Name routers, services, and dependencies by domain purpose rather than framework plumbing.

Structure

• Organize by feature with routers, schemas, services, and repository or gateway boundaries as needed.
• Keep FastAPI route functions thin and move business logic into plain Python services.
• Separate external clients and persistence concerns behind interfaces or clear adapter modules.

Dependencies

• Prefer standard library plus FastAPI, Pydantic v2, and first-party ecosystem tools before adding convenience packages.
• Use async only where I/O benefits from it; keep CPU-bound work out of request threads.
• Keep settings centralized with typed configuration.

Testing

• Default to pytest and HTTP-level tests for routes plus unit tests for service logic.
• Use fixtures to share setup, but keep them readable and scoped.
• Cover validation, error translation, and permission checks alongside happy paths.

Do

• Use typed request and response models consistently.
• Return explicit error shapes and status codes.
• Document environment settings and startup dependencies.

Avoid

• Do not hide state in module globals.
• Do not mix database calls directly into route handlers.
• Do not add background tasks or caching until the need is clear and observable.

Recommended UI Overlays

• None

Communication Style

• Lead with the answer, then add supporting detail only when it helps the current task.
• Restate the goal in one sentence before making large changes or proposing a non-obvious approach.
• Surface assumptions early and keep open questions short, concrete, and actionable.
• Recommend one path when tradeoffs exist instead of handing the user an unranked list of options.
• Use calm, direct status updates that explain what changed, what is being verified, and what remains.

Collaboration Norms

• Treat the existing codebase, tooling, and team conventions as the source of truth when they are already established.
• Prefer the smallest safe change that solves the problem without spreading unnecessary refactors into adjacent areas.
• Call out meaningful tradeoffs before crossing architecture, security, performance, or compatibility boundaries.
• Leave changed code easier to read and easier to review than it was before the edit.
• Avoid surprising the team with hidden dependencies, silent workflow changes, or unannounced behavior shifts.

Planning Expectations

• Inspect current code, configuration, and tests before changing behavior or recommending a design.
• For medium and large tasks, outline the implementation approach, risk areas, and validation plan before editing.
• Break work into reviewable steps that can be tested independently and rolled back cleanly if needed.
• Validate with the closest relevant checks available, and note any checks that could not be run.
• If blocked, explain the blocker, the impact, and the smallest next action that would unblock progress.

Coding Standards

• Favor clear control flow and explicit data movement over clever abstractions or compressed one-liners.
• Keep functions, methods, and components focused on one responsibility and one level of abstraction.
• Handle errors, nullability, retries, and user-facing failure modes intentionally rather than implicitly.
• Preserve public APIs and contracts unless the task explicitly includes a breaking change.
• Add short comments only when the intent or tradeoff would otherwise be hard to infer from the code.
• Prefer deterministic, idempotent behavior for automation, scripts, generators, and background jobs.

Naming Conventions

• Use descriptive domain language that explains intent instead of implementation trivia.
• Keep type, class, and component names noun-based and specific to the business concept they represent.
• Use verb-based names for actions, handlers, commands, migrations, and background jobs.
• Name booleans with is, has, can, should, or an equally explicit affirmative prefix.
• Avoid abbreviations unless the abbreviation is already standard in the ecosystem or product domain.
• Prefer consistency with nearby code over introducing a new naming scheme for a single change.

Architecture Boundaries

• Keep transport, UI, persistence, and infrastructure details at the edges of the system.
• Move business rules into testable units that can be exercised without network or framework bootstrapping.
• Depend on explicit seams for external services, file systems, queues, caches, and third-party SDKs.
• Avoid cross-layer shortcuts that save time now but obscure ownership or increase hidden coupling.
• When no project pattern exists yet, prefer feature-oriented organization over dumping everything into generic folders.

Testing Expectations

• Add or update tests for behavior changes instead of relying on manual verification alone.
• Prefer fast unit tests plus targeted integration coverage at boundaries where wiring matters.
• Cover success paths, failure paths, and at least one realistic edge case for new logic.
• Keep tests deterministic, readable, and narrowly scoped to the behavior they are proving.
• Use end-to-end coverage sparingly for the flows that matter most to users or release safety.

Code Review Checklist

• Check correctness first: does the code solve the right problem and preserve expected behavior?
• Review regression risk next: migrations, data flow, concurrency, permissions, and edge-case handling.
• Prefer simpler designs when two options satisfy the same requirement with comparable safety.
• Verify that tests, docs, flags, schemas, prompts, and examples were updated with the code change.
• Flag security, privacy, accessibility, and operability issues before polish or style concerns.

Documentation Expectations

• Update README, local runbooks, or setup notes whenever developer workflows or required steps change.
• Document public APIs, configuration flags, environment variables, and non-obvious operational constraints.
• Record design decisions near the code or in project docs when future maintainers will need the rationale.
• Keep examples copy-pasteable and aligned with the supported tooling and folder structure.
• When behavior is intentionally limited or deferred, document the boundary instead of implying full support.

Security And Secrets

• Never hardcode secrets, credentials, tokens, or private endpoints in source, prompts, or examples.
• Use environment variables, secret stores, and least-privilege access patterns by default.
• Validate inbound data, encode outbound data appropriately, and avoid trusting client-supplied state.
• Do not log secrets, personal data, or privileged internal details unless explicitly required and protected.
• Scrutinize third-party packages, generated code, and copy-pasted snippets before adopting them.

Dependency Discipline

• Prefer existing dependencies and platform capabilities before adding a new package or framework.
• Add a dependency only when it clearly improves speed, safety, or maintainability for the current team.
• Choose well-maintained libraries with active ecosystems, stable licenses, and clear upgrade paths.
• Do not add overlapping packages that solve nearly the same problem unless a migration is underway.
• Remove dead code, obsolete prompts, or unused packages when touching the surrounding area.

Definition Of Done

• The requested behavior works, and the solution fits the project structure without surprise side effects.
• Relevant tests or checks were run, or the exact verification gap is documented with impact and next steps.
• Names, errors, docs, and developer experience are clean enough that another teammate can continue confidently.
• New instructions, prompts, or automation guidance are updated when the change affects how AI should work here.
• The final diff is reviewable, scoped, and ready for the next engineer to understand quickly.