Introduction
Opinionated engineering playbook for modern software teams.
Personal software development playbook. Defines how I build software — from branching strategy to code conventions.
Purpose: Every new project reads this repo first and follows these standards. No reinventing the wheel.
Table of Contents
How to Use
For Claude Code / AI Assistants
Add this to your project's CLAUDE.md:
## Development Process
Follow the playbook at https://github.com/tansuasici/dev-playbook
Read all files under process/ and conventions/ before starting work.
Apply templates/ when creating issues and PRs.Or at the start of a session:
"Read the dev-playbook repo first, then work on this project."
For Yourself
Bookmark this repo. Before starting a new project, run through checklists/new-project-setup.md.
Structure
dev-playbook/
├── process/ ← How work flows
│ ├── branching.md Branch strategy and naming
│ ├── commits.md Conventional Commits rules
│ ├── issues.md Issue creation and lifecycle
│ ├── pull-requests.md PR process and review outcomes
│ ├── board-workflow.md Kanban board flow
│ ├── ci-cd.md CI/CD pipeline standards
│ ├── code-review.md How to review code
│ ├── incident-response.md What to do when production breaks
│ └── dependency-management.md Adding, updating, removing deps
├── conventions/ ← How code is written
│ ├── dotnet.md .NET / C# standards
│ ├── nextjs.md Next.js / React standards
│ ├── python.md Python standards
│ ├── naming.md Naming conventions (all languages)
│ ├── api-design.md REST API design standards
│ ├── api-error-format.md Standard error response format (RFC 7807)
│ ├── error-handling.md Exception handling patterns
│ ├── testing.md Testing philosophy and practices
│ ├── logging.md Logging levels, structured logging
│ ├── observability.md Metrics, tracing, alerting, health checks
│ ├── performance.md Response budgets, caching, N+1 prevention
│ ├── docker.md Dockerfile and Compose best practices
│ ├── git-hooks.md Pre-commit hooks setup
│ ├── environment-management.md Environment config, feature flags, secrets
│ ├── documentation.md README template, API docs, inline comments
│ ├── accessibility.md WCAG 2.1 AA, keyboard nav, screen readers
│ └── i18n.md Internationalization and localization
├── architecture/ ← How systems are designed
│ ├── decisions.md Architecture Decision Records (ADR)
│ ├── multi-tenancy.md Multi-tenancy with RLS
│ ├── security.md Security standards and OWASP
│ └── database.md Schema design, migrations, indexing
├── templates/ ← Copy-paste templates
│ ├── issue-feature.md Feature request template
│ ├── issue-bug.md Bug report template
│ ├── pull-request.md PR template
│ └── claude-md-starter.md CLAUDE.md starter for new projects
├── checklists/ ← Step-by-step checklists
│ ├── new-project-setup.md New project bootstrap
│ ├── pre-merge.md Pre-merge review
│ ├── release.md Release process
│ ├── security-audit.md Periodic security audit
│ └── onboarding.md New developer onboarding
├── .github/ ← GitHub integration
│ ├── ISSUE_TEMPLATE/ Native issue templates (bug, feature)
│ ├── PULL_REQUEST_TEMPLATE.md Native PR template
│ └── workflows/lint.yml Markdown lint + broken link check
├── labels.yml ← Standard GitHub label set
├── CONTRIBUTING.md ← How to contribute
├── CODE_OF_CONDUCT.md ← Community standards
├── CHANGELOG.md ← Version history
├── VERSION ← Current version (semver)
└── LICENSE ← MIT LicenseQuick Reference
Principles
- Every change has an issue — No ad-hoc work. Track everything.
- Every issue has a branch — Never push directly to main.
- Every branch has a PR — Even solo. PRs are your audit trail.
- CI must pass before merge — No exceptions. Tests are not optional.
- Keep commits atomic — One concern per commit. Easy to bisect, easy to revert.
- Simplicity over cleverness — Make it work, make it right, then make it fast.
Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines.
License
This project is licensed under the MIT License.