How to use Copilot Spaces for architecture context
GitHub Copilot Spaces architecture context workflow for ADRs, issues, PRs, files and IDE agent mode limits. What Copilot Spaces should do for architecture context Architecture…
Faisal Karkoh · 26 Oct 2026 · 10 min read
What Copilot Spaces should do for architecture context
Architecture context usually lives in too many places: ADRs explain settled decisions, issues describe active work, pull requests preserve the discussion that led to a change, and source files show what the system actually does now. The risk with GitHub Copilot Spaces is treating it as a second repository index and adding everything.
The better use is narrower. Use a Space as a maintained context contract for one architecture question, subsystem or migration. It should tell Copilot which artefacts matter, how to rank them when they disagree, and which sources are only background material. This is the same discipline behind designing coding agent context in large repos: give the agent a curated file-based contract, not an unbounded tour of the codebase.
This article uses an illustrative, not observed, example: a hypothetical team creates a Copilot Space called Checkout Architecture for a web application checkout flow. The goal is to help Copilot answer architecture questions using selected ADRs, source files, issues, pull requests and design notes without turning the Space into an uncurated repository dump.
Evidence disclosure: this is a researched workflow based on GitHub documentation, changelog pages and billing documentation accessed on 2026-10-26. No accuracy, latency, token usage or cost tests were run. GitHub announced Copilot Spaces general availability on 24 September 2025 in the GitHub changelog.
Prerequisites and limits before you build the Space
Before designing the Space, check the constraints that change the workflow.
- Copilot access: GitHub says anyone with a GitHub Copilot licence, including Copilot Free, can create and use Spaces in its Copilot Spaces documentation.
- Repository permissions: add only sources the intended users are allowed to view. For individual-owned Spaces, GitHub documents that viewers only see sources they have access to.
- Branch assumption: GitHub says Spaces refer to the latest version of code on the repository's main branch. Do not use a Space as evidence for a feature branch unless the branch-specific detail is captured in an issue, pull request or note.
- Repository versus file context: attaching a repository does not load the whole project into memory. GitHub says Copilot searches the repository and retrieves relevant content. Attaching an individual file loads that file's full contents into Copilot's context window for every query in that Space.
- Source freshness: GitHub files and other GitHub-based sources added to a Space are automatically updated as they change. Treat uploaded local files as static unless you deliberately replace them.
- IDE use: Copilot Spaces can be used in GitHub.com Copilot Chat and in supported IDEs through the GitHub MCP server, but IDE use has different source support.
There is also a cost exposure, but not enough measured data here to model it. GitHub's billing documentation says Copilot Spaces consumes GitHub AI Credits, and that credit use is based on input, output and cached tokens, with 1 AI Credit equal to $0.01 USD in the individual billing documentation. Without measured token usage for this workflow, the practical advice is to avoid broad, noisy context rather than to estimate a fake price.
Step 1: choose the architecture artefacts that deserve persistent context
Start with the architecture question, not the repository tree. For the Checkout Architecture Space, the question is: how should checkout changes respect payment retries, order state transitions and reconciliation boundaries?
The selection rule is simple: add stable, high-signal artefacts that explain decisions, boundaries and current change intent. Leave general repository material to search unless one file must influence every answer.
| Artefact | Why include it | GitHub.com Space chat | Supported IDE agent mode |
|---|
| ADR Markdown files for payment provider choice, order state transitions and retry policy | They describe settled decisions and trade-offs. | Good fit as GitHub files. | Good fit as GitHub files. |
| Architecture overview Markdown file | It names checkout boundaries, services and ownership. | Good fit as a GitHub file. | Good fit as a GitHub file. |
| Specific source files for checkout state, payment adapter interfaces and order persistence contracts | They show current implementation contracts that should be considered in every answer. | Use individual GitHub file attachments when the full file should always be considered. | Supported as GitHub files. |
| Entire checkout repository | Useful when retrieval is enough and you do not know which file Copilot may need. | Possible, but repository context is searched and retrieved rather than fully loaded. | Do not rely on it. GitHub documents that repository context is not supported when using Spaces in an IDE. |
| Current issue for checkout refactor | It explains active intent, acceptance criteria and unresolved questions. | Good fit. | Supported. |
| Two historical pull requests for payment retries and order reconciliation | They preserve historical rationale and review discussion. | Good fit. | Supported. |
| Free-text design note | Useful for temporary open questions, non-goals and naming conventions. | Good fit when deliberately maintained. | Supported as text content. |
| Uploaded local architecture document | Only useful when the source is not in GitHub and does not need to auto-update. | Supported according to GitHub's Space source types. | Do not rely on it. Uploaded files are not supported in IDE Spaces use. |
The key decision is whether an artefact should be persistent context or retrievable background. If a file must influence every architecture answer, attach the specific file. If the repository is only useful as a search surface, attach the repository on GitHub.com, but do not assume the same behaviour in IDE agent mode.
Step 2: create the Checkout Architecture Space
In the illustrative setup, create one Space for checkout architecture rather than one general engineering Space. GitHub's Space creation documentation says users can add instructions and sources, including GitHub files, folders, entire repositories, linked files, pull requests and issues, uploaded files, or added text content.
GitHub’s official docs show the Add to space control on a repository file, which is the public UI evidence for adding selected GitHub files instead of dumping broad repository context into the Space.
Use instructions to define the role of the Space before adding sources. For this example, the Space instructions are:
Treat this Space as architecture context for checkout changes. Prefer ADRs for settled decisions, issues for active intent, PRs for historical rationale and source files for current implementation details. When sources conflict, say which source conflicts and ask for confirmation before proposing code changes.
Then add sources in this order.
- Add the ADRs as GitHub files. Include only the payment provider choice, order state transitions and retry policy ADRs. Avoid adding the whole ADR folder if it contains unrelated decisions.
- Add the architecture overview as a GitHub file. This gives Copilot the shared vocabulary for checkout boundaries and services.
- Add selected source files, not the whole tree. Attach the files that define checkout state, payment adapter interfaces and order persistence contracts. Because GitHub says individual file attachments are loaded in full for every Space query, use this only for files that are compact and central.
- Link the current checkout refactor issue. This captures active intent separately from settled architecture. If the issue later becomes the handoff into implementation, keep it bounded in the same way as a GitHub issue-to-pull-request prompt workflow, with clear scope, acceptance criteria and review expectations.
- Link two historical pull requests. In this example, use the PR that introduced payment retries and the PR that introduced order reconciliation.
- Add one free-text design note. Keep it short: open questions, non-goals and naming conventions. If it becomes canonical, move it into a GitHub file so it can be reviewed and updated with the repository.
Avoid attaching the entire repository by default. Use a repository attachment only when search-and-retrieve behaviour is acceptable. If your team needs the same Space from an IDE, prefer GitHub files, issues, pull requests, text content and instructions, because repository context is not supported in IDE Spaces use.
Step 3: use the Space from GitHub.com and supported IDE agent mode
There are two operating modes, and they should be verified separately.
On GitHub.com, use Copilot Chat with the configured Space. A useful first query is narrow and diagnostic:
Using the Checkout Architecture Space, explain the current retry policy for failed payment authorisations. Separate settled ADR decisions from active refactor intent, and list any source conflicts before suggesting implementation changes.
The expected output is not a measured quality improvement. The expected output is structural: Copilot should answer with reference to the curated Space sources rather than only the current chat prompt, distinguish settled decisions from active issue intent when the sources make that distinction clear, and identify conflicts instead of silently choosing one source.
In an IDE, do not assume the Space is available just because Copilot Chat is installed. GitHub's IDE Spaces documentation says this functionality is available in IDEs that support both the GitHub Copilot extension and the GitHub MCP server. It also says Spaces can only be used in agent mode in an IDE because the Space context is accessed through the GitHub MCP server. If you are deciding where agentic coding belongs, compare this with the broader trade-offs in Cursor vs Claude Code for IDE-first and terminal-first workflows.
For the remote GitHub MCP server, GitHub documents that the copilot_spaces toolset is not included in the default configuration and must be explicitly enabled. In the IDE tool picker, confirm that get_copilot_space and list_copilot_spaces are listed and enabled.
For Copilot Business or Copilot Enterprise users, there is one more gate. GitHub's GitHub MCP Server setup documentation says the organisation or enterprise policy for MCP servers in Copilot must be enabled to use MCP with Copilot.
Then ask the same diagnostic query in IDE agent mode. If the answer is missing repository-level context or uploaded files, treat that as an interface limitation first, not as an answer-quality failure. GitHub documents that when using Spaces in an IDE, repository context and uploaded files are not supported, while text content, GitHub files, issues, pull requests and instructions are supported.
Step 4: maintain the Space as architecture changes
A Space becomes risky when it preserves old intent more strongly than current architecture. Maintenance should be small and explicit.
- Keep canonical decisions in GitHub files. Update ADRs and architecture overview files in the repository rather than copying long-lived notes into uploaded files.
- Retire PRs and issues when they stop explaining current behaviour. Historical PRs are useful when they explain why a decision was made. They are less useful when they only contain obsolete implementation detail.
- Use free-text notes for temporary context. Open questions, non-goals and naming conventions fit well. If the note becomes policy, move it into the repository.
- Review sharing before adding sensitive material. GitHub's collaboration documentation for Copilot Spaces says organisation-owned Spaces can use admin, editor, viewer and No access roles. Individual-owned Spaces can be private, shared with specific GitHub users or public, with public Spaces view-only by default.
- Check individual subscriber data-use settings for sensitive notes. GitHub's Copilot plans page states that for individual subscribers, GitHub may use Copilot interaction data, including prompts, outputs and generated code snippets, to train and improve AI models unless the user opts out. Treat sensitive architecture strategy, security design or customer-specific context accordingly.
If you later need to manage many Spaces across repositories, the API may become useful. GitHub announced the Copilot Spaces API as generally available on 18 May 2026, and the REST API documentation says it can manage resource types including repository, GitHub file, free text, GitHub issue and GitHub pull request resources. That is a lifecycle automation path, not a requirement for the manual architecture workflow here. For broader repository upkeep beyond Spaces, see AI agent GitHub maintenance workflows for triage, test repair, migrations and documentation.
Failure cases and verification checklist
Use this checklist before you standardise the Space across a team.
- Missing Copilot access: confirm the user has a GitHub Copilot licence before creating or using the Space.
- Wrong branch assumption: if Copilot appears to ignore a feature branch, check whether the relevant detail exists only outside main. GitHub documents main-branch behaviour for Spaces code sources.
- Over-broad repository attachment: if answers drift into unrelated code, replace broad repository context with specific files, issues and PRs for the architecture question.
- File expected in every answer but only repository attached: attach the individual file. GitHub says individual file contents are loaded into the context window for every query in that Space.
- Uploaded file expected in IDE agent mode: replace it with a GitHub file or free-text content where possible, because uploaded files are not supported for IDE Spaces use.
- Repository context expected in IDE agent mode: use selected GitHub files instead, because repository context is not supported there.
- MCP unavailable for Business or Enterprise users: check the organisation or enterprise MCP policy before changing the Space design.
- Spaces tools missing in the IDE: confirm agent mode, the GitHub MCP server, the explicit
copilot_spaces toolset, and the get_copilot_space and list_copilot_spaces tools. - Permissions hide sources: confirm every intended viewer has access to the underlying repositories, issues and pull requests. Sharing the Space does not grant access to sources the viewer cannot otherwise see.
- Stale design notes: move canonical content into GitHub files or update the Space text deliberately.
The next action is deliberately small: build one Copilot Space for one architecture question, such as checkout retries or order reconciliation, then test one query on GitHub.com and the same query in IDE agent mode. Document any missing source type as a Space design issue before you turn the pattern into a team standard.