init-copilot-review（初始化 GitHub Copilot 审查）

Copilot Review Init

Create or refine GitHub Copilot review instruction files for a specific repository. Focus on repo-grounded copilot-instructions.md and scoped *.instructions.md files that improve pull request review quality without wasting character budget.

Trigger boundaries

Use this skill when you need to:

• Create or revise .github/copilot-instructions.md
• Create, split, or tighten .github/instructions/*.instructions.md
• Decide root vs scoped review rules, monorepo/package scoping, applyTo, or excludeAgent
• Debug why Copilot review ignores, misroutes, or weakly follows instruction files

Do not use this skill when:

• You are reviewing a PR directly instead of authoring Copilot review instructions
• You are creating non-Copilot agent files such as CLAUDE.md, AGENTS.md, or generic review docs
• You want generic best-practice prose without grounding it in the target repository

Start with the smallest relevant reference set

Do not read every reference by default. Start with the minimum set that fits the task, then expand only if a real uncertainty remains.

Workflow

1. Ground on the repository before drafting

Inspect the actual repository first. Start by changing into the target repo root. If you are using a shared fixture or sample repo, copy it to a scratch repo/worktree before writing any .github/ files so you do not mutate the source fixture by accident.

Quick repo scan recipe:

find . -maxdepth 3 -type f -name "*.md" | head -20       # doc landscape
ls .github/ .github/instructions/ 2>/dev/null             # existing Copilot config
find . -maxdepth 2 -type f \( -name '.eslintrc*' -o -name '.prettierrc*' -o -name 'eslint.config.*' -o -name 'prettier.config.*' -o -name 'biome.json' -o -name 'biome.jsonc' \) | head -20  # enforced style rules
find . \( -name "*.test.*" \) -o \( -name "*.spec.*" \) | head -10  # test conventions

Gather:

• Structure: single app, multi-service, or monorepo
• Dominant languages, frameworks, and path boundaries
• Existing .github/copilot-instructions.md, .github/instructions/, CONTRIBUTING.md, CLAUDE.md, and similar repo guidance
• Linter, formatter, test, and CI configuration so you do not waste rule budget on enforced style rules
• Representative files in each scope (examine 2–3 files per scope: one typical, one complex, one boundary-case)
• Recurring review themes: look for repeated patterns in recent PRs, open issues, code comments, and CONTRIBUTING.md that point to risk areas or repeated defects

⚠️ Steering: Existing instruction files. If the repository already has copilot instruction files, do NOT start from scratch. Evaluate them against the quality criteria in Step 3 (SMSA). Note gaps, redundancies, and linter-duplicated rules. Then decide: refine in place if the architecture is sound (most existing files just need tightening), or recreate only if the structure fundamentally misroutes rules. The default is to refine.

⚠️ Steering: Multi-stack repositories. When a repo has two fundamentally different stacks (e.g., Go backend + Svelte frontend, Python API + React SPA), treat each stack as a separate scope from the start. Check whether the secondary stack is a bundled artifact (e.g., ui/dist/) or actively developed source (e.g., ui/src/). Only actively developed source needs its own instruction files.

Stopping test — move on when you can answer all three:

1. What are the 2–4 highest-risk areas where review catches real bugs?
2. Which linter/formatter rules already enforce style, so you can skip them?
3. What is the narrowest directory structure that separates review scopes?

Done when: All three stopping-test questions are answered with repo evidence. If you cannot answer one, you need more exploration. If all three are answered, stop — more exploration adds no value.

2. Choose the instruction architecture before writing prose

Start from this default shape:

.github/
├── copilot-instructions.md
└── instructions/
    ├── <language>.instructions.md
    └── <domain-or-package>.instructions.md

Use this placement logic:

Steering rules:

• Start minimal: most repos should begin with 1 repo-wide file plus 2–4 scoped files
• Grow toward 5–12 total files only when repo breadth justifies it
• Do not create a file just because you detected a language or framework; create it only if you have 2–3 high-signal rules (rules that catch bugs, security issues, or architectural mistakes a linter cannot) unique to that scope
• Do not dump everything into copilot-instructions.md; that causes scope bleed and usually wastes the 4,000-character limit
• Monorepo package files must contain only package-unique rules, not repeated root rules

⚠️ Steering: Over-creation trap. The most common mistake is creating a file for every detected technology. A repo using TypeScript + React + Prisma does NOT need three separate files if most rules are shared. Start with 1 root + 2 scoped, then add only when a new scope has 2+ unique rules that do not fit anywhere else.

Done when: You have a file tree with file names and the applyTo glob for each scoped file. Every file in the tree has a clear reason to exist.

3. Select rules with evidence and reuse discipline

Every rule should be Specific, Measurable, Actionable, and Semantic (SMSA).

SMSA quick check for each rule:

Use this filter:

Reusable categories are helpful only when the repository actually needs them:

• Repo-wide candidates: security, shared error handling, shared performance risks, testing philosophy
• Scoped candidates: language idioms, framework conventions, API validation, auth/payment paths, migrations, package boundaries, test-file rules

If you use references/scenarios.md (consult when you need a full-stack example for an architecture you have already chosen) or references/micro-library.md (consult when you need a starter pattern for a specific scope after grounding), treat them as pattern libraries to adapt — never copy verbatim. Change variable names, error types, framework calls, and examples to match the target repo's actual code.

⚠️ Steering: Concept overlap ≠ duplication. Two files may mention the same concept (e.g., error handling) as long as the rules are additive and target different contexts. A root file saying "always return structured errors" and a scoped API file saying "use ApiError with status codes" are complementary, not duplicates. Flag duplication only when the same instruction text is copy-pasted or when rules could contradict.

Done when: Every rule passes the SMSA check, no rule duplicates a linter, and every rule cites specific repo evidence (file, config, pattern, or convention).

4. Draft files with scope-safe formatting

When writing files:

• copilot-instructions.md is plain Markdown in .github/ and has no frontmatter
• Every scoped file lives under .github/instructions/
• Every scoped file starts at line 1 with YAML frontmatter:

---
applyTo: "src/api/**/*.ts"
---

