software-engineer

$27

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