⚙️ Software Engineering

AI-Assisted Development

"AI won't replace developers. Developers who use AI will replace those who don't." — Satya Nadella (paraphrased)

The AI Developer Landscape (2024–2025)

flowchart TB subgraph IDE_Copilots ["IDE Copilots"] Copilot[GitHub Copilot] Cursor[Cursor] Codeium[Codeium] Tabnine[Tabnine] Whisperer[Amazon CodeWhisperer] Continue[Continue.dev] end subgraph Coding_Agents ["Coding Agents"] ClaudeCode[Claude Code] Aider[Aider] OpenHands[OpenHands] Devin[Devin] SWE[SWE-agent] AutoGPT[AutoGPT] GPTEng[GPT-Engineer] end subgraph Chat_Assistant ["Chat/Assistant"] ChatGPT[ChatGPT] Claude[Claude] Perplexity[Perplexity] Phind[Phind] Cody[Sourcegraph Cody] end subgraph Specialized ["Specialized"] SQL[SQLCoder] Regex[Regex] Terraform[Terraform] K8s[Kubectl-ai] API[Postbot] end subgraph Local_LLM ["Local LLM"] Ollama[Ollama] LMStudio[LM Studio] GPT4All[GPT4All] llama_cpp[llama.cpp] vLLM[vLLM] TGI[TGI] MLC[MLC-LLM] end %% Styling classDef copilot fill:#e3f2fd,stroke:#1976d2,stroke-width:2px; classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px; classDef chat fill:#e8f5e9,stroke:#388e3c,stroke-width:2px; classDef spec fill:#fff3e0,stroke:#f57c00,stroke-width:2px; classDef local fill:#fce4ec,stroke:#c2185b,stroke-width:2px; class Copilot,Cursor,Codeium,Tabnine,Whisperer,Continue copilot; class ClaudeCode,Aider,OpenHands,Devin,SWE,AutoGPT,GPTEng agent; class ChatGPT,Claude,Perplexity,Phind,Cody chat; class SQL,Regex,Terraform,K8s,API spec; class Ollama,LMStudio,GPT4All,llama_cpp,vLLM,TGI,MLC local;

Mental Models for AI-Assisted Development

1. The "Intern" Model — AI as Junior Developer

Human Does	AI Does
Architecture decisions	Boilerplate, scaffolding
Business logic design	Test generation, refactoring
Code review & verification	Documentation, comments
Security/performance analysis	Exploratory coding, spikes

Rule: Treat AI output like a PR from a junior dev — review, test, verify.

2. The "Exoskeleton" Model — AI as Force Multiplier

Human intent ──▶ AI expands ──▶ Human verifies ──▶ AI refines ──▶ Done
     │              │               │               │
  High-level     Boilerplate     "Does this      Edge cases,
  intent         + tests         look right?"    docs, cleanup

3. The "Dialogue" Model — Iterative Collaboration

You: "Create a REST API for user management"
AI:  *Generates full FastAPI app with CRUD, Pydantic models, tests*
You: "Add pagination and filtering to list endpoint"
AI:  *Updates route, adds query params, updates tests*
You: "Switch to async SQLAlchemy with PostgreSQL"
AI:  *Rewrites models, adds lifespan, updates deps*
You: "Add authentication with JWT"
AI:  *Adds OAuth2, password hashing, dependency injection*

Effective Prompting Patterns

1. Context-Rich Prompts

❌ Bad: "Write a function to parse CSV"
✅ Good: "Write a Python function parse_csv(file_path: Path) -> list[User]
   that reads a CSV with columns: id, email, name, created_at.
   Handle: malformed rows (skip + log), empty files, encoding issues.
   Use csv module (not pandas). Return list of User dataclasses.
   Include type hints and docstring. Write pytest tests."

2. Structured Prompting Framework

Component	Example
Role	"You are a senior Python engineer"
Task	"Refactor this function to use async/await"
Constraints	"Keep public API unchanged; max 50 lines; no external deps"
Context	"This runs in a high-throughput path (10k req/s)"
Output format	"Return only the refactored code + brief explanation"
Verification	"Include pytest tests for the new async behavior"

