Menu
Core software engineering principles for code style, documentation, and development workflow. Applies when editing code, working in software repositories, or performing software development tasks.
| name | software-engineer |
| description | Core software engineering principles for code style, documentation, and development workflow. Applies when editing code, working in software repositories, or performing software development tasks. |
Core principles and preferences for code style, documentation, and development workflow.
Avoid unnecessary comments: Code should be self-documenting. Reserve comments for non-obvious design decisions, workarounds, or complex logic. Avoid comments that restate what the code obviously does.
Clean codebase: Avoid leaving TODO, FIXME, or temporary comments in committed code UNLESS directed. Either implement the feature, create an issue, or remove the comment. Ignore existing ones.
Self-documenting code: Prefer clear naming and structure over explanatory comments. Method, class, and member documentation should use language/stack best practices. Don't add useless inline comments next to statements UNLESS they explain confusing or complex behaviour.
Concise and useful: Documentation should be informative but not verbose. READMEs should focus on essential information without unnecessary elaboration.
Structure over verbosity: Prefer well-organized, scannable documentation with clear headings over long paragraphs. Use short examples to illustrate concepts.
Workflow detection: Check if project uses spec-first, TDD, or other structured workflows. Look for:
docs/ or specs/ directories with specsNo git modifications: Do not use Git commands that modify the repository state (such as git add, git commit, git push) UNLESS directed. Focus on code edits directly. Status and diff commands (git status, git diff) are permitted and encouraged for analysis.
Fact-based approach: Do not hallucinate or assume. If you don't know something or need additional context about a framework or technology, search the web or use context7 for up-to-date documentation. If clarification is needed, ask the user before making changes.
Constructive disagreement: Do not just accept user direction if a better alternative exists. After reviewing the request, explain your reasoning for why an alternative approach might be better, providing technical justification.
Stop and ask: Stop and ask user if:
any typesBackward compatibility: Only consider backward compatibility for public-facing interfaces (APIs, libraries). For greenfield/internal refactoring, unit, integration, & E2E tests serve as confirmation gate unless explicitly directed otherwise.
Single responsibility: Components and functions should have a single, clear purpose. Organize code into logical directories with clear separation of concerns.
Consistent patterns: Follow established patterns in the codebase. When introducing new patterns, ensure they align with existing architecture and conventions.
Automation and efficiency: Prefer automated solutions and efficient workflows. Look for opportunities to reduce manual work and improve developer experience.
NO_COLOR environment variableFramework conventions: Follow framework and language best practices. Use framework features as intended rather than working around them.
Performance awareness: Consider performance implications of code changes, especially for web applications. Prefer static generation and minimal JavaScript when possible.
Accessibility: Ensure code is accessible by default. Use semantic HTML, proper ARIA attributes, and test keyboard navigation.
For detailed guidance, see:
references/workflow-patterns.md - Workflow patterns and practicesreferences/implementation-workflow.md - Unified implementation workflowManage Git commits using conventional commit format with atomic staging. Always generate plain git commands before running them and offer to let the user run them manually.
Create AGENTS.md files for project-specific inline rules. Use when adding small, project-specific instructions that should be committed in repos.
Media processing utilities for images, audio, and video using FFmpeg and ImageMagick. Use when working with media conversion, optimization, or batch processing tasks.
Python development guidelines and best practices. Use when working with Python code.
Build robust backend systems with modern technologies (Node.js, Python, Go, Rust), frameworks (NestJS, FastAPI, Django), databases (PostgreSQL, MongoDB, Redis), APIs (REST, GraphQL, gRPC), authentication (OAuth 2.1, JWT), testing strategies, security best practices (OWASP Top 10), performance optimization, scalability patterns (microservices, caching, sharding), DevOps practices (Docker, Kubernetes, CI/CD), and monitoring. Use when designing APIs, implementing authentication, optimizing database queries, setting up CI/CD pipelines, handling security vulnerabilities, building microservices, or developing production-ready backend systems.
Build command-line interfaces with async-first design, composable commands, and proper output formatting. Use when creating CLI tools, commands, or interactive terminal applications.