I got tired of setting up new Python projects from scratch every time. It's inefficient. So I created this template with all the best tools already configured. It evolved into a showcase of modern Python development and some lessons I've learned along the way. oh and tools, libraries, and frameworks. and lots of generated ideas written by AI.
It has all the cutting-edge tools - Ruff, Pyright, UV, running tests, generating documentation, and CI/CD, and more - working together without conflicts. It includes deep Cursor integration for AI coding, solid I/O practices, automated documentation, and CI/CD.
What started as solving a personal frustration became an exploration of how AI and good tooling can make coding more efficient and enjoyable.
Setting up a new project environment is time-consuming. Each time I start something new, I spend hours configuring linters, formatters, test frameworks, documentation, CI/CD pipelines. This repetitive work takes away from actual development.
With AI helping me manage multiple projects, this setup overhead became an even bigger bottleneck. I needed to reduce this friction to focus on building meaningful features.
I wanted everything preconfigured with best practices ready to go. A template that works immediately. Something that integrates these Python tools - Ruff, Pyright, UV, pytest - without configuration conflicts. Something to handle the boilerplate so I can focus on development.
That's exactly what this project is - a starting point that eliminates setup overhead so you can focus on coding.
I haven't been coding for very long. Before AI tools, I struggled with the boilerplate required for complex applications like web apps. When ChatGPT 3.5 was released, it significantly improved my workflow. I could build a simple web app much faster.
Since then, the development landscape has expanded rapidly. Not just AI tools but libraries for almost every use case. Each new project presented a learning curve - too many tools, frameworks, and best practices to keep up with. I spent more time on configuration than coding, and when I found working solutions, I reused them across projects.
Cursor transformed my development process. The AI-assisted coding increased my productivity substantially. I initiated many projects and developed at a much faster pace, though I still encountered errors requiring manual fixes.
My experience with AI coding has evolved - from early ChatGPT to GitHub Copilot, and now to Cursor with Claude. With the newest agents, we're entering a new phase where human-AI collaboration is more integrated.
What's notable is that AI generated all this project code - including this documentation. It demonstrates how far these assistants have progressed, enabling the creation of production-ready projects with reduced human input.
An important insight I've gained: familiarizing yourself with documentation for tools you use with AI significantly improves results. While AI models understand code generally, they benefit from specific tool knowledge.
When I review documentation and incorporate those specific terms in my prompts, the code quality improves noticeably. For example, after examining Ruff documentation and learning rule codes like E501 or F401, I could direct the AI to address specific linting issues more effectively.
This creates an effective cycle:
- Review documentation for key concepts and terminology
- Use those terms when prompting the AI
- Get better results that follow tool-specific best practices
- Learn from the AI's improved responses
- Continue with enhanced understanding
You don't need comprehensive knowledge - just enough familiarity to guide the AI properly. It's similar to learning key phrases for travel - basic knowledge improves the experience considerably.
As AI tools evolved into agents, my development approach changed significantly. Documentation and code readability became priorities. It makes more sense to have an agent handle repetitive tasks like linting and CI problems rather than doing them manually. I can instruct the agent to document, format, and handle routine tasks.
My workflow has shifted considerably. Previously I spent most of my time writing code with less time reviewing. Now this ratio has reversed - I primarily review AI-generated code, provide feedback, and refine prompts. (The exact numbers aren't measured, but the change has been substantial.)
Coding has become a collaborative process with AI. I focus on architecture and quality control while AI handles implementation details. This has increased productivity and improved project quality as I can devote more attention to design patterns, edge cases, and user experience.
This shift is meaningful - AI can manage code readability and documentation. With proper configuration, AI handles details while I focus on higher-level problems. This represents a new development paradigm: humans handling strategic aspects while AI manages technical implementation.
One tool that has been particularly valuable is Sequential Thinking MCP. For serious AI development, it's essential. It enables AI to break down complex problems into manageable steps, consider each carefully, and revise thinking when necessary.
The results are significantly better than standard prompting - more thorough, accurate, and reliable. For anyone working with AI agents, Sequential Thinking provides a notable improvement in solution quality.
I've explored other approaches, such as the Cline Memory Bank system. It uses structured documentation as AI "memory" - files like projectbrief.md, productContext.md, and activeContext.md.
Initially, it showed promise - sometimes performing better than Cursor. The structured context approach worked well for smaller projects. However, as project complexity increased, limitations became apparent. The system became less reliable - the AI would miss important details despite carefully maintained documentation.
The core issue is that context quality matters more than size. On complex projects, I even tried switching from Claude to Gemini for its larger context window, but this didn't resolve the problems.
In practical development, you don't need to track everything - just the general structure. When specific questions arise, developers typically check the code rather than documentation (which is often outdated).
Having AI reference documentation during coding isn't the optimal solution. Documentation is important, but there are more efficient ways to maintain it, as demonstrated in this repository.
The pyproject.toml configuration and CI workflow automate documentation checks, coverage reporting, and quality metrics. This ensures documentation remains accurate without manual effort. It works particularly well when AI generates the documentation.
Code is primary - and this project template addresses the problem effectively:
- AI-generated documentation alongside code
- Clean code through automated tooling
- Comprehensive quality checks
The process may be somewhat slower at times, and AI occasionally produces errors, but the configured tools provide a safety net. The components work together coherently - something the Memory Bank approach couldn't achieve.
This approach has certain trade-offs. It can be slower, and I've disabled some features in my projects to optimize performance. The key insight is that if something impedes progress, you can simply disable it.
I've wanted a versatile project template that handles boilerplate while incorporating modern tools. The challenge is that tools like Pyright, Ruff, UV, and pyproject.toml configurations can be difficult to integrate correctly. Without proper configuration, IDE performance suffers.
This is the result: a template designed for efficiency and reliability while maintaining functionality. The Python Starting Project combines best practices for configuration, logging, code quality, and project structure.
I plan to create branches with customized configurations - enabling or disabling specific features for different requirements. For now, this release includes everything I've found valuable in my development work.
Contributions, suggestions, and improvements are welcome. If you want to enhance it or adapt it for other languages, please contribute. Collaborative efforts will make this more useful for developers.
By the way, I've noticed the AI tends to make my writing more formal than it naturally is. I'm relatively young and typically write more casually, but I've allowed the AI to maintain a somewhat professional tone as it suits this project. There's a real person behind this documentation.