3. Chain-of-Thought for Complex Tasks

You: "Design a caching layer for this user service. Think step by step:
1. What are the access patterns?
2. What invalidation strategy?
3. What cache topology (local, distributed, hybrid)?
4. How to handle cache stamps/stampedes?
5. What metrics to expose?

Then implement the chosen design with tests."

Verification — The Critical Step

Never commit AI code you haven't verified.

Verification Level	When	How
Syntax/Type	Always	`mypy`, `ruff`, `go vet`, `cargo check`
Unit Tests	Always	Run existing + AI-generated tests
Integration	New features	Testcontainers, contract tests
Security	Auth, input handling	SAST, manual review
Performance	Hot paths	Benchmarks, profiling
Edge Cases	Error handling	Fuzzing, property-based tests

Verification Checklist

# AI Code Review Checklist
- [ ] Code compiles/passes type check
- [ ] All tests pass (existing + new)
- [ ] No hardcoded secrets/credentials
- [ ] Proper error handling (not bare except)
- [ ] Logging appropriate (not PII)
- [ ] No SQL injection / XSS vectors
- [ ] Resource cleanup (connections, files, threads)
- [ ] Timeouts on external calls
- [ ] Pagination on list endpoints
- [ ] Idempotency where needed
- [ ] Observability (logs, metrics, traces)
- [ ] Documentation updated

// AI Code Review Checklist
- [ ] Code compiles/passes type check
- [ ] All tests pass (existing + new)
- [ ] No hardcoded secrets/credentials
- [ ] Proper error handling (not bare except)
- [ ] Logging appropriate (not PII)
- [ ] No SQL injection / XSS vectors
- [ ] Resource cleanup (connections, files, threads)
- [ ] Timeouts on external calls
- [ ] Pagination on list endpoints
- [ ] Idempotency where needed
- [ ] Observability (logs, metrics, traces)
- [ ] Documentation updated

/* AI Code Review Checklist
- [ ] Code compiles/passes type check
- [ ] All tests pass (existing + new)
- [ ] No hardcoded secrets/credentials
- [ ] Proper error handling (not bare except)
- [ ] Logging appropriate (not PII)
- [ ] No SQL injection / XSS vectors
- [ ] Resource cleanup (connections, files, threads)
- [ ] Timeouts on external calls
- [ ] Pagination on list endpoints
- [ ] Idempotency where needed
- [ ] Observability (logs, metrics, traces)
- [ ] Documentation updated
*/

/* AI Code Review Checklist
- [ ] Code compiles/passes type check
- [ ] All tests pass (existing + new)
- [ ] No hardcoded secrets/credentials
- [ ] Proper error handling (not bare except)
- [ ] Logging appropriate (not PII)
- [ ] No SQL injection / XSS vectors
- [ ] Resource cleanup (connections, files, threads)
- [ ] Timeouts on external calls
- [ ] Pagination on list endpoints
- [ ] Idempotency where needed
- [ ] Observability (logs, metrics, traces)
- [ ] Documentation updated
*/

Common AI Failure Modes

Failure Mode	Symptom	Mitigation
Hallucinated APIs	Imports that don't exist	Verify imports; run type checker
Outdated Patterns	Uses deprecated APIs	Specify version in prompt: "FastAPI 0.110+"
Security Blind Spots	Missing auth, SQL injection	Explicit security requirements in prompt
Over-Engineering	200 lines for 10-line task	Constrain: "minimal, <50 lines"
Inconsistent Style	Mixed patterns in codebase	Provide style guide / .editorconfig
Missing Error Handling	Bare try/except, no logging	Require explicit error handling in prompt
Test Gaps	Tests pass but miss edge cases	Mutation testing; property-based tests

Human-AI Workflow Patterns

Pattern 1: Spec → Scaffold → Implement → Verify

1. You write SPEC.md (requirements, API contracts, data models)
2. AI generates project structure + interfaces + test stubs
3. You implement core logic (AI assists per function)
4. AI generates comprehensive tests
5. You run mutation testing → fill gaps
6. AI writes documentation from code

