Decoupling & Monorepos

• Datasets: Always keep flat data files in their own repository. Version them via GitHub Releases. Do not load data from personal local paths.
• Models & Code: Monorepos are preferred for projects with tightly coupled modules (e.g., an ETL pipeline, backend, and frontend).

Repository Hygiene

New repositories should be initialized from a sensible default template (ideally via Cookiecutter). Note: We should create standard templates for project configuration files (e.g., pyproject.toml, bunfig.toml) to ensure these defaults are applied consistently. Every repository must have:

• README.md with purpose, installation, and usage instructions.
• LICENSE? (good to have from the start for when the repo goes public).
• .gitignore appropriate for the language.
• Dependency lockfile committed (uv.lock, bun.lockb).
• AGENTS.md file if a coding agent is being used on the project.

Security & Secrets Management

• Never commit secrets: Ensure .env and *.local files are in your .gitignore from day one.
• Secret Scanning: Ensure secret scanning (e.g., Gitleaks as a pre-commit hook and via GitHub Actions, or GitHub Advanced Security) is enabled to catch accidental leaks.
• Supply Chain Security: Always commit dependency lockfiles (uv.lock, bun.lockb) to guarantee reproducible builds and verify package hashes. Enable automated dependency vulnerability scanning (e.g., Dependabot or Renovate) to catch CVEs in third-party libraries. Protect against supply chain attacks by enforcing a delay on fresh packages: configure exclude-newer = "7 days" in pyproject.toml for uv, and minimumReleaseAge = 604800 in bunfig.toml for Bun.

Python

• Manager: Use uv for faster, deterministic builds.
• Dependencies: Maintain uv.lock locally. The generation of requirements.txt (for container builds or downstream consumption) should be automated via CI/CD.
• Linting/Formatting: Use Ruff.
• Types: Provide type hints for public functions (Pydantic is recommended for data structures). We aim for ty as our primary type checker, with Pyright or Pyrefly as fallbacks. For messy, purely dynamic data (like external JSON), use Pydantic for runtime validation rather than writing brittle static types.
• Testing: Use pytest as the standard test runner.