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.