Dev Test — Development & Testing SOP

Overview

A structured workflow for implementing code changes with quality built in. Covers the full cycle from understanding the codebase to having a verified, reviewable diff.

Use cases: Bug fixes, feature development, refactoring, open-source contributions, any code change that needs to be correct and maintainable.

Workflow

Phase 1: Study Before Coding

Never write code before understanding the context. This phase prevents wasted effort and bad designs.

1a. Understand the project conventions

Check for and read these files (if they exist):

• - CONTRIBUTING.md — contribution guidelines
• INLINECODE1 — formatting rules
• INLINECODE2 / package.json / Makefile — project config, linting, formatting
• INLINECODE5 / .flake8 / .eslintrc — code style rules

1b. Study the area of change

• - Read the module(s) you'll be modifying
• Trace the execution path around the bug/feature
• Understand data flow: what goes in, what comes out
• Note dependencies: what other modules interact with this code

1c. Study existing tests

• - Find the test directory structure: tests/, __tests__/, INLINECODE10
• Note the test framework: pytest, jest, go test, JUnit, etc.
• Study naming conventions: test_feature.py, feature.test.ts, INLINECODE13
• Note fixture/setup patterns used
• Check for test utilities, factories, or mocks

1d. Draft a mental model

Before writing code, articulate:

• - What needs to change (specific behavior)
• Where in the code (files, functions, classes)
• How you'll change it (approach)
• What could go wrong (edge cases, regressions)

Phase 2: Implement

Core principles

1. 1. Minimal, focused changes

- Fix the bug / add the feature. Nothing else. - Avoid unrelated formatting changes, import reordering, or drive-by refactors. - If you spot something else to fix, note it for a separate commit/PR.

1. 2. Follow existing patterns

- Match the codebase's style, not your preferred style - Use the same naming conventions, indentation, comment style - If the project uses snake_case, don't introduce INLINECODE15

1. 3. Add comments for non-obvious logic

- "Why" comments, not "what" comments - Explain trade-offs, workarounds, and intentional decisions

1. 4. Design for quality

| Principle | Meaning | Example |
|-----------|---------|---------|
| Defense-in-depth | Layer multiple protections | Validate input at API + service + DB layer |
| Backward compatibility | Don't break existing behavior | Add new params with defaults |
| Graceful degradation | Handle missing features | Platform-specific code falls back safely |
| Extensibility | Prefer composable designs | Plugin/middleware over hardcoded switch |
| Single responsibility | One function = one job | Extract logic instead of growing functions |

Phase 3: Write Tests

Test categories (implement in order)

1. 1. Fix verification — prove the bug is fixed / feature works

CODEBLOCK0

1. 2. Edge cases — boundary conditions

CODEBLOCK1

1. 3. Error handling — invalid inputs, failure paths

CODEBLOCK2

1. 4. Regression — existing behavior preserved

CODEBLOCK3

Test writing guidelines

• - One assertion per test (ideally) — makes failures easy to diagnose
• Descriptive names — test_oauth_token_refreshes_when_expired not INLINECODE17
• Arrange-Act-Assert pattern:

  def test_feature():
      # Arrange
      input_data = create_test_data()

      # Act
      result = feature(input_data)

      # Assert
      assert result.status == "success"
  

• - Use fixtures for reusable setup
• Mock external dependencies — network calls, file system, databases
• Test behavior, not implementation — don't assert on internal state

Phase 4: Run Tests

Progressive testing strategy

CODEBLOCK5

Handling test results

Scenario	Action
All pass ✅	Proceed to diff review
Your tests fail

Fix the code, re-run | | Pre-existing failures | Note them, don't fix (out of scope) | | Flaky tests (pass/fail randomly) | Run 3x to confirm flakiness, note in PR | | Tests you can't run (need env/infra) | Note in PR, explain what you tested manually |

Phase 5: Review the Diff

Before committing, review every line of your diff.

CODEBLOCK6

Diff review checklist

• - [ ] Every change is intentional (no accidental edits)
• [ ] No debug prints, TODO comments, or temporary code left in
• [ ] No secrets, tokens, or personal paths hardcoded
• [ ] No unrelated formatting changes
• [ ] All new functions/classes have appropriate docstrings/comments
• [ ] Test coverage looks adequate for the changes
• [ ] File additions are in the right directories

Phase 6: Commit

CODEBLOCK7

Commit message format

CODEBLOCK8

Type	When
INLINECODE18	Bug fix
INLINECODE19

New feature |
| refactor | Code restructure (no behavior change) |
| test | Adding/fixing tests only |
| docs | Documentation changes only |
| chore | Build/tooling/dependency changes |

Output

• - Committed code changes + tests on feature branch
• All tests passing
• Clean, reviewable diff

Tips

• - This skill works standalone for any development task.
• In a contribution pipeline, it follows repo-setup and feeds into pr-pilot.
• For large features, repeat Phase 2-5 in small increments rather than one big change.
• When pair-programming with AI: have the AI study the codebase (Phase 1) before asking it to implement anything.