• applyTo is a single quoted or double-quoted glob string relative to repo root
• GitHub Copilot uses standard glob patterns including **, *, and brace expansion {a,b}
• Glob syntax: * matches within a directory, ** matches across directories, {ts,tsx} matches alternatives
• When a logical domain spans multiple directories, prefer a broader wildcard like src/**/*.ts over listing each subdirectory
• excludeAgent, when used, should be either "code-review" or "coding-agent"
• File names should use kebab-case.instructions.md
• Highest-priority rules go first
• Keep examples short and include them only when they clarify a semantic rule

⚠️ Steering: Brace expansion platform validation. GitHub glob syntax supports {ts,tsx}, but shell tools do not all validate it the same way. Do not rely on find -path to validate brace patterns. Use Python globbing in Step 5 or split the scope into separate patterns/files if you need a shell-only fallback.

Overlapping scoped files are acceptable only when the rules are additive — two files may mention the same concept if the rules target different contexts. Flag duplication only when the same instruction is copy-pasted or when rules could conflict. If two matching files would disagree, narrow applyTo until they no longer conflict. Multiple matching scoped files are concatenated, so never rely on overlap to resolve contradictions for you.

Done when: Every file has correct frontmatter (or none for root), every applyTo glob is verified against the repo structure, and no file exceeds 3,500 characters (leaving buffer below the 4,000 hard limit).

5. Validate before presenting anything

Run this checklist — every item must pass:

Character limits:

• Each file stays under the hard 4,000-character limit; aim for 2,500–3,500
• Frontmatter counts toward the limit
• Use wc -c for byte count or wc -m for true character count (matters for multi-byte content like UTF-8 emoji or CJK characters)

Content quality:

• No external links
• No attempts to control Copilot's comment formatting, severity labels, approvals, or merge blocking
• No rules duplicated from linter or formatter config — verify against the actual config files you found in Step 1. Example: find. -maxdepth 2 -type f \(-name '.eslintrc*' -o -name 'eslint.config.*' -o -name '.prettierrc*' -o -name 'prettier.config.*' -o -name 'biome.json' -o -name 'biome.jsonc' -o -name '.golangci.yml' -o -name '.golangci.yaml' \) -exec grep -n "rule-name" {} + 2>/dev/null
• No contradictory rules across overlapping scopes
• Root file contains only universal rules
• Package/service files do not repeat root rules

Glob verification:

# Verify a glob pattern matches intended files
python3 - <<'PY'
from glob import glob
def expand_braces(pattern):
    if '{' not in pattern:
        return [pattern]
    start = pattern.index('{')
    end = pattern.index('}', start)
    options = pattern[start + 1:end].split(',')
    expanded = []
    for option in options:
        expanded.extend(expand_braces(pattern[:start] + option + pattern[end + 1:]))
    return expanded
pattern = "<applyTo-pattern>"
paths = sorted({path for candidate in expand_braces(pattern) for path in glob(candidate, recursive=True)})
for path in paths[:20]:
    print(path)
PY

Deployment awareness:

• Instruction changes must be on the base branch of the PR (typically main or develop) to affect review. A feature-branch-only change does NOT affect the same PR's review. Plan for a merge-to-base then re-review workflow.

Done when: All checklist items pass. If any fail, fix before proceeding to Step 6.

6. Present the result as an architecture, not just a dump

Return:

• If filesystem access is available, write or update the instruction files in .github/ first unless the user explicitly asked for draft-only output.
• The .github/ file tree
• Full contents of each generated instruction file
• A 1–3 sentence per-file explanation covering:

- Why this file exists - What scope it targets - Which repo evidence justified its rules - Why the rule set was kept out of other files

If repo evidence is weak or mixed, say so explicitly and keep the instruction set conservative.

Done when: The user can copy the file tree and contents directly into their repo with no further editing. Every file has a justification grounded in repo evidence.

Do this, not that

Recovery paths

If the task starts drifting, recover in this order:

1. Too broad or too many files → collapse to the root file plus only the highest-signal scoped files
2. File near 4,000 characters → remove low-priority rules, shorten examples, or split by narrower applyTo
3. Unclear scoping → inspect representative repo files and choose the narrowest glob that still matches the intended scope
4. Conflicting rules → make scopes non-overlapping or rewrite the rules to be additive
5. Weak or generic Copilot comments → rewrite rules for specificity and remove linter-level noise
6. Instructions seem ignored → follow references/troubleshooting.md in order: location → character count → frontmatter → base branch → glob match → conflicts → specificity → incremental retest → re-review
7. Existing files are poor quality → evaluate against SMSA, note specific gaps, refine in place rather than discarding
8. Multi-stack repo is confusing → treat each stack as an independent scope; do not force cross-stack rules

Reference routing

• references/setup-and-format.md — file locations, root vs scoped formats, character limits, review modes, configuration levels, base-branch behavior, and working with existing instruction files
• references/writing-instructions.md — rule quality (SMSA criteria with pass/fail examples), section ordering, root vs scoped content decisions, character budgets, code examples, concept overlap vs duplication, and iteration workflow
• references/scoping-and-targeting.md — applyTo glob syntax with framework-specific patterns, excludeAgent, precedence, additive overlap, monorepo layout, multi-stack repos, gap analysis, and optimal file counts
• references/troubleshooting.md — ignored instructions, scope mistakes, architecture mistakes, existing-instructions evaluation, glob verification recipes, conflict diagnosis, debugging order, verification, and non-determinism
• references/scenarios.md — full-stack examples with adaptation workflow and scenario selection guide; adapt only after the file architecture is already chosen
• references/micro-library.md — small templates with adaptation warnings and consultation triggers; adapt only after repo grounding when you need a starter pattern for a specific scope