A professional, batteries-included project template for Python projects. Built to work seamlessly with AI coding agents (Claude, Codex, Cursor) and human developers alike.
This template enforces a consistent, professional project structure across all your Python projects. It is specifically designed for vibe coding workflows — where AI agents (Claude, Codex, Cursor) do most of the heavy lifting — while keeping quality high and supervision low.
Goals:
- 🤖 Give AI agents clear, unambiguous instructions so they don't go off the rails
- ✅ Enforce code quality automatically (lint, format, type check) before every commit
- 🚀 Automate versioning and releases via Conventional Commits
- 🏗️ Maintain a clean 3-layer architecture from day one
| Tool | Purpose |
|---|---|
| Ruff | Lightning-fast linter (replaces flake8, isort, pyupgrade) |
| Black | Opinionated code formatter |
| Mypy | Static type checker |
| pre-commit | Runs ruff + black + mypy automatically before every commit |
| python-semantic-release | Auto version bumps, CHANGELOG, and GitHub Releases |
| pytest + pytest-cov | Test runner with coverage reporting |
| GitHub Actions | CI (lint + type check + tests) and CD (automated releases) |
| Dependabot | Weekly auto-updates for pip and GitHub Actions dependencies |
Makefile | Shortcuts: make lint / make test / make fix / make all |
AGENTS.md | Instructions for AI agents (Claude, Codex, Cursor…) |
CLAUDE.md | Claude-specific instructions with Karpathy principles |
CODEX.md | Codex-specific instructions + Windows git fix |
STACK.md | Project tech stack — read by agents before any change |
All projects using this template follow a strict 3-layer architecture:
src/ui/ → pages, components, views (display only)
↓
src/services/ → business logic, calculations, decisions
↓
src/repositories/ → DB queries, external API calls
Rules enforced in AGENTS.md:
- No business logic in UI files
- No DB/API access outside
repositories/ - No cross-layer calls (UI → repository is forbidden)
- Reuse existing services before creating new ones
Ruff handles linting (errors, warnings, imports, upgrades). Black handles formatting. They cover different concerns and are configured with matching line-length = 120 to avoid conflicts.
AI agents regularly generate untyped code. Mypy catches type errors before runtime and forces def func(x: int) -> str: annotations. Configured in pyproject.toml with disallow_untyped_defs = true.
CI catches errors after the push — pre-commit catches them before. Faster feedback loop, and it prevents bad commits from ever entering the history. Both run in this template.
Versioning should be a byproduct of good commit messages, not a manual step. With Conventional Commits, every feat: or fix: automatically determines the next version, updates the CHANGELOG, and creates a GitHub Release — no human action needed.
Each AI agent reads a different file at startup:
AGENTS.md— universal rules, read by all agentsCLAUDE.md— Claude-specific (read automatically by Claude Code)CODEX.md— Codex-specific (read automatically by OpenAI Codex)
Keeping them separate avoids token waste — each agent only loads what it needs.
Click "Use this template" on GitHub, or clone and re-init:
git clone https://github.com/MaximeFARRE/github-project-template.git my-project
cd my-project
git remote set-url origin https://github.com/YOUR_USERNAME/my-project.gita) Fill STACK.md with your project's tech stack, language, framework, DB, and commands. Agents read this before touching any code.
b) Update pyproject.toml — replace the project name and version:
[project]
name = "your-project-name"version = "0.1.0"c) Update README.md — use README.example.md as a starting point.
d) Fill requirements.txt with your runtime dependencies.
# Create and activate a virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1 # Windowssource .venv/bin/activate # macOS / Linux# Install all dev dependencies (ruff, black, mypy, pytest, pre-commit, semantic-release…)
pip install -r requirements-dev.txt
# Install pre-commit hooks (runs ruff + black + mypy before every commit)
pre-commit installThese settings are required for CI and automated releases to work.
1. Enable write permissions for Actions
Settings → Actions → General → Workflow permissions
→ Select "Read and write permissions"
→ Check "Allow GitHub Actions to create and approve pull requests"
→ Save
2. Protect the main branch
Settings → Branches → Add branch protection rule
→ Branch name pattern: main (or master)
→ ✅ Require a pull request before merging
→ ✅ Require status checks to pass → add Lint & Format and Tests
→ ✅ Do not allow bypassing the above settings
→ Save
This template uses Conventional Commits to drive automatic versioning:
| Commit prefix | Version bump | Example |
|---|---|---|
feat: | minor 0.1.0 → 0.2.0 | feat: add user authentication |
fix: / perf: | patch 0.1.0 → 0.1.1 | fix: prevent duplicate records |
BREAKING CHANGE footer | major 0.1.0 → 1.0.0 | feat!: redesign API |
chore:, docs:, test: | no bump | docs: update README |
On every push to main/master:
- GitHub Actions runs CI (lint + tests)
semantic-release versioncalculates the next version from commitspyproject.tomlis updated, a tag is created,CHANGELOG.mdis generated- A GitHub Release is published automatically
This template ships with ready-to-use instruction files for AI coding agents:
| File | Agent | Key rules |
|---|---|---|
AGENTS.md | All agents | Architecture, code quality, commits, "never do" list |
CLAUDE.md | Claude Code | Same rules, Claude-specific format |
CODEX.md | OpenAI Codex | Same rules + git safe.directory fix for Windows |
STACK.md | All agents | Fill this first — tech stack, commands, conventions |
PROMPTS.md | You | Reusable prompt templates for common tasks |
For Codex on Windows: If Codex can't commit due to a git permission error, add this to
~/.codex/config.toml:setup_commands = ["git config --global --add safe.directory '*'"]
.
├── .github/
│ ├── workflows/
│ │ ├── ci.yml # Lint + type check + tests on every PR and push
│ │ └── release.yml # Automated release on push to main
│ ├── ISSUE_TEMPLATE/
│ ├── pull_request_template.md
│ └── dependabot.yml # Weekly auto-updates for pip + GitHub Actions
├── .githooks/
│ └── pre-commit # Blocks direct commits to main/master (Unix)
├── src/
│ ├── ui/ # Display and interaction only
│ ├── services/ # Business logic
│ └── repositories/ # DB and API access
├── tests/
│ └── conftest.py # Shared pytest fixtures
├── docs/
│ └── ARCHITECTURE.md # Layered architecture rules and examples
├── AGENTS.md # AI agent instructions (universal)
├── CLAUDE.md # Claude-specific instructions + Karpathy principles
├── CODEX.md # Codex-specific instructions + Windows git fix
├── STACK.md # ← Fill this for every project
├── PROMPTS.md # Reusable prompts for AI tasks
├── CONTRIBUTING.md
├── CHANGELOG.md # Auto-generated by semantic-release
├── Makefile # make lint / test / fix / all
├── pyproject.toml # Ruff, black, mypy, pytest, semantic-release config
├── .pre-commit-config.yaml # pre-commit hooks (ruff, black, whitespace…)
├── .editorconfig # Consistent indent/charset across editors
├── requirements.txt # Runtime dependencies
└── requirements-dev.txt # Dev dependencies
MIT — see LICENSE.