{"id":223,"date":"2025-11-21T16:41:26","date_gmt":"2025-11-21T15:41:26","guid":{"rendered":"https:\/\/marshfire.net\/wp\/?p=223"},"modified":"2025-11-22T17:01:00","modified_gmt":"2025-11-22T16:01:00","slug":"how-github-copilot-instructions-supercharged-our-code-reviews-and-my-coffee-habit","status":"publish","type":"post","link":"https:\/\/marshfire.net\/wp\/software-architecture\/223\/","title":{"rendered":"How GitHub Copilot Instructions Supercharged Our Code Reviews (and My Coffee Habit)"},"content":{"rendered":"\n

Learn how GitHub Copilot instruction files transformed our code review process with actionable examples and step-by-step setup.<\/p>\n\n\n\n

TL;DR<\/strong><\/h2>\n\n\n\n

We used GitHub Copilot instruction files to automate repetitive review checks, increase clarity, and improve onboarding. Add a `.github\/copilot-instructions.md<\/code>` file, define a few project-specific rules, and use Copilot Chat with `@workspace<\/code>` to get guided, actionable PR feedback in minutes.<\/p>\n\n\n\n

Start in 10 Minutes (Quick Checklist)<\/strong><\/h2>\n\n\n\n
    \n
  • Create\u00a0.github\/copilot-instructions.md<\/code><\/li>\n\n\n\n
  • Add your review rules (start small)<\/li>\n\n\n\n
  • Add optional\u00a0review.md<\/code>,\u00a0branch-review.md<\/code>,\u00a0git-review.md<\/code><\/li>\n\n\n\n
  • Ask Copilot:\u00a0@workspace review this file<\/code><\/li>\n\n\n\n
  • Iterate weekly based on team feedback<\/li>\n<\/ul>\n\n\n\n
    \"AI<\/figure>\n\n\n\n

    Prologue: Powered by Caffeine and Curiosity<\/strong><\/h2>\n\n\n\n

    There\u2019s something about that first sip of coffee that sharpens your focus\u2014especially during code reviews. We used GitHub Copilot instruction files to make reviews faster, clearer, and friendlier. This post walks through the exact files, and prompts we built to make reviews meaningful and repeatable.<\/p>\n\n\n\n

    The Problem: Code Reviews, the Good, the Bad, and the Tedious<\/strong><\/h2>\n\n\n\n

    Code reviews are the backbone of quality software, but they can be a slog\u2014endless nitpicks, unclear expectations, and the dreaded \u201cLGTM\u201d (“Looks good to me”) with no context. We wanted to make reviews more consistent, reduce reviewer fatigue, and encourage best practices without sounding robotic. Enter: GitHub Copilot instruction files.<\/p>\n\n\n\n

    What Are GitHub Copilot Instruction Files?<\/strong><\/h2>\n\n\n\n

    GitHub Copilot instruction files are markdown documents that teach your workspace Copilot about your team’s standards, patterns, and workflow. Instead of hoping Copilot “gets” your team’s vibe, you give it a playbook: how to review, what to look for, and how to communicate.<\/p>\n\n\n\n

    In our workflow we created three instruction files\u2014review.md<\/code>, branch-review.md<\/code>, and git-review.md<\/code>\u2014each tailored to a stage of development. These are living documents that encode our team’s values and priorities and help guide both AI-assisted and human reviews.<\/p>\n\n\n\n

    Building the Review Experience: Best Practices in Action<\/strong><\/h2>\n\n\n\n

    Here’s what we learned while crafting our instruction files.<\/p>\n\n\n\n

    1. Start Human, Stay Human<\/strong><\/h3>\n\n\n\n

    Reviews are ultimately about people, not just code. Use a friendly tone, celebrate wins, and give feedback the way you would over coffee with a teammate. Being constructive sets the right mood for both AI-assisted and human reviewers.<\/p>\n\n\n\n

    Pro Tips<\/h4>\n\n\n\n
      \n
    • Keep prompts conversational and concise.<\/li>\n\n\n\n
    • Explicitly ask for clarifications rather than assumptions.<\/li>\n<\/ul>\n\n\n\n

      2. Be specific, But Not Overbearing<\/h3>\n\n\n\n

      Vague instructions lead to vague reviews. Break expectations into clear, actionable points: what to check (logic, style, tests, docs), what\u2019s a blocker versus a nice-to-have, and how to handle uncertainty.<\/p>\n\n\n\n

      Pro Tips<\/strong><\/h4>\n\n\n\n
        \n
      • Use checklists for repeatable items (tests, a11y, docs).<\/li>\n\n\n\n
      • Mark rules as Critical\/Major\/Minor so reviewers know the priority.<\/li>\n<\/ul>\n\n\n\n

        3. Automate the Boring Stuff<\/strong><\/h3>\n\n\n\n

        Let automation handle linting, formatting, and import order\u2014freeing humans to focus on architecture, design, and intent.<\/p>\n\n\n\n

        Pro Tips<\/strong><\/h4>\n\n\n\n
          \n
        • Run `nx lint <project> --fix<\/code>` or repo-specific linters automatically.<\/li>\n\n\n\n
        • Ask Copilot to skip items that automated tools already verify.<\/li>\n<\/ul>\n\n\n\n

          4. Context Is King<\/strong><\/h3>\n\n\n\n

          Instruction files should reference project-specific guidelines\u2014style guides, accessibility rules, and design token strategies\u2014so feedback remains relevant.<\/p>\n\n\n\n

          Pro Tips<\/strong><\/h4>\n\n\n\n
            \n
          • Link to docs, README sections, or concrete examples in the repo.<\/li>\n\n\n\n
          • Provide small code snippets in the instruction files to illustrate preferred patterns.<\/li>\n<\/ul>\n\n\n\n

            5. Encourage Learning, Not Just Policing<\/strong><\/h3>\n\n\n\n

            Use instructions to nudge reviewers to explain why<\/em> something matters. This turns reviews into teaching moments, helping junior devs learn faster.<\/p>\n\n\n\n

            Pro Tips<\/strong><\/h4>\n\n\n\n
              \n
            • Request explanation-oriented feedback, not just fixes.<\/li>\n\n\n\n
            • Celebrate good patterns in the “Strengths” output.<\/li>\n<\/ul>\n\n\n\n

              What Improved: The Measurable Impact<\/strong><\/h2>\n\n\n\n

              Since adopting Copilot instruction files, we\u2019ve seen:<\/p>\n\n\n\n

                \n
              • Faster review cycles<\/li>\n\n\n\n
              • Clearer, more consistent PR feedback<\/li>\n\n\n\n
              • Quicker onboarding for new team members<\/li>\n\n\n\n
              • Less reviewer fatigue and more constructive engagement<\/li>\n<\/ul>\n\n\n\n

                Before & After: What a PR Looks Like with Copilot Instructions<\/strong><\/h2>\n\n\n\n

                Before:<\/strong><\/p>\n\n\n\n

                A short PR description like “Fixed stuff and added tests,” leaving reviewers guessing.<\/p>\n\n\n\n

                After:<\/strong><\/p>\n\n\n\n

                A structured description generated by Copilot:<\/p>\n\n\n\n

                  \n
                • Summary of changes<\/li>\n\n\n\n
                • Impacted modules<\/li>\n\n\n\n
                • Testing notes<\/li>\n\n\n\n
                • Accessibility considerations<\/li>\n\n\n\n
                • Linked issues<\/li>\n<\/ul>\n\n\n\n

                  This gives reviewers context immediately and reduces back-and-forth.<\/p>\n\n\n\n

                  Real Review Output Example<\/strong><\/p>\n\n\n\n

                  Here’s an excerpt from an actual branch review using our instruction files. The developer implemented a new app layout with sidebar and toolbar components:<\/p>\n\n\n\n

                  Prompt:<\/strong> <\/p>\n\n\n\n

                  \n

                  @workspace review my branch changes against develop using branch-review guidelines<\/p>\n<\/blockquote>\n\n\n\n

                  Copilot Output (excerpt):<\/strong><\/p>\n\n\n\n

                  <\/circle><\/circle><\/circle><\/g><\/svg><\/span>