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
• .editorconfig — formatting rules
• pyproject.toml / package.json / Makefile — project config, linting, formatting
• tox.ini / .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__/, test/
• Note the test framework: pytest, jest, go test, JUnit, etc.
• Study naming conventions: test_feature.py, feature.test.ts, feature_test.go
• 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. 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. 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 camelCase

1. Add comments for non-obvious logic
• "Why" comments, not "what" comments
• Explain trade-offs, workarounds, and intentional decisions

1. 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. Fix verification — prove the bug is fixed / feature works

```

test_feature_handles_null_input() # The exact scenario from the issue

```

1. Edge cases — boundary conditions

```

test_feature_with_empty_string()

test_feature_with_max_length_input()

test_feature_with_special_characters()

```

1. Error handling — invalid inputs, failure paths

```

test_feature_raises_on_invalid_type()

test_feature_returns_none_on_missing_key()

```

1. Regression — existing behavior preserved

```

test_existing_behavior_unchanged()

test_other_module_still_works()

```

Test writing guidelines

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

```python

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

# 1. Run only your new/modified tests first (fast feedback)
python -m pytest tests/test_my_feature.py -v --tb=short
# or: npm test -- --testPathPattern=my_feature
# or: go test ./pkg/my_feature/... -v

# 2. Run the full test module/directory
python -m pytest tests/ -v --tb=short

# 3. Run the entire test suite (before committing)
python -m pytest --tb=short
# or: npm test
# or: go test ./...

Handling test results

Phase 5: Review the Diff

Before committing, review every line of your diff.

# Overview of what changed
git diff --stat

# Full diff
git diff

# If already staged
git diff --cached

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

# Stage specific files (never use `git add .`)
git add path/to/modified_file.py
git add tests/test_new_feature.py

# Verify staged files
git diff --cached --stat

# Commit with conventional message
git commit -m "fix(module): short description of what was fixed

Longer explanation of why, if non-obvious.

Addresses #issue_number"

Commit message format

{type}({scope}): {concise description}

{body: what and why, not how}

{footer: issue refs, test results, breaking 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.