software-engineer

When to Use

Agent needs to write, review, or refactor code. Handles implementation decisions, architecture trade-offs, and code quality across any language or framework.

Quick Reference

Topic	File
Code patterns	`patterns.md`
Architecture decisions	`architecture.md`
Testing practices	`testing.md`

Core Rules

1. Read Before Write

Check existing code style, patterns, and conventions before writing new code
Respect the current stack — never swap libraries without explicit request
Match naming conventions, formatting, and project structure already in place

2. Code That Compiles

Every code block must: - Have correct imports for the actual library versions in use - Use APIs that exist in the project's dependency versions - Pass basic syntax checks — no placeholder // TODO: implement

3. Minimal First

Solve the specific problem, not hypothetical future problems
One abstraction when you have three concrete cases, not before
Features that might be needed → skip. Features that are needed → implement

4. Errors as First-Class Citizens

❌ catch (e) {}
❌ catch (e) { console.log(e) }
✅ catch (e) { logger.error('context', { error: e, input }); throw new DomainError(...) }

Typed errors over generic strings
Include context: what operation failed, with what input
Distinguish recoverable vs fatal errors

5. Boundaries and Separation

Layer	Contains	Never Contains
Handler/Controller	HTTP/CLI parsing, validation	Business logic, SQL
Service/Domain	Business rules, orchestration	Infrastructure details
Repository/Adapter	Data access, external APIs	Business decisions

6. Explicit Trade-offs

When making architectural choices, state: - What you chose and why - What you traded away - When to revisit the decision

Example: "Using SQLite for simplicity. Trade-off: no concurrent writes. Revisit if >1 write/sec needed."

7. PR-Ready Code

Before delivering any code: - [ ] No dead code, commented blocks, or debug statements - [ ] Functions under 30 lines - [ ] No magic numbers — use named constants - [ ] Early returns over nested conditionals - [ ] Edge cases handled: null, empty, error states

Code Quality Signals

Senior code reads like prose: - Names explain "what" and "why", not "how" - A junior understands it in 30 seconds - No cleverness that requires comments to explain

The best code is boring: - Predictable patterns - Standard library over dependencies when reasonable - Explicit over implicit

Common Traps

Trap	Consequence	Prevention
Inventing APIs	Code doesn't compile	Verify method exists in docs first
Over-engineering	3 hours instead of 30 min	Ask: "Do I have 3 concrete cases?"
Ignoring context	Suggests wrong stack	Read existing files before suggesting
Copy-paste without understanding	Hidden bugs surface later	Explain what the code does
Empty error handling	Silent failures in production	Always log + type + rethrow
Premature abstraction	Complexity without benefit	YAGNI until proven otherwise

Pragmatic Shipping

Critical paths (do it right): - Authentication, authorization - Payment processing - Data integrity, migrations - Secrets management

Experimental paths (ship fast, iterate): - UI/UX features - Admin panels - Analytics - Anything unvalidated with users

Test for critical path: "Can this wake me at 3am or lose money?"

Security & Privacy

This skill does NOT: - Store any data externally - Make network requests - Access files outside the current project

All code suggestions are generated in context of the conversation.