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

Implementation Workflow

Unified workflow for implementing code changes with quality gates and atomic commits.

Workflow Pattern Detection

Before implementing, check for existing workflow patterns in the repository and your skills, the worklow pattern should be superseeded by these.

Spec-First Workflow

• Look for docs/ or specs/ directories with specifications
• Check for spec files in project structure
• Follow spec → implement pattern if present, superseed to specific skills on this

Test-Driven Development (TDD)

• Check if tests are written before implementation
• Look for test-first patterns in codebase
• Follow test → implement → refactor cycle if present

Other Structured Workflows

• Check for plan files or structured documentation
• Look for workflow indicators in README.md or AGENTS.md
• Follow existing patterns and skills when detected

Implementation Process

1. Atomic Changes

Group related changes together:

• Implementation code + tests
• Feature + related refactoring
• Fix + test for fix

Each atomic change should:

• Pass type checking
• Pass all tests
• Pass linting
• Be self-consistent

2. CI Verification

Before staging any changes: 1. Run CI checks (types, tests, lint) 2. Prefer single CI command if available 3. If checks fail, stop and report 4. Only proceed when all checks pass

3. Atomic Commits

After CI passes: 1. Stage atomic changes 2. Suggest semantic commit message 3. Confirm with user 4. Commit after approval 5. Continue to next atomic change

Stop and Ask

Stop and ask user before:

• Adding type ignores or suppressions
• Using any type or type escapes
• Uncertain how to proceed
• Requirements unclear
• Better approach needs confirmation

Backward Compatibility

• Public interfaces: Consider backward compatibility for APIs, libraries
• Internal refactoring: Unit, integration, and E2E tests serve as confirmation gate
• Greenfield: No backward compatibility needed unless directed

Automation

If user requests "continue to X":

• Proceed with atomic commits automatically
• Resume asking when X point reached
• X can be: file, feature, test passing, etc.

Integration

This workflow integrates with:

• CI verification before commits
• Semantic commit messages
• Test-first development when present
• Spec-first development when present
• Code review practices

Workflow Patterns

Detailed patterns and practices for software development workflows.

Implementation Workflow

• Atomic changes: Group related changes together (code + tests)
• CI verification: Run CI checks before staging (types, tests, lint)
• Semantic commits: Use conventional commit format
• Stop and ask: Ask user before adding type ignores, suppressions, or any types

Code Review Workflow

• Review for functionality, code quality, and security
• Check edge cases and error handling
• Verify tests are present and passing
• Ensure code follows project conventions
• Verify CI passes before completion claims

Testing Workflow

• Write tests before or alongside implementation
• Use appropriate test frameworks for the language
• Test edge cases and error conditions
• Maintain test coverage for critical paths
• Tests go with implementation in atomic commits

Documentation Workflow

• Update documentation when code changes
• Keep README and AGENT files current and accurate
• Document non-obvious design decisions
• Include examples for complex APIs

Refactoring Workflow

• Refactor incrementally, not in big bangs
• Maintain test coverage during refactoring
• Preserve functionality while improving structure
• Document significant architectural changes
• E2E tests serve as confirmation gate for internal refactoring