---
type: reference
title: SDLC and Tooling Best Practices
description: Current best practices for the software development life cycle - git, CI/CD, testing, review, versioning, and dev environments.
tags:
  - sdlc
  - git
  - ci-cd
  - testing
  - tooling
  - unverified
timestamp: 2026-08-11
---
verified: 2026-08-28

# SDLC and Tooling Best Practices

This page distills current (2025/2026) best practices for running a software project. Use it when you bootstrap a new repository or when you review an existing one.

## Git Branching

Trunk-based development dominates. Teams use short-lived feature branches and merge into a single shared `main` branch. Feature flags hide incomplete features. This replaces older models such as GitFlow for most projects.

Use GitHub Flow as the default for new projects. Create a branch for each change. Open a pull request for every change. Merge the change after review. Deploy from `main` at any time.

The rule `main` must stay deployable at all times.

## Continuous Integration and Delivery

GitHub Actions is the most common CI/CD platform. Workflows live in `.github/workflows/`. A standard workflow follows this order: lint, test, build, deploy.

Use these patterns:

* Run one pipeline for pull request checks.
* Run a separate pipeline for `main` branch deployments.
* Use matrix builds to test multiple tool versions.
* Cache dependencies between runs.
* Split shared steps into reusable workflows.

## Testing

Follow the testing pyramid. Write many unit tests. Write fewer integration tests. Write the fewest end-to-end tests.

| Layer | Speed | Focus |
|-------|-------|-------|
| Unit | Fast | Isolated functions and modules |
| Integration | Medium | Service-to-service interaction |
| End-to-end | Slow | Complete user journeys |

Aim for roughly ten unit tests per integration test, and ten integration tests per end-to-end test.

## Code Review

Reduce review friction with these tools:

* Pull request templates for consistency.
* `CODEOWNERS` to assign reviewers by path.
* Required review before merge.
* Pre-commit hooks for lint and format checks.

## Semantic Versioning

Version numbers follow the `MAJOR.MINOR.PATCH` format.

* MAJOR changes when an API breaks compatibility.
* MINOR changes when features stay compatible.
* PATCH changes fix bugs in a compatible way.

Pre-release versions use `-alpha`, `-beta`, or `-rc` suffixes.

## Development Environments

Use `mise` to manage tool versions, environment variables, and named tasks in one `mise.toml` file. `mise` replaces the separate tools asdf and direnv, and it replaces a `Makefile` for tasks.

Use Dev Containers for reproducible environments. The Dev Container Specification uses `.devcontainer/devcontainer.json`. It works with VS Code, Codespaces, and the container CLI.

## Per-Ecosystem Variations

| Ecosystem | Manifest | Package manager | Test command |
|-----------|----------|-----------------|--------------|
| Node/JS | `package.json` | npm, pnpm, or Bun | `vitest` / `jest` |
| Python | `pyproject.toml` | uv | `pytest` |
| Rust | `Cargo.toml` | cargo | `cargo test` |
| Go | `go.mod` | go modules | `go test ./...` |
| Terraform | `.tf` files | providers | `terraform validate` |

Put `AGENTS.md` instructions for each ecosystem in the [Agent Instruction Files](agents-files.md) page.

## Monorepos

Use a workspace tool for monorepos:

* Turborepo or Nx for JavaScript/TypeScript.
* pnpm workspaces for dependency management.
* Cargo workspaces for Rust.
* Go workspaces for Go modules.
* uv workspaces for Python.

Put a nested `AGENTS.md` in each package when a monorepo has multiple packages.

## Citations

* [Trunk-Based Development](https://trunk-based-development.com/)
* [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
* [GitHub Actions](https://docs.github.com/en/actions)
* [Microsoft Engineering Playbook](https://microsoft.github.io/code-with-engineering-playbook/)
* [semver.org](https://semver.org/)
* [mise](https://mise.jdx.dev/)
* [Dev Container Specification](https://containers.dev/)

## See Also

* [Agent Instruction Files](agents-files.md)
* [Language and Framework Stacks](languages/index.md)
* [Infrastructure and Cloud](infra/index.md)