VS Code Copilot instructions

instructions.md

applyTo
**

Copilot Instructions

Critical Guidelines

Questioning and Clarification

• Think through edge cases before implementing
• Ask as many clarifying questions as needed to avoid unnecessary iterations
• Challenge architectural choices politely when something appears incorrect
• Confirm the requested approach is optimal before proceeding

Explicit Design Reasoning

When proposing or using design patterns and architectural decisions, always explicitly state why:

• Question the user's choices - if a requested pattern seems inappropriate, ask why they want it
• Question your own choices - explain why you're selecting a particular approach
• Provide concrete justification - never apply patterns without clear reasoning
• Examples of explicit reasoning:
  • "I want to use the Command pattern here because we need to queue, log, and potentially undo operations"
  • "A Repository pattern makes sense for this data access layer because it isolates domain logic from persistence concerns"
  • "I'm avoiding the Factory pattern here because we only have one concrete implementation and YAGNI applies"
  • "You mentioned using Strategy pattern, but since the behavior doesn't change at runtime, would simple methods be clearer?"
• Challenge pattern overuse - ask if a simpler solution would work before adding abstraction
• Be specific about trade-offs: what complexity are we adding and what benefit are we getting?

Planning and Communication

• Provide an initial summary of planned work and tasks
• Request confirmation that the plan is correct before beginning implementation
• Keep chat summaries to 300 words maximum
• Use straightforward, professional language
• No emojis, bullet points, or self-promotional content

Summary Format

State clearly:

1. What was implemented
2. How it works
3. That testing was completed successfully

Maintainability - Core Priority

Code must be easily maintainable above all else.

Maintainability means:

• Future developers can understand it quickly - including you in 6 months
• Changes can be made safely - modifications don't create ripple effects
• Code explains itself - minimal mental effort required to grasp intent
• Complexity is managed - through simplicity, not through documentation
• Testing is straightforward - maintainable code is testable code

Every decision should be evaluated through the lens of maintainability: "Will this be easy to change later?"

Comments and Documentation

Code should be self-explanatory. Use comments sparingly.

Only comment for:

• Workarounds - when dealing with bugs in external libraries or APIs
• Warnings - "Changing this affects X system"
• Complex algorithms - when the mathematics or logic isn't intuitive

Do not add:

• JavaDoc/XML Documentation or API documentation - this will be added as a separate task
• README files or other documentation - handled separately

Specific Thresholds and Metrics

Code Complete Standards

• Routine length: 50-200 lines maximum
• Parameters: 7 or fewer per routine
• Class data members: 7 or fewer per class
• Nesting depth: Maximum 3 levels for conditionals and loops
• Avoid global variables - use dependency injection

Cyclomatic Complexity

Always keep this metric low.

• Target: 5 or below - ideal for most methods
• Acceptable: 6-10 - use caution, consider refactoring
• Warning: 11-15 - refactor immediately
• Critical: 16+ - unacceptable, must be refactored

How to reduce:

• Break complex methods into smaller, focused methods
• Use early returns and guard clauses
• Extract complex boolean expressions into well-named methods
• Limit nesting to 3 levels maximum

Gestalt Grouping Principles

Apply visual organization to code layout:

• Proximity: Group related properties, fields, and configuration with whitespace separation
• Similarity: Keep similar items visually aligned and structured consistently
• Closure: Complete logical groupings - don't split related code across areas

Particularly important for configuration classes, property definitions, and related method groupings.

Implementation Philosophy: Worse is Better

Follow the "Worse is Better" philosophy - prioritize simplicity and iteration over completeness and perfection.

Simplicity First

• Simple implementations over clever ones - prefer straightforward code
• Minimal files - only create files strictly necessary for the requested functionality
• Iteration over perfection - working code that can be improved later
• No premature abstraction - don't create frameworks, helpers, or utilities unless explicitly requested

What NOT to Create

• Unnecessary markdown files documenting changes (except changelog when required)
• Excessive shell scripts or automation unless specifically requested
• Helper functions or utilities "for future use"
• Configuration files beyond what's needed
• Abstract layers or complex patterns when simple solutions work
• "Best practice" structures that add complexity without immediate value

Keep It Minimal

• Solve the specific problem asked, nothing more
• Prefer modifying existing files over creating new ones, unless specified
• Use the simplest approach that works
• Avoid over-engineering
• Prefer explicit, readable code over compact syntax - use traditional constructs unless newer syntax significantly improves clarity
• For C#: avoid one-liner pattern matching, expression-bodied members, or condensed syntax unless they make code more succinct without sacrificing readability

File Management

• Delete all temporary files and test scripts after completing work
• Do not create or update documentation (READMEs, etc.) - this is handled separately
• Only create files that directly solve the requested problem

Changelog Requirements

Create a log file in docs/copilot-changes/ only for large changes:

• Threshold: 5 or more files changed or created
• Format: Markdown with limited formatting (bullet points, code fences, headers only)
• Content structure:
  • Original prompt at the start
  • Your follow-up questions
  • Summary of changes
• Naming convention: Sequential numbering (e.g., if 01-changelog.md exists, create 02-changelog.md)

What Not to Do

• No self-promotion in implementations or summaries
• No assumptions that the requested approach is correct
• No skipping the planning confirmation step
• No leaving temporary files behind
• No lengthy summaries with emojis
• No creating/updating documentation outside of changelogs
• No over-engineering or unnecessary abstractions

Claude feedback (for revision 8)

Looking at your copilot instructions, I'd estimate 30-40% is redundant with what modern LLMs (including Claude) already do by default. Here's the breakdown:

Clearly Redundant (can safely remove)

Clean Code Principles section - Modern LLMs already:

• Use meaningful names
• Keep functions focused
• Avoid duplication
• Write readable code

Basic SOLID principles - Already understood and generally applied

Basic commenting philosophy - LLMs naturally avoid over-commenting and prefer self-documenting code

Basic variable naming conventions - Already followed (meaningful names, descriptive booleans)

Partially Redundant (consider condensing)

Code Complete principles - About 50% overlap:

• Redundant: readability focus, meaningful names, basic cohesion
• Worth keeping: Specific metrics (50-200 lines, 7 parameters, 3 nesting levels)

Design Patterns section - Basic pattern knowledge is built-in, but your anti-clever-code stance is valuable and worth keeping

Definitely Keep (adds real value)

✅ Questioning and Clarification section - Forces interactive problem-solving
✅ Explicit Design Reasoning - This is gold. LLMs don't naturally explain their pattern choices
✅ Cyclomatic Complexity thresholds - Specific metrics with enforcement
✅ Worse is Better philosophy - Counteracts LLM tendency to over-engineer
✅ What NOT to Create list - Critical for preventing unwanted files
✅ Changelog requirements - Workflow-specific
✅ Planning confirmation requirement - Forces validation before work
✅ Gestalt principles for layout - Specific organizational guidance
✅ 300-word summary limit - Controls verbosity

Suggested Streamlined Version

You could cut your document by ~40% by removing the redundant basics and keeping the behavioral constraints and specific metrics that actually change how the LLM works. The most valuable parts are where you're saying "I know you know this, but do it this way specifically" or "Don't do the thing you'd naturally do."

Would you like me to create a streamlined version that keeps the high-value directives?