Pattern 2: Refactor with Safety Net

1. Ensure test coverage >90% + mutation score >80%
2. Ask AI: "Refactor this to use strategy pattern"
3. Run tests → they pass
4. Run mutation tests → score maintained
5. Commit with confidence

Pattern 3: Legacy Migration

1. AI analyzes legacy codebase → produces ADR + migration plan
2. AI creates strangler fig adapter + characterization tests
3. Incrementally rewrite modules with AI pair programming
4. AI generates migration scripts + rollback procedures
5. Verify parity with production traffic shadowing

Tool-Specific Tips

GitHub Copilot (in VS Code)

Feature	How to Use
Inline suggestions	`Tab` to accept, `Esc` to dismiss
Chat (`Ctrl+I`)	"Explain this", "Add tests", "Fix bug"
`@workspace`	Context from entire codebase
`@terminal`	Run commands, explain errors
Custom instructions	`.github/copilot-instructions.md`

# .github/copilot-instructions.md
- Use type hints everywhere
- Prefer pytest over unittest
- Use async/await for I/O
- Follow Google-style docstrings
- No bare except clauses
- Log with structlog

// .github/copilot-instructions.md
- Use modern C++ (C++20/23)
- Prefer std::format over iostreams
- Use RAII for resource management
- Prefer std::expected over exceptions for errors
- Use clang-format with LLVM style
- Enable -Weverything -Wno-c++98-compat

// .github/copilot-instructions.md
- Use Java 21+ features (records, patterns, virtual threads)
- Prefer immutable data (records, sealed interfaces)
- Use Project Lombok sparingly
- Prefer Streams over loops
- Use JUnit 5 + AssertJ for tests
- Follow Google Java Style Guide

// .github/copilot-instructions.md
- Use C# 12+ features (primary ctors, collection expressions)
- Prefer readonly/immutable types
- Use File-scoped namespaces
- Use pattern matching extensively
- Use nullable reference types
- Follow Microsoft C# Coding Conventions

Team Adoption Guidelines

Phase	Focus	Guardrails
1. Pilot	2–3 volunteers, low-risk code	No production AI code without review
2. Expand	Team-wide, standardize prompts	Shared prompt library; approved tools list
3. Integrate	CI gates for AI code	Mutation test gate; security scan
4. Govern	Metrics, cost, policy	Token budgets; data privacy; model approval

Team Prompt Library

# team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

Team Adoption Guidelines

Phase	Focus	Guardrails
1. Pilot	2–3 volunteers, low-risk code	No production AI code without review
2. Expand	Team-wide, standardize prompts	Shared prompt library; approved tools list
3. Integrate	CI gates for AI code	Mutation test gate; security scan
4. Govern	Metrics, cost, policy	Token budgets; data privacy; model approval

Team Prompt Library

# team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

Team Adoption Guidelines

Phase	Focus	Guardrails
1. Pilot	2–3 volunteers, low-risk code	No production AI code without review
2. Expand	Team-wide, standardize prompts	Shared prompt library; approved tools list
3. Integrate	CI gates for AI code	Mutation test gate; security scan
4. Govern	Metrics, cost, policy	Token budgets; data privacy; model approval

Team Prompt Library

# team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

Team Adoption Guidelines

Phase	Focus	Guardrails
1. Pilot	2–3 volunteers, low-risk code	No production AI code without review
2. Expand	Team-wide, standardize prompts	Shared prompt library; approved tools list
3. Integrate	CI gates for AI code	Mutation test gate; security scan
4. Govern	Metrics, cost, policy	Token budgets; data privacy; model approval

Team Prompt Library

# team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.

// team-prompts.md

## New Feature
> You are a senior {language} engineer. Implement {feature} 
> following our conventions: {link-to-conventions}. 
> Requirements: {requirements}. 
> Output: implementation + tests + brief explanation.

## Refactor
> Refactor {file/function} to {pattern/goal}. 
> Constraints: {preserve API, <50 lines, no new deps}.
> Run tests after each step.

## Debug
> This test fails: {error}. 
> Context: {code snippet}. 
> Hypothesize root cause and fix.