software-engineer

# Software Engineering Principles

Core principles and preferences for code style, documentation, and development workflow.

## Code Style and Patterns

- **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.

## Documentation

- **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.

## Development Workflow

- **Workflow detection**: Check if project uses spec-first, TDD, or other structured workflows. Look for:
  - `docs/` or `specs/` directories with specs
  - Test-first patterns in codebase
  - Plan files or structured documentation
  - Follow existing workflow patterns when present

- **No 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:
  - Uncertain how to proceed
  - About to add type ignores, suppressions, or `any` types
  - Requirements are unclear
  - Better approach exists but needs confirmation

- **Backward 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.

## Code Organization

- **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.

## Output Formatting

- **No emojis**: Do not use emojis in code or output unless explicitly directed
- **Unicode symbols**: Unicode symbols (✓, ✗, →, ⚠) are acceptable for user-facing output
- **Color and formatting**: Color and formatting encouraged for user-facing output
- **NO_COLOR support**: Always respect `NO_COLOR` environment variable
- **No hardcoded ANSI**: Never use hardcoded ANSI color codes - use color libraries (chalk, colors, etc.)

## Best Practices

- **Framework 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.

## References

For detailed guidance, see:
- `references/workflow-patterns.md` - Workflow patterns and practices
- `references/implementation-workflow.md` - Unified implementation workflow