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.