Why Copilot Spaces + Markdown repos work so well

When you ask Copilot generic questions (“How should we log errors?” “What’s our API versioning approach?”), the model will often respond with reasonable defaults. But reasonable defaults are not the same as your standards.

Copilot Spaces solve the context problem by allowing you to attach a curated set of sources (files, folders, repos, PRs/issues, uploads, free text) plus explicit instructions—so Copilot answers in the context of your team’s rules and artifacts. Spaces can be shared with your team and stay updated as the underlying GitHub content changes—so your “best practices coach” stays evergreen.

The architecture (high level)

Here’s the mental model:

Engineering Knowledge Base Repo: A dedicated repo containing your standards as Markdown (coding style, architecture decisions, security rules, testing conventions, examples, templates).

Copilot Space: “Engineering Standards Coach”: A Space that attaches the knowledge base repo (or key folders/files within it), optionally your main application repo(s), and a short set of “rules of engagement” (instructions).

In-repo reinforcement (optional but powerful): Custom instruction files (repo-wide + path-specific) and prompt files (slash commands) inside your production repos to standardize behavior and workflows.

Step 1 Create a Knowledge Base repo (Markdown-first)

Create a repo such as:

• engineering-knowledge-base
• platform-playbook
• org-standards

A practical starter structure:

engineering-knowledge-base/
  README.md
  standards/
    coding-style.md
    logging.md
    error-handling.md
    performance.md
  security/
    secure-coding.md
    secrets.md
    threat-modeling.md
  architecture/
    overview.md
    adr/
      0001-service-boundaries.md
      0002-api-versioning.md
  testing/
    unit-testing.md
    integration-testing.md
    contract-testing.md
  templates/
    pr-review-checklist.md
    api-design-checklist.md
    definition-of-done.md

Tip: Keep these docs opinionated, concrete, and example-heavy—Copilot works best when it can point to specific patterns rather than abstract principles.

Step 2 Create a Copilot Space and attach your sources

Create a space, name it, choose an owner (personal or organization), then add sources and instructions. Inside the Space, add two types of context: Instructions (how Copilot should behave) and Sources (your actual code and docs).

2.1 Instructions (how Copilot should behave in this Space)

Example instructions you can paste:

You are the Engineering Standards Coach for this organization.

Goals:
- Recommend solutions that follow our standards in the attached knowledge base.
- When proposing code, align with our logging, error-handling, security, and testing guidelines.
- When uncertain, ask for the missing repo context or point to the exact standard that applies.

Output format:
- Start with the standard(s) you are applying (with a link or filename reference).
- Then provide the recommended implementation.
- Include a lightweight checklist for reviewers.

2.2 Sources (your real “knowledge base”)

Attach:

• The knowledge base repo (or just the folders that matter)
• Your main code repo(s) (or select folders)
• PR checklist and Definition of Done templates
• Key architecture docs, runbooks, or troubleshooting guides

Step 3 (Optional) Add instruction files to your production repos

Spaces are excellent for curated context and team-wide “ask me anything about our standards.” But you can reinforce consistency directly inside each repo by adding custom instruction files.

3.1 Repo-wide instructions (.github/copilot-instructions.md)

Create: your-app-repo/.github/copilot-instructions.md

# Repository Copilot Instructions

## Tech stack
- Language: TypeScript (strict)
- Framework: Node.js + Express
- Testing: Jest
- Lint/format: ESLint + Prettier

## Engineering rules
- Use structured logging as defined in /docs/logging.md
- Never log secrets or raw tokens
- Prefer small, composable functions
- All new endpoints must include: input validation, authz checks, unit tests, and consistent error handling

## Build & test
- Install: npm ci
- Test: npm test
- Lint: npm run lint

3.2 Path-specific instructions (.github/instructions/*.instructions.md)

Create: your-app-repo/.github/instructions/security.instructions.md

---
applyTo: "**/*.ts"
---
# Security rules (TypeScript)

- Never introduce dynamic SQL construction; use parameterized queries only.
- Any new external HTTP call must enforce timeouts and retry policy.
- Any auth logic must include negative tests.

Step 4 (Optional) Turn your best practices into “slash commands” with prompt files

To standardize repeatable workflows like code review, test scaffolding, or endpoint scaffolding, create prompt files (slash commands) as .prompt.md files—commonly in .github/prompts/. Engineers invoke them manually in chat by typing /.

Create: your-app-repo/.github/prompts/standards-code-review.prompt.md

---
description: Review code against our org standards (security, perf, style, tests)
---

You are a senior engineer performing a standards-based review.

Use these checks:
1) Security: input validation, authz, secrets, injection risks
2) Reliability: error handling, retries/timeouts, edge cases
3) Observability: structured logs, metrics, tracing where relevant
4) Testing: required coverage, negative tests, naming conventions
5) Style: follow repository rules in .github/copilot-instructions.md

Output:
- Summary (2-3 lines)
- Issues (severity: BLOCKER/REQUIRED/SUGGESTION)
- Suggested patch snippets (only where confident)
- “Ready to merge?” verdict

Now any engineer can type /standards-code-review and get the same structured output every time, without rewriting the prompt.

How teams actually use this day-to-day

Recipe A  Onboarding a new engineer

Ask inside the Space: “Summarize our service architecture and coding conventions for onboarding. Link the key docs.”

Recipe B  Writing a feature with best-practice guardrails

Ask in the Space: “We’re adding endpoint X. Generate a plan that follows our API versioning ADR and error-handling standard.”

Recipe C  Enforcing review standards consistently

In the repo, run the prompt file: /standards-code-review.

Governance and best practices (what to do / what to avoid)

1. Keep Spaces purpose-built. Avoid dumping an entire org into one Space if your goal is consistent, grounded output.
2. Prefer linking the “golden source.” Keep standards in a single repo and update them via PR—treat it like code.
3. Make instructions short but strict. Detailed rules belong in your Markdown standards.
4. Avoid conflicting instruction files. If instructions contradict each other, results can be inconsistent.

References (official docs for further reading)

About GitHub Copilot Spaces: https://docs.github.com/en/copilot/concepts/context/spaces 

Creating GitHub Copilot Spaces: https://docs.github.com/en/copilot/how-tos/provide-context/use-copilot-spaces/create-copilot-spaces 

Adding custom instructions for GitHub Copilot: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions 

Use custom instructions in VS Code: https://code.visualstudio.com/docs/copilot/customization/custom-instructions 

Use prompt files in VS Code: https://code.visualstudio.com/docs/copilot/customization/prompt-files 

Closing: the “best practices” flywheel

Once you implement this pattern, you get a virtuous cycle: teams encode standards as Markdown; Copilot Spaces ground answers in those standards; prompt files and instruction files standardize execution; and code reviews shift from style policing to design and correctness.