Penguin Bootstrapped Startup Development
A pragmatic Python development skill for bootstrapped startups that emphasizes unreasonable effectiveness: achieving 3x the capability with 1/3 of the complexity.
Philosophy
This skill guides you to build elegant, maintainable Python code optimized for bootstrapped startup constraints. Every decision should favor simplicity and effectiveness over premature optimization or over-engineering.
Core Principles
Apply the heuristic: **3x capability from 1/3 complexity**. Build things that are unreasonably effective for bootstrapped environments.
Instructions
When writing Python code for this project, follow these guidelines:
1. Pythonic Practices
Write elegant, Pythonic code that prioritizes readability and maintainabilityFollow PEP 8 guidelines strictly - use Ruff as your primary linter and formatterChoose explicit code over implicit shortcuts - clarity beats brevityKeep the Zen of Python principles in mind for all design decisionsPrefer standard library solutions over external dependencies when reasonable2. Modular Design
Apply Single Responsibility Principle - each module/file should have one clear purposeBuild reusable components through functions and classesFavor composition over inheritance for flexibilityOrganize code into logical packages and modules with clear boundariesKeep modules focused and cohesive3. Code Quality Requirements
**Type Annotations:**
Add comprehensive type annotations to ALL functions, methods, and class membersUse the most specific types possible (not just `Any` or overly broad types)Leverage `typing` module features: `Optional`, `Union`, `List`, `Dict`, etc.**Documentation:**
Write detailed Google-style docstrings for all functions, methods, and classesExplain purpose, parameters, return values, and exceptions raisedInclude usage examples in docstrings where helpfulDocument non-obvious implementation decisions**Testing:**
Aim for 90%+ test coverage using `pytest`Test both happy paths and edge casesWrite clear, descriptive test names that explain what's being testedUse fixtures effectively to reduce test code duplicationInclude integration tests for critical workflows**Exception Handling:**
Use specific exception types, never bare `except:` clausesProvide informative, actionable error messagesCreate custom exception classes for domain-specific errorsHandle exceptions gracefully with appropriate recovery or cleanupLog exceptions with context before re-raising or handling**Logging:**
Use Python's `logging` module for all logging needsLog important events, warnings, and errors at appropriate levelsInclude relevant context in log messages (IDs, values, states)Avoid excessive logging that creates noise4. Bootstrapped Startup Constraints
Prioritize features that deliver immediate user valueBuild the simplest solution that works, then iterateAvoid premature optimization - profile before optimizingChoose battle-tested libraries over cutting-edge but unstable onesMake pragmatic trade-offs that favor shipping over perfectionDocument technical debt for future consideration, but don't let it block progress5. Code Review Checklist
Before considering code complete, verify:
[ ] All functions have type annotations[ ] All public APIs have Google-style docstrings[ ] Test coverage meets 90% threshold[ ] Ruff linting passes with no warnings[ ] No bare `except` clauses[ ] Logging is present for key operations[ ] Code follows single responsibility principle[ ] Solution is as simple as possible (but no simpler)Example
```python
from typing import Optional
import logging
logger = logging.getLogger(__name__)
class UserNotFoundError(Exception):
"""Raised when a user cannot be found in the database."""
pass
def get_user_email(user_id: int) -> str:
"""
Retrieve the email address for a given user ID.
Args:
user_id: The unique identifier for the user.
Returns:
The user's email address as a string.
Raises:
UserNotFoundError: If no user exists with the given ID.
Example:
>>> email = get_user_email(123)
>>> print(email)
'[email protected]'
"""
logger.info(f"Fetching email for user_id={user_id}")
user = db.query(User).filter(User.id == user_id).first()
if user is None:
logger.error(f"User not found: user_id={user_id}")
raise UserNotFoundError(f"No user found with ID {user_id}")
return user.email
```
Notes
This is optimized for bootstrapped startup environments where speed and pragmatism matterThe 3x/1/3 heuristic should guide all architectural decisionsWhen in doubt, choose the simpler, more maintainable solutionTechnical excellence serves business goals, not the other way around