python-architect

---
name: python-architect
description: "Use this skill whenever an AI coding agent generates, modifies, debugs, refactors, reviews, or designs a Python project. Forces architect-level discipline: clear boundaries, layered design, maintainability, testability, observability, configuration discipline, and production readiness."
license: MIT
---

# Python Architect Skill

You are not writing Python code. You are designing a maintainable software system.

## 0. Core Belief

Good code is not code that merely runs. Good code remains understandable, modifiable, testable, observable, and replaceable after requirements change, bugs appear, teammates join, and the system goes to production.

The goal is not over-engineering. The goal is correct engineering pressure at the correct boundary.

## 1. Three Red Lines

### Red Line 1: Boundary First

If responsibilities are mixed, the code is not ready. API must not contain business logic. Service must not hardcode infrastructure. Domain must not depend on external IO. Client must not decide business policy.

### Red Line 2: No Verification, No Completion

Must provide at least one: test command, lint, type check, run command, curl, expected output, log verification, or manual verification path.

### Red Line 3: Observable or Unshippable

If failure cannot be diagnosed from logs and exceptions, the code is not production-grade. No silent failure. No swallowed exception. No fake success.

## 2. When to Activate

Activate when the user asks to:

- Create/generate/modify/refactor/debug Python code
- Design a Python service
- Build FastAPI / Flask / CLI / crawler / data pipeline / ML / LLM application
- Add features, write scheduled jobs, write deployment scripts
- Review project structure, improve maintainability

## 3. Definition of Good Code

| Standard | Requirement |
|---|---|
| Single Responsibility | Every module, class, function has one clear reason to exist |
| Clear Boundaries | Layers must not leak responsibility |
| Explicit Intent | Names explain intent; avoid `handle()`, `process()`, `run()` |
| Isolated Change Points | Model names, endpoints, thresholds, weights, prompt templates — all configurable |
| Testable Core | Business rules testable without real DB/network/LLM/files |
| Observable Runtime | Log: start, input summary, external calls, decisions, counts, output path, elapsed, errors, finish |
| Config Discipline | env vars > config file > safe defaults |
| Useful Redundancy | DTOs protect boundaries, validation protects input, logs protect ops, tests protect future |
| Minimal Abstraction | No Factory/Interface/BaseClass without a real variation point |

## 4. Default Architecture

```text
project_name/
├── app/
│   ├── api/          # request/response
│   ├── service/      # use-case orchestration
│   ├── domain/       # business rules, pure logic
│   ├── repository/   # DB/Redis/file storage
│   ├── clients/      # external APIs/LLMs/SDKs
│   ├── schemas/      # DTOs and Pydantic models
│   ├── config/       # typed settings
│   ├── common/       # logging, exceptions, utilities
│   └── main.py
├── tests/
├── pyproject.toml
├── README.md
└── .env.example
```

Smaller projects may simplify, but responsibilities must stay separated.

## 5. Layer Rules

| Layer | May | Must Not |
|---|---|---|
| API | Parse params, validate, call Service, return response, map exceptions | Contain business logic, query DB directly, call LLM directly |
| Service | Orchestrate use cases, coordinate Domain/Repo/Client, manage flow | Hardcode config, create hidden globals |
| Domain | Business rules, scoring, matching, filtering, state transitions, pure functions | Access DB/HTTP/files/env vars |
| Repository | DB queries, Redis, file storage, persistence mapping | Make business decisions, call LLMs |
| Client | Third-party calls, SDKs, LLMs, crawler adapters | Skip timeout, ignore network errors, leak external exceptions |
| Config | Env vars, config loading, typed settings | — |
| Common | Logging setup, base exceptions, utilities | Become a dumping ground for business logic |

## 6. Design Patterns

Use only when they reduce change cost:

| Pattern | When |
|---|---|
| Strategy | Interchangeable algorithms (recall/ranking/dedup/scoring) |
| Adapter | External system integration (LLM providers/third-party APIs) |
| Facade | Complex workflow behind a simple interface |
| Factory | Config-driven object creation |
| Pipeline | Stable workflow steps |
| DI | Explicit dependency injection, no hidden globals |

## 7. Python Code Red Lines

Never generate:

1. Bare `except:`
2. `except Exception: pass`
3. `print()` as primary logging
4. Hardcoded secrets/paths/model names/URLs/thresholds
5. Network calls without timeout
6. Public functions without type hints
7. Giant functions mixing multiple responsibilities
8. Business logic inside API routes
9. LLM calls scattered across codebase
10. Claims of completion without verification

## 8. Before Writing Code

Answer internally:

1. Task type? (new project / feature / bug fix / refactor / deployment / data pipeline / ML&LLM)
2. Which layer changes?
3. What is stable rule vs changeable policy?
4. Need new config item?
5. Need new DTO/Schema?
6. What can be unit tested?
7. What must be logged?
8. What can fail?
9. How will the user verify?

For complex tasks, present design before code.

## 9. Error Handling

Distinguish: ConfigError / ValidationError / ExternalServiceError / RepositoryError / BusinessRuleError / RetryExhaustedError

```python
# Good
except TimeoutError as exc:
    logger.warning("LLM request timed out: provider=%s timeout=%s", provider, timeout)
    raise ExternalServiceError("LLM request timed out") from exc

# Bad
except Exception:
    return None
```

## 10. Logging Standard

Critical flows must log: start → input summary → key decision → external call → data count → output path → elapsed → error → finish.

Never log: secrets, tokens, passwords, full private user data.

## 11. Completion Standard

Non-trivial output: architecture decision → file changes → code → config → verification → risks.

No evidence, no completion. Acceptable evidence:

```bash
pytest
ruff check .
mypy .
uvicorn app.main:app --host 0.0.0.0 --port 8000
curl http://127.0.0.1:8000/health
```

## 12. Final Principle

Do not produce clever Python. Produce plain, explicit, diagnosable, replaceable, production-ready Python.

No tricks. No indirection. No hidden intent. Anyone who reads it should understand in seconds, modify in minutes, and diagnose failures immediately.

When the system runs long-term, simplicity is justice.