diff --git a/.codespellrc b/.codespellrc index 43f1415e..5fdb581f 100644 --- a/.codespellrc +++ b/.codespellrc @@ -66,10 +66,22 @@ # soruce - intentional misspelling for tests -ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,extenions,Vertexes,nin,FO,CAF,Parth,ans,gud,Vally,vally,ACI,soruce +# straightaway - valid adverb ("immediately") in mirrored copilot-workshops content + +# crystalize - valid US spelling variant in mirrored copilot-workshops content + +ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,extenions,Vertexes,nin,FO,CAF,Parth,ans,gud,Vally,vally,ACI,soruce,straightaway,crystalize # Skip certain files and directories # *.tm7 - MTM DataContract exports; embedded base64 icon blobs trigger false positives -skip = .git,node_modules,package-lock.json,*.lock,website/build,website/.docusaurus,.all-contributorrc,./skills/geofeed-tuner/assets/*.json,./skills/geofeed-tuner/references/*.txt,./plugins/fastah-ip-geo-tools/skills/geofeed-tuner/assets/*.json,./plugins/fastah-ip-geo-tools/skills/geofeed-tuner/references/*.txt,./extensions/arcade-canvas/game/phaser.min.js,./extensions/pr-artifact-explorer/assets/asciinema-player.min.js,./extensions/pr-artifact-explorer/assets/asciinema-player-worker.min.js,./extensions/pr-artifact-explorer/assets/primer-*.css,./extensions/flight-map-canvas/game/vendor/three.min.js,*.tm7 +# website/src/content/docs/ - localized Learning Hub content mirrored from + +# upstream course repos. codespell only knows English, so Spanish, Japanese, Korean, + +# Portuguese, and Chinese prose produces false positives on ordinary foreign words. + +# These files are source-faithful mirrors and must not be edited to satisfy a spell checker. + +skip = .git,node_modules,package-lock.json,*.lock,website/build,website/.docusaurus,.all-contributorrc,./skills/geofeed-tuner/assets/*.json,./skills/geofeed-tuner/references/*.txt,./plugins/fastah-ip-geo-tools/skills/geofeed-tuner/assets/*.json,./plugins/fastah-ip-geo-tools/skills/geofeed-tuner/references/*.txt,./extensions/arcade-canvas/game/phaser.min.js,./extensions/pr-artifact-explorer/assets/asciinema-player.min.js,./extensions/pr-artifact-explorer/assets/asciinema-player-worker.min.js,./extensions/pr-artifact-explorer/assets/primer-*.css,./extensions/flight-map-canvas/game/vendor/three.min.js,*.tm7,./website/src/content/docs/es-es,./website/src/content/docs/ja-jp,./website/src/content/docs/ko-kr,./website/src/content/docs/pt-br,./website/src/content/docs/zh-cn diff --git a/.github/workflows/copilot-workshops-sync.md b/.github/workflows/copilot-workshops-sync.md index 82f2d55b..e9eb07d2 100644 --- a/.github/workflows/copilot-workshops-sync.md +++ b/.github/workflows/copilot-workshops-sync.md @@ -18,7 +18,7 @@ safe-outputs: # Copilot Workshops Content Sync -You are a documentation sync agent for the **awesome-copilot** Learning Hub. Your job is to keep the **Copilot Workshops** mirror aligned with its upstream source course, and to perform the **initial import** if the mirror does not exist yet. +You are a documentation sync agent for the **awesome-copilot** Learning Hub. Your job is to keep the **Copilot Workshops** mirror aligned with its upstream source course. The mirror already exists — your runs are always **incremental**. ## Source of truth @@ -103,15 +103,18 @@ Navigation is wired in three places: ## Step 1 — Determine what's new upstream +> [!IMPORTANT] +> The **initial import has already been completed manually** (seeded from `github-samples/copilot-workshops@b543d2fe8cc7454d9118b094f168f7a0dd818b4a`), because a full first-run import exceeds the maximum number of files a safe-output pull request can contain. Treat the mirror as existing, and only ever produce **incremental** updates from here on. If the mirror ever appears to be missing entirely, do **not** attempt to recreate it in a single run — call the `noop` safe output with an explanation so a human can re-seed it manually. + 1. Read `cache-memory` and look for a file named `copilot-workshops-sync-state.json`. It may contain: - `last_synced_sha` — the most recent commit SHA you processed on your previous run - `last_synced_at` — a filesystem-safe timestamp in the format `YYYY-MM-DD-HH-MM-SS` 2. Use GitHub tools to fetch recent commits from `github-samples/copilot-workshops` on the `main` branch: - If `last_synced_sha` exists, list commits **since that SHA** (stop once you reach it). - - If no cached state exists, treat this as a **first run**: you will perform a full initial import (see Step 4), so gather the full current state of the upstream `docs/` tree rather than a commit delta. + - If no cached state exists, use `b543d2fe8cc7454d9118b094f168f7a0dd818b4a` (the seed commit for the manual initial import) as the baseline and list commits since then. -3. Identify which files changed (or, on a first run, which files exist). Focus on: +3. Identify which files changed. Focus on: - Markdown files under `docs/` — the landing `README.md`, harness overview `README.md` files, per-lesson `-*.md` files, and their localized equivalents under `docs//` - Supporting assets in `docs/_images/` - Any change to harness structure, lesson order, or lesson titles @@ -146,7 +149,10 @@ If the mirror already exists and is fully consistent with upstream — or the up ## Step 4 — Update (or create) the Learning Hub files -Edit the local docs, assets, and navigation so the website remains a **source-faithful mirror** of the upstream course. On a **first run**, create the full mirror from scratch: all four harness folders, every lesson, the landing page, all referenced images, every localized page that exists upstream, and the navigation wiring. +Edit the local docs, assets, and navigation so the website remains a **source-faithful mirror** of the upstream course. The full mirror already exists, so scope each run to the files that upstream actually changed — do not rewrite untouched pages just to bump `lastUpdated`. + +> [!WARNING] +> A safe-output pull request can contain at most **100 changed files**. If your analysis identifies more than that, do not attempt the whole update in one run. Instead, apply the highest-value subset (prioritize English pages, then images, then localizations), stay comfortably under the limit, and clearly state in the PR body which upstream changes were deferred so the next scheduled run can pick them up. Do **not** advance `last_synced_sha` past a commit whose changes you deferred. ### File mapping rules @@ -204,7 +210,7 @@ Write an updated `copilot-workshops-sync-state.json` to `cache-memory` with: Create a pull request with your changes using the `create-pull-request` safe output. Use `main` as the base branch for all work related to this workflow. The PR body must include: -1. **What changed upstream** — a concise summary of the commits and file changes found in `github-samples/copilot-workshops` (or, on a first run, a note that this is the initial import of the workshop) +1. **What changed upstream** — a concise summary of the commits and file changes found in `github-samples/copilot-workshops` 2. **What was updated locally** — list each mirrored Learning Hub file or asset you created or edited and what changed, including any navigation wiring and any localized pages 3. **Source links** — links to the relevant upstream files or commits on `main` 4. A note that the markdown body of this workflow can be edited directly on GitHub.com without recompilation @@ -220,6 +226,7 @@ If there is nothing to change after your analysis, do **not** open a PR. Instead - Preserve GitHub admonition syntax exactly; the site renders it natively. - Only mirror localized files that actually exist upstream; rely on Starlight's fallback for the rest, and never fabricate translations. - Keep the course source-faithful; avoid summaries or interpretive rewrites. +- The repository runs `codespell` in CI. Localized locale directories are already excluded in `.codespellrc`, but a new upstream English page may still trip a false positive on a valid word. **Never edit mirrored prose to satisfy the spell checker** — add the word to `ignore-words-list` in `.codespellrc` (with a comment explaining why) as part of the same PR. - Do not auto-merge; the PR is for human review. - If you are uncertain whether an upstream change warrants a Learning Hub update, err on the side of creating the PR — a human reviewer can always decline. - Always call either `create-pull-request` or `noop` at the end of your run so the workflow clearly signals its outcome. diff --git a/website/astro.config.mjs b/website/astro.config.mjs index b9d80718..6c11bef2 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -154,6 +154,82 @@ export default defineConfig({ "learning-hub/cli-for-beginners/07-putting-it-all-together", ], }, + { + label: "Copilot Workshops", + items: [ + { + label: "Overview", + link: "/learning-hub/copilot-workshops/", + }, + { + label: "VS Code", + items: [ + { + label: "Overview", + link: "/learning-hub/copilot-workshops/vscode/", + }, + "learning-hub/copilot-workshops/vscode/0-prerequisites", + "learning-hub/copilot-workshops/vscode/1-custom-instructions", + "learning-hub/copilot-workshops/vscode/2-agent-mode", + "learning-hub/copilot-workshops/vscode/3-mcp", + "learning-hub/copilot-workshops/vscode/4-custom-agents", + "learning-hub/copilot-workshops/vscode/5-managing-agents", + "learning-hub/copilot-workshops/vscode/6-iterating", + ], + }, + { + label: "Copilot CLI", + items: [ + { + label: "Overview", + link: "/learning-hub/copilot-workshops/cli/", + }, + "learning-hub/copilot-workshops/cli/0-prerequisites", + "learning-hub/copilot-workshops/cli/1-install-copilot-cli", + "learning-hub/copilot-workshops/cli/2-custom-instructions", + "learning-hub/copilot-workshops/cli/3-generating-code", + "learning-hub/copilot-workshops/cli/4-mcp", + "learning-hub/copilot-workshops/cli/5-agent-skills", + "learning-hub/copilot-workshops/cli/6-custom-agents", + "learning-hub/copilot-workshops/cli/7-slash-commands", + "learning-hub/copilot-workshops/cli/8-review", + ], + }, + { + label: "Copilot App", + items: [ + { + label: "Overview", + link: "/learning-hub/copilot-workshops/app/", + }, + "learning-hub/copilot-workshops/app/0-prerequisites", + "learning-hub/copilot-workshops/app/1-install-copilot-app", + "learning-hub/copilot-workshops/app/2-add-star-rating", + "learning-hub/copilot-workshops/app/3-custom-instructions", + "learning-hub/copilot-workshops/app/4-build-filtering", + "learning-hub/copilot-workshops/app/5-mcp-playwright", + "learning-hub/copilot-workshops/app/6-agent-merge", + "learning-hub/copilot-workshops/app/7-canvases", + "learning-hub/copilot-workshops/app/8-review", + ], + }, + { + label: "Copilot Cloud Agent", + items: [ + { + label: "Overview", + link: "/learning-hub/copilot-workshops/cloud/", + }, + "learning-hub/copilot-workshops/cloud/0-prerequisites", + "learning-hub/copilot-workshops/cloud/1-custom-instructions", + "learning-hub/copilot-workshops/cloud/2-cloud-agent", + "learning-hub/copilot-workshops/cloud/3-custom-agents", + "learning-hub/copilot-workshops/cloud/4-managing-agents", + "learning-hub/copilot-workshops/cloud/5-iterating", + ], + }, + ], + }, { label: "Hands-on", items: [ diff --git a/website/public/images/learning-hub/copilot-workshops/app-0-create-repository.png b/website/public/images/learning-hub/copilot-workshops/app-0-create-repository.png new file mode 100644 index 00000000..34913187 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-0-create-repository.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-0-use-template.png b/website/public/images/learning-hub/copilot-workshops/app-0-use-template.png new file mode 100644 index 00000000..cf02650d Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-0-use-template.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-2-review-panel.png b/website/public/images/learning-hub/copilot-workshops/app-2-review-panel.png new file mode 100644 index 00000000..95006ea5 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-2-review-panel.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-2-start-session.png b/website/public/images/learning-hub/copilot-workshops/app-2-start-session.png new file mode 100644 index 00000000..b06d71ec Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-2-start-session.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-4-plan-mode.png b/website/public/images/learning-hub/copilot-workshops/app-4-plan-mode.png new file mode 100644 index 00000000..1eaea46f Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-4-plan-mode.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-agent-merge-merge.png b/website/public/images/learning-hub/copilot-workshops/app-agent-merge-merge.png new file mode 100644 index 00000000..03ec3689 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-agent-merge-merge.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-enable-agent-merge.png b/website/public/images/learning-hub/copilot-workshops/app-enable-agent-merge.png new file mode 100644 index 00000000..47462d47 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-enable-agent-merge.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-new-session-from-issue.png b/website/public/images/learning-hub/copilot-workshops/app-new-session-from-issue.png new file mode 100644 index 00000000..26db5be2 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-new-session-from-issue.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-select-changes.png b/website/public/images/learning-hub/copilot-workshops/app-select-changes.png new file mode 100644 index 00000000..ebfc5c94 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-select-changes.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-show-folder-view.png b/website/public/images/learning-hub/copilot-workshops/app-show-folder-view.png new file mode 100644 index 00000000..122982d5 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-show-folder-view.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/app-terminal-screenshot.png b/website/public/images/learning-hub/copilot-workshops/app-terminal-screenshot.png new file mode 100644 index 00000000..7e7514d6 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/app-terminal-screenshot.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/cli-7-context-window.png b/website/public/images/learning-hub/copilot-workshops/cli-7-context-window.png new file mode 100644 index 00000000..36298511 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/cli-7-context-window.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex0-code-button.png b/website/public/images/learning-hub/copilot-workshops/ex0-code-button.png new file mode 100644 index 00000000..7044ef53 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex0-code-button.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex0-create-codespace.png b/website/public/images/learning-hub/copilot-workshops/ex0-create-codespace.png new file mode 100644 index 00000000..1ff8f3f6 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex0-create-codespace.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex0-repository-settings.png b/website/public/images/learning-hub/copilot-workshops/ex0-repository-settings.png new file mode 100644 index 00000000..a9b15f84 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex0-repository-settings.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex0-use-template.png b/website/public/images/learning-hub/copilot-workshops/ex0-use-template.png new file mode 100644 index 00000000..82c860f4 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex0-use-template.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex1-copilot-authentication.png b/website/public/images/learning-hub/copilot-workshops/ex1-copilot-authentication.png new file mode 100644 index 00000000..02ee9498 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex1-copilot-authentication.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex1-mcp-diagram.png b/website/public/images/learning-hub/copilot-workshops/ex1-mcp-diagram.png new file mode 100644 index 00000000..f00c7a10 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex1-mcp-diagram.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-explores.png b/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-explores.png new file mode 100644 index 00000000..396dbce2 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-explores.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-proposed-changes.png b/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-proposed-changes.png new file mode 100644 index 00000000..cde3f7ef Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-proposed-changes.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-run-tests.png b/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-run-tests.png new file mode 100644 index 00000000..32e4e1ad Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex3-agent-mode-run-tests.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex3-select-instructions-file.png b/website/public/images/learning-hub/copilot-workshops/ex3-select-instructions-file.png new file mode 100644 index 00000000..3510732f Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex3-select-instructions-file.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex3-source-control-changes.png b/website/public/images/learning-hub/copilot-workshops/ex3-source-control-changes.png new file mode 100644 index 00000000..ed6fe869 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex3-source-control-changes.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex4-assign-copilot-details.png b/website/public/images/learning-hub/copilot-workshops/ex4-assign-copilot-details.png new file mode 100644 index 00000000..fc77d3cb Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex4-assign-copilot-details.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex4-issue-eyes-emoji.png b/website/public/images/learning-hub/copilot-workshops/ex4-issue-eyes-emoji.png new file mode 100644 index 00000000..c3356969 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex4-issue-eyes-emoji.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex4-view-session.png b/website/public/images/learning-hub/copilot-workshops/ex4-view-session.png new file mode 100644 index 00000000..87e58d13 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex4-view-session.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex5-select-custom-agent.png b/website/public/images/learning-hub/copilot-workshops/ex5-select-custom-agent.png new file mode 100644 index 00000000..8de31865 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex5-select-custom-agent.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex6-accessibility-session.png b/website/public/images/learning-hub/copilot-workshops/ex6-accessibility-session.png new file mode 100644 index 00000000..e1444dc0 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex6-accessibility-session.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex6-steer-cloud-agent-task.png b/website/public/images/learning-hub/copilot-workshops/ex6-steer-cloud-agent-task.png new file mode 100644 index 00000000..b32ef396 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex6-steer-cloud-agent-task.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex7-back-to-pr.png b/website/public/images/learning-hub/copilot-workshops/ex7-back-to-pr.png new file mode 100644 index 00000000..ae3890e8 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex7-back-to-pr.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/ex7-ready-for-review.png b/website/public/images/learning-hub/copilot-workshops/ex7-ready-for-review.png new file mode 100644 index 00000000..c5a7a947 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/ex7-ready-for-review.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/shared-approve-workflows.png b/website/public/images/learning-hub/copilot-workshops/shared-approve-workflows.png new file mode 100644 index 00000000..5b089958 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/shared-approve-workflows.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/shared-assign-copilot.png b/website/public/images/learning-hub/copilot-workshops/shared-assign-copilot.png new file mode 100644 index 00000000..140db5de Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/shared-assign-copilot.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/shared-chat-mode-selector.png b/website/public/images/learning-hub/copilot-workshops/shared-chat-mode-selector.png new file mode 100644 index 00000000..9699f9b5 Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/shared-chat-mode-selector.png differ diff --git a/website/public/images/learning-hub/copilot-workshops/shared-pr-files-changed.png b/website/public/images/learning-hub/copilot-workshops/shared-pr-files-changed.png new file mode 100644 index 00000000..f3ea727c Binary files /dev/null and b/website/public/images/learning-hub/copilot-workshops/shared-pr-files-changed.png differ diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/0-prerequisites.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/0-prerequisites.md new file mode 100644 index 00000000..54d4cfa8 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "Lección 0 - Requisitos previos" +description: "Prepara el entorno para las lecciones de la aplicación GitHub Copilot: instala Node.js para el proyecto Tailspin Toys y crea tu propia copia del repositorio a partir de la plantilla." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +La aplicación GitHub Copilot es una aplicación de escritorio que actúa como centro de operaciones tanto para Copilot como para GitHub. Proporciona acceso rápido a incidencias y solicitudes de incorporación de cambios y, por supuesto, permite desarrollar con GitHub Copilot. Durante este taller trabajarás en local con la aplicación Tailspin Toys, creada con Astro, y con la aplicación GitHub Copilot. Antes de empezar, vamos a comprobar que Node.js esté instalado en local y, después, instalaremos la aplicación Copilot. + +En esta lección: + +- instalarás Node.js para poder ejecutar las pruebas del proyecto en tu equipo. +- crearás tu propia copia del proyecto Tailspin Toys a partir de la plantilla. + +## Instalar Node.js + +En varias lecciones se pide a un agente que desarrolle funcionalidades y ejecute en local el conjunto de pruebas de Tailspin Toys, para lo que se necesita [**Node.js**][nodejs], el único entorno de ejecución que requiere el proyecto. Instala la versión **22 o posterior**; la versión **LTS** actual es una opción segura. + +La opción más sencilla en cualquier plataforma es usar el instalador oficial: + +1. En el sistema operativo, abre una ventana de terminal con Windows Terminal, Terminal de macOS o la aplicación que utilices habitualmente. +2. Ejecuta el comando siguiente para confirmar que tienes instalada la versión 22 de Node.js o una posterior: + + ```shell + node --version + ``` + +3. Si aparece `v22` o un número superior, puedes pasar a la sección siguiente. + +> [!TIP] +> Solo tienes que completar estos pasos si no tienes Node instalado o si necesitas actualizarlo. + +4. Abre la [página de descarga de Node.js][node-download]. +5. Descarga la versión **LTS** correspondiente a tu sistema operativo. +6. Ejecuta el instalador y acepta las opciones predeterminadas. En Windows, mantén seleccionada la opción **Add to PATH**. +7. Después de instalarlo, abre una nueva ventana de terminal. +8. Confirma la instalación en la nueva ventana de terminal mediante el comando siguiente: + + ```bash + node --version + ``` + +9. Debería aparecer `v22.x.x` o una versión posterior. + +> [!TIP] +> ¿Prefieres usar contenedores? Si tienes [**Docker**][docker], puedes utilizar el [contenedor de desarrollo][dev-containers] del repositorio en lugar de instalar Node.js en local; el contenedor ya incluye Node. No necesitas ambas opciones. + +## Configurar el repositorio del laboratorio + +Trabajarás con tu propia copia del proyecto Tailspin Toys. Créala ahora a partir del [repositorio de plantilla][template-repository]. El nuevo repositorio contiene todos los archivos necesarios para el laboratorio y lo conectarás a la aplicación en la siguiente lección. + +1. En una nueva ventana del navegador, ve al repositorio de GitHub de este laboratorio: `https://github.com/github-samples/tailspin-toys`. +2. Para crear tu propia copia del repositorio, selecciona el botón **Use this template** en la página del repositorio del laboratorio. A continuación, selecciona **Create a new repository**. + + ![Botón Use this template con la opción Create a new repository seleccionada en el menú desplegable](/images/learning-hub/copilot-workshops/app-0-use-template.png) + +3. Si realizas el taller como parte de un evento dirigido por GitHub o Microsoft, sigue las instrucciones de los mentores. De lo contrario, puedes crear el nuevo repositorio en una organización en la que tengas acceso a GitHub Copilot. + + ![Formulario Create a new repository con github-samples/tailspin-toys como plantilla y el nombre del repositorio completado](/images/learning-hub/copilot-workshops/app-0-create-repository.png) + +4. Anota la ruta del repositorio que has creado (**organization-or-user-name/repository-name**), ya que la utilizarás más adelante en el laboratorio. + +> [!NOTE] +> Al crear el repositorio a partir de la plantilla, se genera automáticamente una lista de incidencias de trabajo pendiente. Trabajarás con estas incidencias durante todo el taller; no necesitas crear ninguna. + +## Resumen y pasos siguientes + +Ya tienes el entorno preparado. Has instalado Node.js para poder compilar y probar el proyecto en tu equipo y has creado tu propia copia del repositorio Tailspin Toys a partir de la plantilla. + +A continuación, instalarás la aplicación GitHub Copilot, conectarás el repositorio que acabas de crear y conocerás el espacio de trabajo. Continúa con la [Lección 1 - Instalar la aplicación GitHub Copilot][next-lesson]. + +## Recursos + +- [Descargar Node.js][node-download] +- [Crear un repositorio a partir de una plantilla][template-repository] +- [Acerca de la aplicación GitHub Copilot][about-copilot-app] + +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/1-install-copilot-app/ +[nodejs]: https://nodejs.org/ +[node-download]: https://nodejs.org/en/download +[docker]: https://www.docker.com/products/docker-desktop/ +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/1-install-copilot-app.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/1-install-copilot-app.md new file mode 100644 index 00000000..69b6d437 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "Lección 1 - Instalar la aplicación GitHub Copilot" +description: "Instala la aplicación GitHub Copilot, conecta el repositorio que has creado a partir de la plantilla, familiarízate con el espacio de trabajo y prueba un chat rápido." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +La [**aplicación GitHub Copilot**][about-copilot-app] es una aplicación de escritorio para el desarrollo dirigido por agentes. Se basa en GitHub Copilot CLI y se integra de forma nativa con GitHub, por lo que los repositorios, las ramas y las canalizaciones de CI funcionan sin configuración adicional. Está diseñada para flujos de trabajo en los que diriges varios agentes en paralelo, cada uno en su propio espacio de trabajo aislado, en lugar de realizar todo el trabajo y automatizar las tareas repetitivas por tu cuenta. Con Node.js instalado y tu copia del proyecto preparada, el siguiente paso es instalar la aplicación y conectar ese repositorio. + +En esta lección: + +- instalarás la aplicación GitHub Copilot e iniciarás sesión. +- añadirás el proyecto a la aplicación desde su repositorio de GitHub. +- conocerás el espacio de trabajo, incluida la lista de trabajo pendiente que la plantilla ha creado para ti. +- probarás un chat rápido para obtener información sobre la propia aplicación. + +## Escenario + +Tu equipo está adoptando agentes de IA para abordar una lista creciente de trabajo pendiente. La aplicación Copilot ofrece un único lugar desde el que dirigir ese trabajo: seleccionar incidencias, ejecutar agentes, revisar cambios y combinar solicitudes de incorporación de cambios. En esta lección instalarás y conectarás la aplicación, y aprenderás a iniciar una conversación sobre el proyecto. + +> [!NOTE] +> Se requiere un plan de Copilot válido: Copilot Student o cualquier plan de pago (Pro, Pro+, Business o Enterprise). Si utilizas Copilot Business o Copilot Enterprise, el administrador debe habilitar la directiva **Copilot CLI** para que la aplicación funcione. + +## Instalar y configurar la aplicación GitHub Copilot + +Como cabe esperar, el primer paso para utilizar la aplicación GitHub Copilot es instalarla. Hay versiones disponibles para Windows, macOS y Linux. Vamos a instalar la aplicación, autenticarnos y añadir a ella nuestro repositorio de Tailspin Toys. + +1. En un navegador, abre la [página de inicio de la aplicación GitHub Copilot][download-app]. +2. Descarga la aplicación para tu plataforma e instálala siguiendo las instrucciones de la página. +3. Abre la aplicación después de instalarla. +4. Selecciona **Sign in to GitHub** y sigue las indicaciones para autenticarte. Si utilizas GitHub Enterprise Server, elige **Use GitHub Enterprise** e introduce la dirección del servidor cuando se solicite. +5. Después de autenticarte, se te pedirá que conectes los repositorios. Selecciona el repositorio de Tailspin Toys que acabas de crear, cuyo nombre debería ser `/tailspin-toys`. +6. Selecciona **Continue** para continuar con la incorporación. +7. Cuando se te pida que elijas un tema, selecciona el que más te guste y, después, selecciona **Finish**. + +> [!NOTE] +> Si tu copia de Tailspin Toys no aparece automáticamente en la lista, puedes añadirla tras completar el proceso de incorporación en la aplicación. Al finalizar, la aplicación Copilot mostrará la pantalla de inicio. Desde allí, selecciona **Choose from GitHub**, busca el repositorio por su nombre (\/tailspin-toys) y selecciónalo. El repositorio se añadirá a la aplicación Copilot. + +## Familiarizarse con el espacio de trabajo + +Con el proyecto conectado, dedica un momento a conocer el espacio de trabajo. La aplicación organiza todo en varias áreas de la barra lateral: + +- **Sessions**: donde los agentes realizan su trabajo. Cada sesión se ejecuta en su propio espacio de trabajo aislado, por lo que puedes ejecutar varias a la vez sin que sus cambios entren en conflicto. Iniciarás tu primera sesión en la siguiente lección. +- **Quick chats**: conversaciones ligeras para preguntas y lluvias de ideas que no necesitan una rama ni un espacio de trabajo propios. Probarás una al final de esta lección. +- **My work**: tus incidencias y solicitudes de incorporación de cambios, disponibles mediante la **integración nativa con GitHub** de la aplicación. Desde aquí puedes examinar y filtrar incidencias y solicitudes de incorporación de cambios, comprobar el estado de CI, iniciar una sesión a partir de una incidencia y revisar solicitudes de incorporación de cambios, todo ello sin salir de la aplicación. +- **Automations**: tareas de agente guardadas que se ejecutan según una programación o bajo demanda. Crearás una casi al final de este recorrido. + +### Localizar la lista de trabajo pendiente inicial + +Como la aplicación se integra de forma nativa con GitHub, el trabajo pendiente del repositorio aparece directamente en ella. Cuando creaste el repositorio a partir de la plantilla, se generó una lista de incidencias. Vamos a comprobar que esté disponible. + +1. Selecciona **My work** en la barra lateral. +2. La plantilla ha creado ocho incidencias en tu lista de trabajo pendiente. Este módulo se centra en las tres siguientes; confirma que puedes verlas: + + - Allow users to filter games by category and publisher + - Update our repository coding standards + - Implement pagination on the game list page + +3. Selecciona una incidencia para leer sus detalles. Cada incidencia también sirve como punto de partida para una sesión de agente. Más adelante iniciarás el trabajo desde estas incidencias. + +> [!NOTE] +> La lista de elementos de **My work** se filtra automáticamente para mostrar solo los elementos de los repositorios que has añadido a la aplicación Copilot. Para ver elementos de trabajo de otros repositorios, añádelos a la aplicación. + +## Probar un chat rápido + +Una buena forma de familiarizarse con la aplicación es utilizarla para conocer la *propia aplicación*, y un **chat rápido** es la herramienta adecuada. Los chats rápidos permiten formular una pregunta o plantear ideas sin crear una rama ni un árbol de trabajo, por lo que son perfectos para una consulta rápida y desechable que no requiere una sesión. + +1. En la barra lateral, selecciona **+** junto a **Quick chats** para abrir un chat nuevo. +2. Pregunta a la aplicación cómo funcionan sus sesiones: + + ```plaintext + How does the GitHub Copilot app use worktrees? + ``` + +3. Lee la respuesta en la vista de conversación. Verás que cada sesión se ejecuta en su propio árbol de trabajo de Git aislado, lo que permite ejecutar varios agentes en paralelo sin que sus cambios entren en conflicto. Puedes continuar la conversación o iniciar un chat nuevo en cualquier momento. + +## Resumen y pasos siguientes + +Has instalado la aplicación GitHub Copilot, conectado el proyecto y explorado el espacio de trabajo. Has aprendido a: + +- instalar la aplicación e iniciar sesión en GitHub. +- añadir un proyecto desde su repositorio de GitHub. +- familiarizarte con el espacio de trabajo y localizar la lista de trabajo pendiente inicial en **My work**. +- utilizar un chat rápido para formular una pregunta breve y desechable. + +A continuación, iniciarás tu primera sesión de agente y realizarás el primer cambio en el proyecto: mostrar una valoración por estrellas en las tarjetas de los juegos. Continúa con la [Lección 2 - Ejecutar tu primera sesión de agente][next-lesson]. + +## Recursos + +- [Acerca de la aplicación GitHub Copilot][about-copilot-app] +- [Introducción a la aplicación GitHub Copilot][getting-started] +- [Trabajar con sesiones de agente en la aplicación GitHub Copilot][agent-sessions] + +[ex0]: /es-es/learning-hub/copilot-workshops/app/0-prerequisites/ +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/2-add-star-rating/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[download-app]: https://gh.io/app \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/2-add-star-rating.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/2-add-star-rating.md new file mode 100644 index 00000000..88e16090 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "Lección 2 - Ejecutar tu primera sesión de agente" +description: "Inicia tu primera sesión de agente en la aplicación GitHub Copilot, realiza un pequeño cambio en las tarjetas de los juegos y combínalo como tu primera solicitud de incorporación de cambios." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +En la lección anterior recorriste el espacio de trabajo y utilizaste un chat rápido. Ahora es el momento de iniciar una **sesión de agente** y realizar el primer cambio en el proyecto. Será un cambio pequeño: los juegos ya tienen una valoración por estrellas en sus datos, pero las tarjetas de la página de inicio todavía no la muestran. Pedirás al agente que la muestre, revisarás el cambio y lo combinarás como tu primera solicitud de incorporación de cambios. + +En esta lección: + +- iniciarás una sesión de agente y aprenderás cómo se estructura. +- pedirás al agente que realice un cambio pequeño y específico en el proyecto. +- revisarás el cambio en la vista de diferencias del espacio de trabajo. +- ejecutarás la aplicación en local para confirmar el cambio en el navegador. +- abrirás y combinarás tu primera solicitud de incorporación de cambios. + +## Escenario + +Cada juego de Tailspin Toys puede tener una valoración por estrellas, que ya aparece en la página de detalles del juego. Sin embargo, las tarjetas de los juegos de la página de inicio solo muestran el título, la categoría, el editor y la descripción. Como ejercicio inicial, pedirás al agente que muestre la valoración existente en cada tarjeta. Es un cambio pequeño y autocontenido, perfecto para tu primera sesión. + +## Anatomía de una sesión + +Una **sesión** es una conversación con un agente que se ejecuta en su propio espacio de trabajo aislado. Cada sesión recibe un **árbol de trabajo y una rama de Git dedicados**, lo que permite ejecutar varias sesiones a la vez, por ejemplo, una para añadir una funcionalidad y otra para corregir un error, sin que sus cambios entren en conflicto. Las sesiones aparecen en la barra lateral agrupadas por repositorio; selecciona cualquiera de ellas para cambiar de sesión. + +Dentro de una sesión verás tres elementos: la **conversación** con el agente, la **actividad de las herramientas** del agente mientras explora y edita archivos, y la lista de **archivos modificados** con sus diferencias. + +## Iniciar una sesión y solicitar el cambio + +Vamos a iniciar una sesión nueva para comenzar a explorar el proyecto e implementar la funcionalidad. En una [lección anterior][prior-lesson] añadiste el proyecto desde su repositorio de GitHub. Crearemos una sesión nueva para ese repositorio y solicitaremos el cambio. + +1. Vuelve a la aplicación GitHub Copilot o ábrela. +2. Selecciona **Home screen**. +3. Comprueba que `tailspin-toys` esté seleccionado como repositorio. + + ![Cuadro de indicaciones de la aplicación GitHub Copilot con el selector de repositorio establecido en tailspin-toys y el selector de modelo debajo](/images/learning-hub/copilot-workshops/app-2-start-session.png) + +4. Utiliza la indicación siguiente para solicitar el cambio: + + ```plaintext + On the game cards, show each game's star rating. The Game type already includes a starRating field — it's a number out of 5, or null when a game hasn't been rated yet. Display it on each card in src/components/GameCard.astro, and when starRating is null show "No rating yet" instead. Keep the change small and don't restructure the card layout. + ``` + +> [!NOTE] +> Observa que la indicación contiene el nombre del archivo que Copilot debe actualizar. Aunque no es necesario especificar los archivos que Copilot debe incluir en su trabajo, orientarlo ayuda a que genere el código con rapidez y reduzca el uso de tokens. + +5. Selecciona Enter para enviar la indicación a Copilot. + +La aplicación Copilot comienza por crear un árbol de trabajo nuevo, una copia aislada del proyecto. Después explora el proyecto, localiza los archivos que debe actualizar para añadir la funcionalidad y crea el código necesario. Ya has añadido una nueva funcionalidad con la aplicación Copilot. + +## Revisar las diferencias + +Todos los cambios generados por IA deben revisarse antes de combinarlos, incluso los más pequeños. Vamos a explorar los cambios directamente en la aplicación Copilot. + +1. En la esquina superior derecha de la aplicación, selecciona **Toggle review panel**. Se abrirá la pantalla de diferencias con todos los cambios pendientes realizados por Copilot. + + ![Barra de herramientas superior de la aplicación GitHub Copilot con una flecha que señala el botón Toggle review panel situado a la derecha de Create PR](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. Deberías observar código añadido a `GameCard.astro`, el archivo principal que se utiliza para mostrar los detalles de los juegos. Debería ser similar al siguiente: un pequeño bloque que representa la valoración cuando existe y muestra "No rating yet" cuando `starRating` es `null`: + + ```astro + {game.starRating !== null ? ( + + ★ {game.starRating} / 5 + + ) : ( + + No rating yet + + )} + ``` + +> [!NOTE] +> Como Copilot, al igual que todas las herramientas de IA generativa, es probabilístico y no determinista, el código exacto puede variar respecto al ejemplo anterior. No obstante, debería ser relativamente parecido. + +## Comprobar los cambios + +No debemos limitarnos a leer el código y dar por hecho que funciona. También debemos probarlo visualmente. Para ello, iniciaremos la aplicación desde la terminal y confirmaremos que todo funciona. La aplicación Copilot incluye una terminal integrada. + +1. En el panel de revisión situado a la derecha de la aplicación Copilot, selecciona **Terminal**. Si no aparece el botón **Terminal**, selecciona **+** (con la etiqueta **Open in panel**) y, después, **Terminal**. + + ![Botón Terminal del panel de revisión de la aplicación GitHub Copilot](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +2. Introduce el comando siguiente en la ventana de terminal para iniciar el servidor de desarrollo de la aplicación web: + + ```shell + npm run dev + ``` + +3. Cuando se inicie el servidor, lo que solo tardará un momento, abre una ventana del navegador. +4. Ve a http://localhost:4321. +5. Ahora deberías ver valoraciones por estrellas en todos los juegos de la página de inicio. +6. Vuelve a la ventana de terminal. +7. Selecciona Ctrl+C para detener el servidor de desarrollo. + +## Abrir y combinar tu primera solicitud de incorporación de cambios + +El cambio tiene buen aspecto; ha llegado el momento de publicarlo. Pedirás al agente que abra una solicitud de incorporación de cambios y, después, la revisarás y combinarás en github.com. Por ahora, gestionarás este proceso de forma manual. En una próxima lección descubrirás cómo Copilot puede encargarse automáticamente de parte del trabajo. + +1. En la esquina superior derecha, selecciona **Create PR**. +2. Si se solicita, selecciona **Sign in with your browser** y sigue las indicaciones para autenticarte. +3. Copilot comenzará a crear la solicitud de incorporación de cambios. + +Una vez creada, Copilot supervisará los flujos de trabajo del repositorio que deban ejecutarse. Después de unos instantes, el botón de la esquina superior derecha cambiará a **Ready to merge**. Esto indica que la solicitud está lista para combinarse. + +4. Selecciona la burbuja **PR** situada justo encima del chat para abrir la solicitud en el panel de revisión. Puedes revisarla aquí según sea necesario. +5. Cuando esté lista, selecciona **Ready to merge**. +6. Selecciona **Merge pull request** en el nuevo cuadro de diálogo para combinar la solicitud. + +Ya has publicado una nueva funcionalidad en el sitio web. + +## Resumen y pasos siguientes + +Has iniciado tu primera sesión de agente y publicado tu primer cambio. En concreto: + +- has iniciado una sesión de agente y aprendido cómo se estructuran las sesiones. +- has indicado al agente que realice un cambio pequeño y específico en las tarjetas de los juegos. +- has revisado el cambio en la vista de diferencias del espacio de trabajo. +- has ejecutado la aplicación en local para confirmar la valoración por estrellas en el navegador. +- has abierto una solicitud de incorporación de cambios y la has combinado personalmente en github.com. + +A continuación, utilizarás la aplicación para añadir al repositorio un estándar de instrucciones personalizadas a partir de una de las incidencias de la lista de trabajo pendiente. Continúa con la [Lección 3 - Guiar a Copilot con instrucciones personalizadas][next-lesson]. + +## Recursos + +- [Trabajar con sesiones de agente en la aplicación GitHub Copilot][agent-sessions] +- [Acerca de la aplicación GitHub Copilot][about-copilot-app] +- [Gestionar incidencias y solicitudes de incorporación de cambios con la aplicación GitHub Copilot][managing-issues-prs] + +[prior-lesson]: /es-es/learning-hub/copilot-workshops/app/1-install-copilot-app/#instalar-y-configurar-la-aplicacion-github-copilot +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/3-custom-instructions/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/3-custom-instructions.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/3-custom-instructions.md new file mode 100644 index 00000000..62cd6443 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "Lección 3 - Guiar a Copilot con instrucciones personalizadas" +description: "Utiliza la aplicación GitHub Copilot para añadir al repositorio un estándar de instrucciones personalizadas a partir de una incidencia de la lista de trabajo pendiente y combina el cambio como una solicitud de incorporación de cambios." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +El contexto es fundamental al trabajar con IA generativa. Si una tarea debe realizarse de una forma concreta o Copilot necesita conocer información de fondo, conviene que ese contexto esté disponible. Una de las herramientas más potentes para proporcionarlo son los [archivos de instrucciones][instruction-files], que describen no solo *qué* código quieres, sino también *cómo* debe estructurarse. En esta lección añadirás un estándar de documentación al repositorio y lo harás como realizarás la mayor parte del trabajo a partir de ahora: comenzarás desde una incidencia de la lista de trabajo pendiente y dejarás que el agente realice el cambio. + +En esta lección: + +- explorarás cómo llegan al agente las instrucciones del repositorio y los archivos de instrucciones limitados por ruta. +- iniciarás una sesión desde la incidencia sobre instrucciones de la lista de trabajo pendiente. +- pedirás al agente que añada un estándar de documentación a `.github/copilot-instructions.md`. +- revisarás el cambio y lo combinarás como una solicitud de incorporación de cambios. + +## Escenario + +Como cualquier buen equipo de desarrollo, Tailspin Toys dispone de directrices y requisitos para las prácticas de desarrollo. Entre ellos se incluyen: + +- Se debe añadir documentación al código mediante comentarios de documentación TSDoc. +- El formato se debe documentar y aplicar mediante linting. + +Mediante los archivos de instrucciones, garantizarás que Copilot disponga de la información adecuada para realizar las tareas conforme a estas prácticas. + +## Archivos de instrucciones + +Las instrucciones personalizadas permiten proporcionar contexto y preferencias a Copilot para que comprenda mejor el estilo y los requisitos de programación. Esta potente funcionalidad ayuda a orientar a Copilot para obtener sugerencias y fragmentos de código más pertinentes. Puedes especificar las convenciones de programación, las bibliotecas e incluso los tipos de comentarios que prefieres incluir en el código. También puedes crear instrucciones para todo el repositorio o para tipos de archivo concretos, con contexto específico para una tarea. + +Hay dos tipos de archivos de instrucciones: + +- `.github/copilot-instructions.md`, un único archivo de instrucciones que se envía a Copilot con **cada** solicitud del repositorio. Debe contener información del proyecto que sea pertinente para la mayoría de las solicitudes de chat o CLI enviadas a Copilot, como la pila tecnológica, una descripción general de lo que se está creando, procedimientos recomendados y otras directrices globales. +- Los archivos `.github/instructions/*.instructions.md` se pueden crear para tareas o tipos de archivo concretos. Puedes utilizarlos para proporcionar directrices para lenguajes específicos, como TypeScript o Astro, o para tareas como crear un componente de interfaz de usuario o un nuevo conjunto de pruebas unitarias. + +> [!NOTE] +> Copilot admite otros estándares para incorporar instrucciones mediante AGENTS.md, CLAUDE.md y GEMINI.md, de modo que siempre disponga del contexto adecuado. + +### Procedimientos recomendados para gestionar archivos de instrucciones + +Una explicación completa sobre la creación de archivos de instrucciones queda fuera del alcance del taller. No obstante, los ejemplos del proyecto de muestra presentan un enfoque representativo. En términos generales: + +- Mantén las instrucciones de `copilot-instructions.md` centradas en directrices de ámbito de proyecto, como una descripción de lo que se está creando, la estructura del proyecto y los estándares globales de programación. +- Utiliza archivos `*.instructions.md` para proporcionar instrucciones específicas para tipos de archivo, como pruebas unitarias, componentes de Astro o la capa de datos, o para tareas concretas. +- Utiliza lenguaje natural. Redacta directrices claras. Proporciona ejemplos de cómo debe y no debe ser el código. + +No existe una única forma de crear archivos de instrucciones, del mismo modo que no existe una única forma de utilizar la IA. La experimentación te permitirá descubrir qué funciona mejor para tu proyecto. + +> [!TIP] +> Todos los proyectos que utilicen GitHub Copilot deberían disponer de una colección sólida de archivos de instrucciones. Al explorar los de este proyecto, observarás que hay archivos de instrucciones para muchos tipos de archivos de código. +> +> ¿Buscas plantillas o un punto de partida? Explora [Awesome Copilot][awesome-copilot], un repositorio repleto de archivos de instrucciones, agentes personalizados y otros recursos. + +## Explorar los archivos de instrucciones personalizadas del proyecto + +Dedica un momento a leer los archivos de instrucciones incluidos en este repositorio: hay un archivo principal `copilot-instructions.md` y una colección de archivos `*.instructions.md` para distintas tareas. Ábrelos en el editor o en la interfaz web de GitHub. + +1. Si el panel de revisión aún no está visible, selecciona **Toggle review panel** en la esquina superior derecha para abrirlo. + + ![Barra de herramientas superior de la aplicación GitHub Copilot con una flecha que señala el botón Toggle review panel situado a la derecha de Create PR](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. Selecciona **+** para añadir un elemento nuevo al panel de revisión. +3. Selecciona **File**. +4. Busca `copilot-instructions.md`. +5. Selecciona `copilot-instructions.md` en la lista de archivos para abrirlo. +6. Explora el archivo. Observa la breve descripción del proyecto y secciones como **Agent notes**, **Code standards**, **Scripts** y **Repository Structure**. En **Code standards**, fíjate en las directrices anidadas de **GitHub Actions Workflows**. Se aplican a cualquier interacción con Copilot. +7. Selecciona **Show folder view** para abrir el navegador de carpetas. + + ![Botón Show folder view del panel de revisión con un archivo abierto en la aplicación GitHub Copilot](/images/learning-hub/copilot-workshops/app-show-folder-view.png) + +8. Ve a la carpeta `.github/instructions` y explora los archivos. Observa que hay instrucciones para archivos de Astro, la capa de datos de Drizzle, pruebas y otros elementos. +9. Abre `.github/instructions/unit-tests.instructions.md`. Observa el campo `applyTo` de la parte superior: establece un patrón glob, relativo a la raíz del repositorio, que determina a qué archivos se aplican las instrucciones. En este caso, coincidirá cualquier archivo de prueba de TypeScript, por ejemplo, uno que cumpla `**/*.test.ts`. +10. Examina las instrucciones específicas para crear pruebas unitarias en este proyecto. +11. Por último, abre `.github/instructions/drizzle.instructions.md` y desplázate hasta el final. Observa los vínculos a otros archivos de instrucciones, como `unit-tests.instructions.md`, y a archivos existentes del proyecto. De este modo puedes dividir conjuntos de instrucciones grandes en archivos más pequeños y reutilizables, y señalar a Copilot ejemplos que debe seguir al generar código. Las rutas son relativas al archivo de instrucciones, no a la raíz del repositorio. + +> [!NOTE] +> La sección **Code formatting requirements** de `copilot-instructions.md` documenta los estándares de programación del proyecto, pero todavía no exige documentación dentro del código. En los pasos siguientes añadirás reglas para comentarios de documentación TSDoc y comentarios de cabecera de archivo. + +## Empezar desde la incidencia sobre instrucciones + +En la lección anterior iniciaste una sesión con una indicación directa. Sin embargo, la mayor parte del trabajo comienza con una incidencia. Vamos a crear una sesión basada en una incidencia presentada para actualizar los archivos de instrucciones y, después, solicitaremos la actualización. + +> [!NOTE] +> Como los archivos de instrucciones influyen mucho en el código que genera Copilot, debes asegurarte de que lo orienten con claridad. Pedir a Copilot que cree una primera versión, como harás en esta lección, es un buen enfoque, siempre que después la revises para confirmar que las actualizaciones cumplen tus requisitos. + +1. Selecciona **My work** en la barra lateral. +2. Selecciona la incidencia titulada **Update our repository coding standards** para abrirla. +3. Selecciona **New session** en la esquina superior derecha para iniciar una sesión basada en la incidencia. + + ![Vista de una incidencia en la aplicación GitHub Copilot con una flecha que señala el botón New session de la esquina superior derecha](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. Utiliza la indicación siguiente para pedir a Copilot que actualice los archivos de instrucciones de acuerdo con los requisitos documentados en la incidencia: + + ```plaintext + Following this issue, make the updates to the instructions files in this project to meet the requirements documented. Don't create the PR quite yet! + ``` + +Copilot realizará las actualizaciones. + +## Revisar el cambio + +Vamos a leer las actualizaciones de Copilot y también a pedirle un ejemplo del código que generará a partir de las instrucciones actualizadas. + +1. Selecciona **Changes** en la esquina superior derecha para abrir los cambios de código. + + ![Pestañas del panel de sesión de la aplicación GitHub Copilot con una flecha que señala la pestaña Changes](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. Revisa el archivo de instrucciones actualizado. Confirma que contiene las directrices para añadir documentación y comentarios al código. + +> [!NOTE] +> Como la IA es probabilística y no determinista, el texto exacto puede variar. + +3. Utiliza la indicación siguiente para pedir a Copilot que cree un ejemplo del código que generará ahora: + + ```plaintext + Do not make any updates, but show me what the code would look like. Based on the new instructions, if I asked Copilot to create a new library component to return all Publishers what would that code look like? + ``` + +4. Revisa el código que propone Copilot. Observa los comentarios de documentación TSDoc y el comentario de cabecera de archivo que incluye, exactamente lo que solicitan las instrucciones actualizadas. + +Ya has actualizado los archivos de instrucciones del proyecto y has comprobado el efecto que tendrán. + +## Abrir y combinar la solicitud de incorporación de cambios + +Los archivos de instrucciones pasan a ser recursos del repositorio y, por tanto, se comparten con el resto del equipo. Vamos a crear una solicitud de incorporación de cambios con nuestro trabajo, igual que haríamos con cualquier otro recurso. + +1. En la esquina superior derecha, selecciona **Create PR**. +2. Si se solicita, selecciona **Sign in with your browser** y sigue las indicaciones para autenticarte. +3. Copilot comenzará a crear la solicitud de incorporación de cambios. + +Una vez creada, Copilot supervisará los flujos de trabajo del repositorio que deban ejecutarse. Después de unos instantes, el botón de la esquina superior derecha cambiará a **Ready to merge**. Esto indica que la solicitud está lista para combinarse. + +4. Selecciona **Ready to merge**. +5. Selecciona **Merge pull request** en el nuevo cuadro de diálogo para combinar la solicitud. + +> [!NOTE] +> Una vez combinado el estándar en la rama predeterminada, pasa a formar parte del proyecto para todo el equipo y para cada sesión nueva. Cuando inicies la sesión de filtrado de la siguiente lección desde una rama predeterminada actualizada, el agente seguirá este estándar automáticamente. Verás que el código TypeScript que genera incluye comentarios de documentación TSDoc sin que se lo pidas: una demostración pequeña pero real de cómo las instrucciones determinan el código generado. + +## Resumen y pasos siguientes + +Has explorado cómo la aplicación obtiene contexto de los archivos de instrucciones y, después, has utilizado una sesión para añadir y combinar un estándar para todo el repositorio. En concreto: + +- has explorado el archivo `copilot-instructions.md` del repositorio y los archivos `*.instructions.md` limitados por ruta. +- has iniciado una sesión desde la incidencia sobre instrucciones de la lista de trabajo pendiente. +- has pedido al agente que añada un estándar de documentación a `.github/copilot-instructions.md`. +- has revisado el cambio y lo has combinado como una solicitud de incorporación de cambios. + +A continuación, crearás la funcionalidad de filtrado en una sesión nueva y comprobarás cómo adopta el estándar que acabas de combinar. Continúa con la [Lección 4 - Crear una funcionalidad con Autopilot][next-lesson]. + +## Recursos + +- [Archivos de instrucciones para personalizar GitHub Copilot][instruction-files] +- [Personalizar la aplicación GitHub Copilot][customize-app] +- [Procedimientos recomendados para crear instrucciones personalizadas][instructions-best-practices] +- [Awesome Copilot: colección de archivos de instrucciones y otros recursos][awesome-copilot] + +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/4-build-filtering/ +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[awesome-copilot]: https://awesome-copilot.github.com/ +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/4-build-filtering.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/4-build-filtering.md new file mode 100644 index 00000000..613a1c86 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "Lección 4 - Crear una funcionalidad con Autopilot" +description: "Utiliza los modos Plan y Autopilot de la aplicación GitHub Copilot para crear una funcionalidad de filtrado estática en el cliente, comprobar que hereda el estándar de documentación y verificarla con una habilidad de agente." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Hasta ahora hemos realizado un par de pequeñas actualizaciones en el proyecto. Sin embargo, los cambios más amplios requieren un proceso más sólido. La aplicación GitHub Copilot está diseñada para integrarse en nuestro flujo actual y garantizar que creemos lo correcto de la forma adecuada. Esta es la primera de tres lecciones en las que seguirás un proceso de desarrollo habitual: empezarás por utilizar una incidencia para generar una funcionalidad nueva y una habilidad de agente para ejecutar las pruebas de validación y los linters. + +En esta lección: + +- iniciarás una sesión nueva desde la incidencia sobre filtrado. +- utilizarás el modo **Plan** para planificar la funcionalidad y, después, **Autopilot** para crearla. +- confirmarás que el código generado sigue el estándar de documentación que combinaste anteriormente. +- verificarás el trabajo con la habilidad `quality-checks` del proyecto. + +## Escenario + +La página de inicio muestra todos los juegos, pero los visitantes no pueden restringir la lista. La incidencia sobre filtrado solicita que puedan filtrar los juegos por **categoría** y **editor**. Vamos a utilizar Copilot para implementar esta funcionalidad. + +## Contexto + +Introducir agentes de programación con IA en el flujo de desarrollo no cambia los principios fundamentales. De hecho, adquieren aún más importancia. La mayoría de los desarrolladores siguen un flujo similar al siguiente: + +1. Abrir una incidencia que detalle lo que debe hacerse. +2. Crear un plan de lo que debe desarrollarse. +3. Crear y revisar el código. +4. Ejecutar las pruebas para validar el código. +5. Validar manualmente la nueva funcionalidad. +6. Crear una solicitud de incorporación de cambios (PR). +7. Una vez revisado el código y completado correctamente el proceso de integración continua, combinarlo. + +> [!NOTE] +> Los detalles concretos variarán según el equipo y la organización, pero la mayoría de los procesos serán una variante del flujo anterior. + +Al mantener este enfoque estándar, te aseguras de que el código generado por IA cumpla los requisitos establecidos y pase por el mismo proceso de validación que el código escrito manualmente. + +## Modos de sesión + +El **modo de sesión** controla el grado de autonomía del agente. Puedes establecerlo en el menú desplegable situado debajo del campo de indicaciones y cambiarlo en cualquier momento: + +- **Interactive**: trabajas junto con el agente. El agente sugiere cambios y espera tus indicaciones antes de continuar. +- **Plan**: el agente crea primero un plan. Revisas y apruebas el plan antes de que el agente lo ejecute. +- **Autopilot**: el agente trabaja de forma totalmente autónoma, escribe código, ejecuta pruebas e itera sin esperar indicaciones. + +## Planificar la funcionalidad de filtrado + +El mejor momento para detectar un posible problema es antes de escribir código, y una breve planificación previa es la mejor forma de hacerlo. Al planificar con Copilot, le pedirás que genere una serie de pasos y documente el enfoque que seguirá. Después podrás revisar el plan y proponer mejoras antes de permitir que Copilot genere el código a partir de él. + +Vamos a abrir la incidencia, iniciar una sesión nueva y crear un plan. Para ello, cambiaremos al modo Plan y enviaremos la solicitud. + +1. Selecciona **My work** en la pestaña de navegación. +2. Selecciona la incidencia titulada **Allow users to filter games by category and publisher**. +3. Selecciona **New session** en la esquina superior derecha. + + ![Vista de una incidencia en la aplicación GitHub Copilot con una flecha que señala el botón New session de la esquina superior derecha](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. Selecciona Shift+Tab hasta que el modo muestre **Plan**. + + ![Cuadro de indicaciones de la aplicación GitHub Copilot con una flecha que señala el selector de modo establecido en Plan](/images/learning-hub/copilot-workshops/app-4-plan-mode.png) + +5. Envía la indicación siguiente. La incidencia sobre filtrado ya está en el contexto de esta sesión porque la has iniciado desde ella: + + ```plaintext + Plan the work based on the requirements documented in the issue. Please ask any clarifying questions you might have as you build the plan. + ``` + +6. El agente puede plantear preguntas de seguimiento mientras crea el plan. Respóndelas según cómo desarrollarías la funcionalidad. + +> [!NOTE] +> Como Copilot es probabilístico, las preguntas de seguimiento exactas pueden variar. Incluso es posible que no formule ninguna. Es completamente normal. + +7. Cuando termine, Copilot ofrecerá un resumen del plan. Revísalo. Debería proponer crear consultas, añadir controles de filtrado y, por supuesto, pruebas. Si quieres, proporciona comentarios para perfeccionarlo; el agente incorporará las sugerencias en una versión nueva. + +## Crear la funcionalidad con Autopilot + +Con el plan preparado, vamos a dejar que Copilot cree la implementación. + +1. En la lista de opciones del cuadro de diálogo **Plan summary**, selecciona la opción más parecida a **Approve and implement with autopilot**. + +Copilot comenzará a trabajar en la implementación. + +> [!NOTE] +> Si Copilot no empieza a crear automáticamente el código necesario, puedes pedírselo con una indicación como "Go ahead and start building out the plan!". +> +> Las actualizaciones necesarias tardarán varios minutos. El agente edita y crea archivos, escribe y ejecuta pruebas e itera. Es un buen momento para repasar lo que has explorado hasta ahora o tomar algo. + +## Revisar los cambios + +Todo el código generado por IA debe revisarse antes de combinarlo. Vamos a revisar el código y ejecutar el sitio para comprobar que todo funciona correctamente. + +1. Selecciona **Changes** en la esquina superior derecha para abrir los cambios de código. + + ![Pestañas del panel de sesión de la aplicación GitHub Copilot con una flecha que señala la pestaña Changes](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. Revisa los cambios. Deberías ver nuevos archivos de TypeScript y Astro, además de archivos de prueba. Observa que las nuevas funciones auxiliares incluyen comentarios de documentación TSDoc y un comentario de cabecera de archivo: el estándar de documentación que combinaste en la Lección 3, aplicado automáticamente sin solicitarlo. +3. En el panel de revisión situado a la derecha de la aplicación Copilot, selecciona **Terminal**. Si no aparece el botón **Terminal**, selecciona **+** (con la etiqueta **Open in panel**) y, después, **Terminal**. + + ![Botón Terminal del panel de revisión de la aplicación GitHub Copilot](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +4. Introduce el comando siguiente en la ventana de terminal para iniciar el servidor de desarrollo de la aplicación web: + + ```shell + npm run dev + ``` + +5. Cuando se inicie el servidor, lo que solo tardará un momento, abre una ventana del navegador. +6. Ve a http://localhost:4321. +7. Ahora deberías ver filtros en la página de inicio. +8. Si algo no parece correcto, puedes pedir a Copilot que lo actualice. +9. Cuando estés conforme, vuelve a la ventana de terminal. +10. Selecciona Ctrl+C para detener el servidor de desarrollo. + +## Verificar el trabajo con la habilidad quality-checks + +Podrías revisar visualmente las diferencias y dar el trabajo por terminado, pero el equipo ha definido un nivel de calidad y una forma repetible de comprobarlo. + +Las **habilidades de agente** permiten proporcionar a Copilot directrices para realizar tareas repetibles, como ejecutar pruebas, generar compilaciones o crear solicitudes de incorporación de cambios. Una habilidad es una carpeta con instrucciones, scripts y recursos que el agente puede cargar bajo demanda. [Agent Skills es un estándar abierto][agent-skills-repo] que utilizan distintos agentes, por lo que la misma habilidad funciona en Copilot Chat en modo agente, el agente en la nube de Copilot, Copilot CLI y la aplicación GitHub Copilot. + +Las habilidades se almacenan en la carpeta `.github/skills` de un proyecto o de forma global en `~/.copilot/skills`. Cada habilidad es una carpeta que contiene un archivo `SKILL.md` con frontmatter YAML, formado por un `name` y una `description`, seguido de las instrucciones en Markdown: + +```yaml +--- +name: quality-checks +description: Run the project's test suites and linter to verify code changes are ready to commit, push, or merge. +--- +``` + +Las habilidades también pueden incluir subcarpetas con scripts, recursos y material de referencia. La estructura completa se describe en la [especificación de habilidades de agente][agent-skills-spec]. + +> [!TIP] +> Las habilidades se cargan de forma dinámica. El agente decide cuál se aplica según el campo `description`; una descripción clara y específica del escenario marca la diferencia entre una habilidad que se utiliza y otra que se ignora. + +## Explorar la habilidad quality-checks + +Vamos a explorar la habilidad para ver qué hace. + +1. Si el panel de revisión aún no está visible, selecciona **Toggle review panel** en la esquina superior derecha para abrirlo. + + ![Barra de herramientas superior de la aplicación GitHub Copilot con una flecha que señala el botón Toggle review panel situado a la derecha de Create PR](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. Selecciona **+** para añadir un elemento nuevo al panel de revisión. +3. Selecciona **File**. +4. Busca `SKILL.md`. +5. Selecciona `SKILL.md .github/skills/quality-checks` en la lista de archivos para abrirlo. +6. Observa los campos `name` y `description`. La descripción indica al agente *cuándo* debe utilizar la habilidad: siempre que sea necesario probar, analizar con un linter o verificar cambios de código antes de una confirmación, un envío o una combinación. +7. Lee la habilidad. Observa que documenta qué script ejecuta cada conjunto de pruebas, como las pruebas unitarias, las pruebas de un extremo a otro de Playwright y ESLint, en qué orden y cómo depurar errores habituales. Así, el agente ejecuta las comprobaciones según el proceso del equipo en lugar de adivinarlo. + +## Ejecutar las comprobaciones + +En la misma sesión de filtrado, pide al agente que verifique el trabajo. No mencionarás el nombre de la habilidad; el agente la identificará a partir de la solicitud. + +1. Vuelve a la aplicación Copilot. +2. Llama directamente a la habilidad mediante el comando de barra diagonal `/quality-checks` y selecciona Enter. +3. Siguiendo la habilidad, el agente ejecutará las pruebas unitarias, el linter y las pruebas de un extremo a otro, y comunicará los resultados. Si algo falla, pídele que corrija el problema y vuelva a ejecutar las comprobaciones hasta que todo se complete correctamente. +4. **Mantén abierta esta sesión.** En la siguiente lección añadirás el servidor MCP de Playwright y lo utilizarás para comprobar la funcionalidad de filtrado en un navegador real. + +## Resumen y pasos siguientes + +Has creado una funcionalidad real de principio a fin y la has verificado según el nivel de calidad del equipo. En concreto: + +- has iniciado una sesión nueva desde la incidencia sobre filtrado en un proyecto actualizado. +- has utilizado el modo Plan para planificar la funcionalidad y Autopilot para crearla. +- has confirmado que la función auxiliar generada sigue el estándar de documentación que combinaste en la Lección 3. +- has verificado el trabajo con la habilidad `quality-checks`. + +A continuación, conectarás el servidor MCP de Playwright y pedirás al agente que explore la funcionalidad de filtrado en un navegador real. Continúa con la [Lección 5 - Realizar pruebas con el servidor MCP de Playwright][next-lesson]. + +## Recursos + +- [Trabajar con sesiones de agente en la aplicación GitHub Copilot][agent-sessions] +- [Acerca de Agent Skills][about-agent-skills] +- [Personalizar la aplicación GitHub Copilot][customize-app] +- [Acerca de los entornos aislados locales y en la nube para GitHub Copilot][sandboxes] + +[ex0]: /es-es/learning-hub/copilot-workshops/app/0-prerequisites/ +[ex2]: /es-es/learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /es-es/learning-hub/copilot-workshops/app/3-custom-instructions/ +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/5-mcp-playwright/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[agent-skills-repo]: https://github.com/agentskills/agentskills +[agent-skills-spec]: https://agentskills.io/specification \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/5-mcp-playwright.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/5-mcp-playwright.md new file mode 100644 index 00000000..909a54d9 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "Lección 5 - Realizar pruebas con el servidor MCP de Playwright" +description: "Añade el servidor MCP de Playwright a la aplicación GitHub Copilot y pide al agente que pruebe manualmente la funcionalidad de filtrado en un navegador real." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +En la lección anterior creaste y verificaste la funcionalidad de filtrado con el conjunto de pruebas automatizadas del proyecto. Las pruebas automatizan la validación del código, pero permitir que el agente confirme el comportamiento también resulta muy útil. Así puede responder a los problemas que detecte en la interfaz de usuario que está creando. Vamos a explorar cómo MCP proporciona a los agentes de IA acceso a capacidades externas y a añadir el servidor MCP de Playwright para que Copilot pueda interactuar directamente con el sitio que estás desarrollando. + +En esta lección: + +- comprenderás qué es Model Context Protocol (MCP) y cómo lo utiliza la aplicación GitHub Copilot. +- añadirás el servidor MCP de Playwright desde la configuración de la aplicación. +- pedirás al agente que controle un navegador y explore la funcionalidad de filtrado. + +## Escenario + +Aunque las pruebas unitarias y de un extremo a otro son importantes, validar las actualizaciones de la interfaz de usuario requiere interactuar con ella. Quieres que Copilot pueda utilizar el sitio web en el que trabajas como lo haría un usuario para automatizar aún más los cambios y aumentar la confianza en que las actualizaciones funcionan según lo previsto. + +## ¿Qué es Model Context Protocol (MCP)? + +[Model Context Protocol (MCP)][mcp-blog-post] proporciona a los agentes de IA una forma de comunicarse con herramientas y servicios externos. Mediante MCP, los agentes de IA pueden comunicarse con ellos en tiempo real. Esto les permite acceder a información actualizada mediante recursos y realizar acciones en tu nombre mediante herramientas. + +Se accede a estas herramientas y recursos a través de un servidor MCP, que actúa como puente entre el agente de IA y las herramientas y servicios externos. El servidor MCP gestiona la comunicación entre el agente de IA y las herramientas externas, como API existentes o herramientas locales, por ejemplo, paquetes NPM. Cada servidor MCP representa un conjunto diferente de herramientas y recursos a los que puede acceder el agente de IA. + +Dos servidores MCP populares son: + +- [**GitHub MCP Server**](https://github.com/github/github-mcp-server): proporciona acceso a un conjunto de API para gestionar repositorios de GitHub. Permite al agente de IA realizar acciones como crear repositorios, actualizar los existentes y gestionar incidencias y solicitudes de incorporación de cambios. +- [**Playwright MCP Server**][playwright-mcp-server]: proporciona capacidades de automatización del navegador mediante Playwright. Permite al agente de IA realizar acciones como visitar páginas web, completar formularios y seleccionar botones. + +Hay muchos otros servidores MCP que proporcionan acceso a distintas herramientas y recursos. GitHub aloja un [registro de MCP](https://github.com/mcp) para facilitar su descubrimiento y las contribuciones al ecosistema. + +> [!CAUTION] +> Trata los servidores MCP como cualquier otra dependencia del proyecto. Antes de utilizar uno, revisa atentamente su código fuente, verifica el editor y considera las implicaciones de seguridad. Utiliza únicamente servidores MCP de confianza y ten cuidado al conceder acceso a recursos u operaciones confidenciales. + +## Añadir el servidor MCP de Playwright + +Los servidores MCP se añaden y gestionan desde la configuración de la aplicación. La aplicación incluye un catálogo de servidores populares, por lo que el [servidor MCP de Playwright][playwright-mcp-server] está a solo un par de selecciones. + +1. Selecciona Ctrl+, para abrir la página de configuración de la aplicación Copilot. +2. Selecciona **MCP servers**. +3. En el cuadro de búsqueda, escribe `Playwright`. +4. Selecciona **Playwright** en la lista de **Popular MCP servers**. +5. Selecciona **Add server** para añadirlo a la lista de servidores MCP disponibles. +6. Selecciona Esc para cerrar el cuadro de diálogo de configuración. + +Ya has añadido el servidor MCP de Playwright. + +## Pedir a Copilot que explore la funcionalidad mediante Playwright + +Vamos a pedir a Copilot que pruebe manualmente la funcionalidad mediante el servidor MCP de Playwright. + +1. Utiliza la indicación siguiente para pedir a Copilot que valide la nueva funcionalidad: + + ```plaintext + Start the dev server then use the Playwright MCP server to validate the functionality you just added exists. Use the details in the issue to ensure the newly added behavior matches the specs. + ``` + +Copilot iniciará un navegador mediante el servidor MCP de Playwright, recorrerá cada paso y comunicará lo que encuentre. Verás cómo abre un navegador en el sistema para realizar las tareas. + +2. Compara el resumen con los criterios de aceptación de la incidencia. Si algo no parece correcto, formula preguntas de seguimiento o pide al agente que corrija el código antes de abrir una solicitud de incorporación de cambios. +3. Mantén abierta esta sesión, ya que la completaremos en la siguiente lección. + +Copilot también ha validado la funcionalidad en el navegador mediante la exploración de la característica como lo haría un usuario. + +## Resumen y pasos siguientes + +Has utilizado el servidor MCP de Playwright para explorar la funcionalidad en un navegador real desde la aplicación GitHub Copilot. En resumen: + +- has aprendido qué es Model Context Protocol (MCP) y cómo la aplicación pone a disposición las herramientas MCP. +- has añadido el servidor MCP de Playwright desde la configuración de la aplicación. +- has pedido al agente que controle un navegador y explore la funcionalidad de filtrado. + +La funcionalidad está creada, verificada y en funcionamiento. Ahora toca publicarla mediante **Agent Merge**, que abrirá y combinará la solicitud de incorporación de cambios. Continúa con la [Lección 6 - Combinar cambios con Agent Merge][next-lesson]. + +## Recursos + +- [¿Qué es MCP y por qué todo el mundo habla de él?][mcp-blog-post] +- [Servidor MCP de Playwright de Microsoft][playwright-mcp-server] +- [Configurar servidores MCP en la aplicación GitHub Copilot][customize-app] + +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/6-agent-merge/ +[mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/ +[playwright-mcp-server]: https://github.com/microsoft/playwright-mcp +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/6-agent-merge.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/6-agent-merge.md new file mode 100644 index 00000000..f69e0398 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "Lección 6 - Combinar cambios con Agent Merge" +description: "Abre la solicitud de incorporación de cambios del filtrado, revísala en My work y deja que Agent Merge corrija los bloqueos y la combine por ti, el nivel más alto de la automatización de combinaciones." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +La funcionalidad de filtrado está creada, verificada y en funcionamiento en un navegador. El último paso es combinarla. Ya has combinado dos cambios en este recorrido; en ambos casos abriste la solicitud de incorporación de cambios y la combinaste personalmente en github.com. Esta vez dejarás que la aplicación se encargue del trabajo con **Agent Merge**, que guía una solicitud durante todo su ciclo de vida desde la aplicación. + +En esta lección: + +- aprenderás qué es Agent Merge y cómo automatiza el ciclo de vida de una combinación. +- habilitarás Agent Merge en la sesión de filtrado. +- observarás cómo crea la solicitud de incorporación de cambios, ejecuta CI y la combina cuando todo se completa correctamente. + +## Escenario + +En los últimos módulos has explorado distintos niveles de automatización, desde crear código hasta permitir que Copilot valide directamente una interfaz de usuario. Para acelerar aún más el desarrollo, Tailspin Toys quiere averiguar si las solicitudes de incorporación de cambios que ya se han revisado y validado pueden combinarse automáticamente. + +## Introducción a Agent Merge + +**Agent Merge** permite automatizar el último tramo de la incorporación de una solicitud de cambios mediante la aplicación Copilot. Al habilitarlo, la sesión de la aplicación lee la solicitud y resuelve lo que la bloquea: corrige comprobaciones de CI con errores, responde a comentarios de revisión y reorganiza la base cuando es necesario. Después la combina en cuanto GitHub lo permite. Se ejecuta en segundo plano, continúa tras reiniciar la aplicación y se desactiva cuando se combina la solicitud. + +Hasta ahora, tú seleccionabas **Merge pull request** en github.com. Agent Merge transfiere esa responsabilidad al agente para que puedas pasar a la siguiente tarea mientras este guía la solicitud hasta completarla. Sigues revisando y aprobando el trabajo; el agente se ocupa del proceso mecánico final. + +## Utilizar Agent Merge para gestionar la solicitud + +Has revisado el código manualmente, ejecutado pruebas e incluso permitido que Copilot valide la interfaz de usuario. Ha llegado el momento de combinar el código nuevo con el código base. Vamos a permitir que Agent Merge guíe la solicitud durante la integración continua (CI) y la combine. + +1. Vuelve a la sesión que mantuviste abierta en el módulo anterior mientras añadías la funcionalidad de filtrado. +2. En la esquina superior derecha, selecciona el menú desplegable situado junto a **Create PR**. +3. Selecciona **Agent merge** para habilitar Agent Merge. + + ![Menú desplegable Create PR de la aplicación GitHub Copilot abierto, con una flecha que señala la opción Agent merge](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. El texto del botón cambia a **Agent merge**. +5. Selecciona el botón **Agent merge** para iniciar el proceso. + +La aplicación Copilot comenzará a crear y gestionar la solicitud. Primero explora el proyecto para determinar la mejor forma de crearla y, después, genera la nueva solicitud. + +Transcurridos unos instantes, observarás que Copilot vuelve a trabajar y examina las condiciones de la solicitud, incluido el proceso de CI que ejecuta todas las pruebas del repositorio. Comunicará el estado de las revisiones de otros miembros del equipo, las comprobaciones que deben ejecutarse y si la solicitud puede combinarse. + +6. Permite que Agent Merge combine la solicitud seleccionando el menú desplegable situado junto a **Agent merge** y, después, **Merge pull request**. + + ![Menú desplegable Agent merge con las acciones permitidas al agente —Address reviews, Fix CI failures y Resolve conflicts— y una flecha que señala Merge pull request](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. Cuando todos los procesos de CI estén en verde, lo que significa que las pruebas han finalizado correctamente, Copilot combinará la solicitud. + +## Resumen y pasos siguientes + +Has automatizado varias partes del proceso de desarrollo, como la generación, las pruebas y la validación de código, y ahora también el proceso de solicitud de incorporación de cambios. En concreto: + +- has aprendido qué es Agent Merge y cómo automatiza el ciclo de vida de una combinación. +- has habilitado Agent Merge en la sesión de filtrado. +- has observado cómo crea la solicitud de incorporación de cambios, ejecuta CI y la combina cuando todo se completa correctamente. + +A continuación, explorarás los **lienzos**, una forma más completa de planificar y visualizar el trabajo con el agente. Continúa con la [Lección 7 - Planificar con lienzos][next-lesson]. + +## Recursos + +- [Gestionar incidencias y solicitudes de incorporación de cambios con la aplicación GitHub Copilot][managing-issues-prs] +- [Acerca de la aplicación GitHub Copilot][about-copilot-app] + +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/7-canvases/ +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/7-canvases.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/7-canvases.md new file mode 100644 index 00000000..4a0c7481 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "Lección 7 - Planificar con lienzos" +description: "Crea un lienzo compartido y dirigido por agentes en la aplicación GitHub Copilot para planificar y realizar el seguimiento del trabajo junto con el agente." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Hasta ahora has dirigido a los agentes mediante el chat. Sin embargo, gran parte del trabajo no reside en una conversación, sino en un tablero, un documento o una lista de comprobación. Los **lienzos** ofrecen al agente y a ti una superficie compartida para ese tipo de trabajo, directamente en la aplicación. En esta lección crearás un lienzo sencillo para planificar y realizar el seguimiento de la lista de trabajo pendiente que has estado abordando. + +En esta lección: + +- comprenderás qué es un lienzo y cuándo utilizarlo. +- crearás un lienzo compartido con un tablero Kanban para clasificar la lista de trabajo pendiente. +- guardarás el lienzo en el repositorio y lo combinarás para el equipo. +- abrirás el lienzo en una sesión nueva y empezarás a trabajar desde él. + +## Escenario + +Examinar una lista de incidencias puede resultar abrumador, incluso en las mejores circunstancias. Los desarrolladores de Tailspin Toys buscan una herramienta que les permita clasificar las incidencias con rapidez y empezar a trabajar en ellas desde la aplicación Copilot. + +## ¿Qué es un lienzo? + +Un [lienzo][canvas-docs] es una superficie interactiva y compartida para un recurso de trabajo, como un plan, un tablero de clasificación, una lista de comprobación de versiones, un panel o un documento. Aunque el chat resulta adecuado para describir intenciones y razonar sobre ambigüedades, la mayor parte del trabajo se realiza en una *superficie*. Los lienzos permiten colaborar con el agente directamente sobre ella. + +Los lienzos son **bidireccionales**: el agente puede actualizar el lienzo mientras trabaja y tú puedes editar la misma superficie. Cuando creas un lienzo, el agente lo genera a partir de la indicación y el flujo de trabajo, y puedes pedirle que añada, elimine o revise capacidades a medida que avanzas. Una vez creado, el lienzo se abre en el panel derecho de la aplicación. + +Algunos ejemplos habituales son: + +- **Lienzos de Markdown** para planificar el día y priorizar incidencias y solicitudes de incorporación de cambios. +- **Tableros Kanban con agentes** en los que las personas y los agentes añaden tarjetas y desplazan el trabajo entre columnas. +- **Tableros de clasificación de incidencias** que resumen las incidencias principales y los temas recurrentes de un repositorio. + +## ¿Por qué utilizar un lienzo? + +Utiliza un lienzo cuando una tarea requiera estructura, iteración y verificación, y un chat no sea suficiente. Un lienzo permite: + +- basar el trabajo del agente en un recurso real que se adapte al flujo de trabajo. +- orientar o corregir el trabajo directamente en la superficie compartida y, después, permitir que el agente continúe a partir de los cambios. +- inspeccionar el progreso como cambios visibles en un recurso, no solo como respuestas del chat. + +## Crear un lienzo para realizar el seguimiento del trabajo + +Has publicado numerosos cambios: la valoración por estrellas, el estándar de documentación y la funcionalidad de filtrado ya están combinados. Sin embargo, todavía quedan elementos en la lista de trabajo pendiente. Vamos a crear el lienzo para clasificar el trabajo con rapidez. + +1. Vuelve a la aplicación GitHub Copilot o ábrela. +2. Selecciona **Home screen**. +3. Comprueba que `tailspin-toys` esté seleccionado como repositorio. +4. En el cuadro de indicaciones, utiliza la indicación siguiente para crear un lienzo que satisfaga nuestras necesidades: + + ```plaintext + Create a basic Kanban board canvas that allows me to quickly triage work. Highlight the three issues which are most likely to need attention right now, with the remainder in a second section down below. The top three cards should include a description of the issue's content and a justification of why they're at the top of the list. Each issue should have a button that allows me to add it to the current context for the current session so I can get to work on it straightaway. + ``` + +Copilot comenzará a crear el lienzo. + +> [!NOTE] +> La creación tardará unos minutos. Como se trata de una tarea compleja, es posible que la primera versión no te satisfaga. Puedes seguir enviando indicaciones hasta crear la herramienta que necesitas. + +## Guardar el lienzo y combinarlo con el repositorio + +Los lienzos pueden convertirse en recursos del repositorio, al igual que los archivos de instrucciones y las habilidades. Vamos a pedir a Copilot que lo añada al repositorio y lo combine para que pueda utilizarlo todo el equipo. + +1. En la misma sesión, pide a Copilot que guarde el lienzo en el repositorio mediante la indicación siguiente: + + ```plaintext + Let's save this canvas definition to the repository so I can share it with my development team + ``` + +2. Cuando Copilot haya guardado los archivos del lienzo, selecciona el menú desplegable situado junto a **Create PR** en la esquina superior derecha. +3. Selecciona **Agent merge** para habilitar Agent Merge. + + ![Menú desplegable Create PR de la aplicación GitHub Copilot abierto, con una flecha que señala la opción Agent merge](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. El texto del botón cambia a **Agent merge**. +5. Selecciona el botón **Agent merge** para iniciar el proceso. + +La aplicación Copilot comenzará a crear y gestionar la solicitud. Primero explora el proyecto para determinar la mejor forma de crearla y, después, la genera. + +Transcurridos unos instantes, observarás que Copilot vuelve a trabajar y examina las condiciones de la solicitud, incluido el proceso de CI que ejecuta todas las pruebas del repositorio. Comunicará el estado de las revisiones de otros miembros del equipo, las comprobaciones que deben ejecutarse y si la solicitud puede combinarse. + +6. Permite que Agent Merge combine la solicitud seleccionando el menú desplegable situado junto a **Agent merge** y, después, **Merge pull request**. + + ![Menú desplegable Agent merge con las acciones permitidas al agente —Address reviews, Fix CI failures y Resolve conflicts— y una flecha que señala Merge pull request](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. Espera a que todos los procesos de CI se completen correctamente y se muestren en verde. Cuando terminen, Copilot combinará automáticamente la solicitud. + +Ya has creado un lienzo compartido para el equipo. + +## Trabajar en el lienzo + +Con el lienzo creado, vamos a iniciar una sesión nueva y utilizarlo. + +1. En la aplicación Copilot, selecciona **New session** junto a **tailspin-toys** para iniciar una sesión nueva. +2. Pide a Copilot que abra el lienzo de clasificación mediante la indicación siguiente: + + ```plaintext + Open the triage issues canvas + ``` + +3. El lienzo que has creado debería abrirse en la sesión nueva. +4. Selecciona **Add to current context** en una de las incidencias que más te interese. +5. Copilot empezará a trabajar en la incidencia. + +Has utilizado un lienzo creado por ti para agilizar el proceso de desarrollo. + +## Resumen y pasos siguientes + +Has creado una superficie compartida en la que puedes colaborar con el agente. En concreto: + +- has aprendido qué son los lienzos y cuándo utilizarlos. +- has creado con el agente un lienzo compartido con un tablero Kanban para clasificar incidencias. +- has guardado y combinado el lienzo con el repositorio mediante Agent Merge. +- has abierto el lienzo en una sesión nueva y lo has utilizado para empezar a trabajar. + +Con la lista de trabajo pendiente organizada, da un paso atrás para revisar todo lo que has creado y descubrir cómo continuar. Continúa con la [Lección 8 - Repaso y pasos siguientes][next-lesson]. + +## Recursos + +- [Trabajar con extensiones de lienzo en la aplicación GitHub Copilot][canvas-docs] +- [Lienzos en Awesome Copilot][awesome-copilot-canvases] +- [Acerca de la aplicación GitHub Copilot][about-copilot-app] + +[next-lesson]: /es-es/learning-hub/copilot-workshops/app/8-review/ +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/8-review.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/8-review.md new file mode 100644 index 00000000..f3acdea4 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "Lección 8 - Repaso y pasos siguientes" +description: "Repasa el recorrido de la aplicación GitHub Copilot, automatiza el trabajo recurrente y descubre cómo continuar." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Durante las últimas lecciones, has llevado una funcionalidad desde la idea hasta la combinación mediante la aplicación GitHub Copilot. Entre otras cosas, has aprendido a: + +- conectar un repositorio y familiarizarte con el espacio de trabajo de la aplicación y la lista de trabajo pendiente inicial. +- iniciar sesiones desde una tarea directa y desde incidencias, y utilizar los modos Plan y Autopilot para controlar cómo trabaja el agente. +- orientar al agente con instrucciones personalizadas y una habilidad reutilizable. +- probar el trabajo con el servidor MCP de Playwright en un navegador real. +- colaborar con el agente en un lienzo compartido. +- publicar cambios con niveles crecientes de automatización de combinaciones, desde combinarlos personalmente en github.com hasta permitir que **Agent Merge** incorpore una solicitud de cambios. + +Vamos a automatizar parte del trabajo recurrente, comentar procedimientos recomendados y descubrir cómo continuar. + +## Automatizar el trabajo recurrente + +La aplicación puede ejecutar agentes según una programación o bajo demanda mediante **automatizaciones**, una opción muy útil para tareas rutinarias como clasificar incidencias nuevas o resumir la actividad reciente. Vamos a crear una automatización sencilla y no destructiva. + +1. Selecciona **Automations** en la barra lateral y, después, **New automation**. +2. Asigna un nombre, como `Recap my recent work`. +3. Elige un desencadenador. **Manual** permite ejecutarla bajo demanda; **On a schedule** la ejecuta automáticamente; **When an issue is created** responde a incidencias nuevas. Para esta lección, elige **Manual**. +4. Introduce una indicación de solo lectura para que la automatización no pueda modificar nada, por ejemplo: + + ```plaintext + Summarize the pull requests merged in this repository over the last week, and list any issues still open in the backlog. + ``` + +5. Elige el proyecto, tu repositorio de Tailspin Toys, y crea la automatización. +6. Ejecútala bajo demanda para ver el resultado. + +> [!TIP] +> Las automatizaciones pueden ejecutarse en local o en la nube. Habilita **Run in the cloud** y elige las **Tools** que puede utilizar una automatización cuando quieras que se ejecute sin supervisión según una programación. Mantén las automatizaciones programadas bien delimitadas y sin acciones destructivas hasta que confíes en sus resultados. + +## Procedimientos recomendados + +Al utilizar cualquier herramienta de IA, la infraestructura que la rodea determina la calidad de los resultados. Los archivos de instrucciones, las habilidades y los agentes personalizados han contribuido al trabajo de este taller. Invierte en ellos y reutilízalos entre sesiones. + +Adapta el **modo y el modelo** a la tarea. Utiliza **Plan** para razonar sobre un enfoque antes de desarrollar, **Interactive** para mantener el control durante cambios concretos y **Autopilot** solo para tareas aisladas y bien delimitadas. Elige un modelo más rápido para las modificaciones rutinarias y otro más capaz, con mayor esfuerzo de razonamiento, para el trabajo complejo. + +El contexto sigue siendo tan importante como la infraestructura. Describir con claridad *qué* quieres crear, *por qué* y *cómo* cambia sustancialmente el resultado. Los chats rápidos son un buen lugar para delimitar una idea antes de dedicarle una sesión completa. + +## Más opciones para explorar + +Ya conoces el flujo de trabajo principal. Estas son algunas funcionalidades adicionales que merece la pena explorar: + +- **Quick chats** para preguntas rápidas y desechables que no necesitan una sesión completa. +- **Rubber duck** para razonar sobre un problema y obtener comentarios pertinentes antes de desarrollar. +- [**Agentes personalizados**][custom-agents] para encapsular un rol, sus herramientas y sus instrucciones con el fin de realizar trabajo especializado y repetible. +- [`/chronicle`][chronicle] para generar una narración de lo sucedido en una sesión. +- [Usar tu propia clave (BYOK)][byok] para utilizar modelos de tu propio proveedor, incluidos modelos locales mediante Ollama, Foundry Local o LM Studio. +- [Entornos aislados en la nube][sandboxes] para ejecutar sesiones en un entorno aislado hospedado en GitHub. +- [Vínculos profundos][deep-links] para abrir la aplicación directamente en un repositorio, una sesión o una indicación. + +## Pasos siguientes + +La mejor forma de mejorar con cualquier herramienta es seguir utilizándola. Úsala para código de producción, proyectos personales o esa pequeña aplicación que llevas años pensando en crear. Comparte lo que aprendas con el equipo y aprende de sus experiencias. Y, como siempre, consulta la documentación. + +Para explorar más elementos del ecosistema de GitHub Copilot, consulta el [recorrido de VS Code](/es-es/learning-hub/copilot-workshops/vscode/), el [recorrido de Copilot CLI](/es-es/learning-hub/copilot-workshops/cli/) o el [recorrido del agente en la nube](/es-es/learning-hub/copilot-workshops/cloud/). + +## Recursos + +- [Acerca de la aplicación GitHub Copilot][about-copilot-app] +- [Introducción a la aplicación GitHub Copilot][getting-started] +- [Personalizar la aplicación GitHub Copilot][customize] +- [Utilizar automatizaciones][using-automations] +- [Trabajar con extensiones de lienzo][canvas-docs] +- [Acerca de los entornos aislados locales y en la nube][sandboxes] + +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[customize]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[using-automations]: https://docs.github.com/copilot/how-tos/github-copilot-app/using-automations +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/index.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/index.md new file mode 100644 index 00000000..d1d367d4 --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/app/index.md @@ -0,0 +1,57 @@ +--- +title: "Aplicación GitHub Copilot" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +La [**aplicación GitHub Copilot**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) es una aplicación de escritorio basada en Copilot CLI que reúne el desarrollo dirigido por agentes en un único espacio de trabajo específico. Añade sesiones de agente en paralelo, modos de sesión intercambiables, lienzos compartidos y gestión nativa de incidencias y solicitudes de incorporación de cambios de GitHub, incluido **Agent Merge**, que guía una solicitud durante reorganizaciones de base, comentarios de revisión, correcciones de CI y la combinación. + +A lo largo de estas lecciones instalarás la aplicación y configurarás el proyecto. Después, conocerás el espacio de trabajo de la aplicación y la lista de trabajo pendiente que la plantilla ha creado para ti. Empezarás con un cambio pequeño, añadir una valoración por estrellas, y luego añadirás desde una incidencia un estándar de instrucciones personalizadas, crearás una funcionalidad de filtrado en una sesión de agente aislada y la verificarás con una habilidad reutilizable. Añadirás el servidor MCP de Playwright para explorar la funcionalidad en un navegador real y avanzarás por niveles crecientes de automatización de combinaciones hasta que **Agent Merge** incorpore la solicitud. Por último, colaborarás en un lienzo compartido y automatizarás el trabajo recurrente: un ciclo completo desde la idea hasta una funcionalidad combinada. + +## Lecciones + +| Lección | Tema | Descripción | +|--------|-------|-------------| +| [0. Requisitos previos][ex0] | Configuración | Instala Node.js y crea tu copia del proyecto Tailspin Toys | +| [1. Instalar la aplicación Copilot][ex1] | Configuración | Instala la aplicación, conecta el proyecto y familiarízate con el espacio de trabajo | +| [2. Ejecutar tu primera sesión de agente][ex2] | Primer cambio | Inicia una sesión y publica un pequeño cambio como tu primera solicitud de incorporación de cambios | +| [3. Guiar a Copilot con instrucciones personalizadas][ex3] | Contexto | Añade un estándar de documentación desde una incidencia y combínalo | +| [4. Crear una funcionalidad con Autopilot][ex4] | Funcionalidad principal | Utiliza Plan y Autopilot para crear el filtrado y verifícalo con una habilidad | +| [5. Realizar pruebas con MCP de Playwright][ex5] | Herramientas externas | Añade el servidor MCP de Playwright y explora la funcionalidad en un navegador | +| [6. Combinar cambios con Agent Merge][ex6] | Combinación | Deja que Agent Merge corrija e incorpore la solicitud de filtrado | +| [7. Planificar con lienzos][ex7] | Colaboración | Crea un lienzo compartido para planificar y realizar el seguimiento del trabajo | +| [8. Repaso y pasos siguientes][ex8] | Resumen | Automatiza tareas recurrentes y descubre cómo continuar | + +## Requisitos previos + +Antes de asistir a este taller, asegúrate de disponer de: + +- [ ] Una cuenta de GitHub con un plan **Copilot Student, Pro, Pro+, Business o Enterprise** activo +- [ ] Un ordenador con **macOS, Linux o Windows** +- [ ] [Git instalado][install-git] en el ordenador + +> [!TIP] +> ¿No tienes un plan de pago? Los estudiantes verificados pueden obtener GitHub Copilot gratis mediante [GitHub Education][callout-student-plan-education]. El plan **Copilot Student** incluye el agente, MCP, la revisión de código y las funcionalidades de Copilot CLI que se utilizan en este taller, por lo que permite completar todos los recorridos. + +> [!NOTE] +> Como la aplicación Copilot se ejecuta en tu propio equipo y no en un codespace, la [Lección 0][ex0] explica cómo instalar Node.js y crear tu copia del proyecto antes de instalar la aplicación. + +> [!NOTE] +> Si utilizas Copilot Business o Copilot Enterprise, el administrador debe habilitar la directiva **Copilot CLI** para que puedas utilizar la aplicación. + +## Comenzar + +[**Empieza por la Lección 0: Requisitos previos →**][ex0] + +[ex0]: /es-es/learning-hub/copilot-workshops/app/0-prerequisites/ +[ex1]: /es-es/learning-hub/copilot-workshops/app/1-install-copilot-app/ +[ex2]: /es-es/learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /es-es/learning-hub/copilot-workshops/app/3-custom-instructions/ +[ex4]: /es-es/learning-hub/copilot-workshops/app/4-build-filtering/ +[ex5]: /es-es/learning-hub/copilot-workshops/app/5-mcp-playwright/ +[ex6]: /es-es/learning-hub/copilot-workshops/app/6-agent-merge/ +[ex7]: /es-es/learning-hub/copilot-workshops/app/7-canvases/ +[ex8]: /es-es/learning-hub/copilot-workshops/app/8-review/ +[install-git]: https://github.com/git-guides/install-git +[callout-student-plan-education]: https://github.com/education/students \ No newline at end of file diff --git a/website/src/content/docs/es-es/learning-hub/copilot-workshops/index.md b/website/src/content/docs/es-es/learning-hub/copilot-workshops/index.md new file mode 100644 index 00000000..af3ee5bd --- /dev/null +++ b/website/src/content/docs/es-es/learning-hub/copilot-workshops/index.md @@ -0,0 +1,41 @@ +--- +title: "Manos a la obra con los agentes de GitHub Copilot" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Las recientes ampliaciones de las capacidades de GitHub Copilot ofrecen a los desarrolladores herramientas potentes para todo el ciclo de vida del desarrollo de software (SDLC). Estas capacidades incluyen trabajar con incidencias y solicitudes de incorporación de cambios en GitHub, interactuar con servicios externos y, por supuesto, crear código. En este laboratorio se exploran estas funciones mediante casos de uso reales y consejos para aprovechar al máximo las herramientas. + +> [!CAUTION] +> Como GitHub Copilot es probabilístico y no determinista, el código exacto, los archivos modificados y otros elementos pueden variar. Por este motivo, es posible que observes pequeñas diferencias entre las capturas de pantalla y los fragmentos de código del laboratorio y lo que tú ves. Es algo normal y forma parte de trabajar con este tipo de herramientas. +> +> Si algo parece no funcionar o no se ejecuta correctamente, ¡pide ayuda a un mentor! + +## Elige tu entorno + +GitHub Copilot te acompaña allí donde trabajes. Elige el entorno que se ajuste a tu forma de desarrollar y completa sus ejercicios con el trabajo pendiente compartido de Tailspin Toys. Cada entorno comienza con su propia configuración para que puedas empezar directamente con el que elijas. + +### 🖥️ [VS Code](/es-es/learning-hub/copilot-workshops/vscode/) + +GitHub Copilot dentro de **Visual Studio Code** y GitHub Codespaces. Trabaja con el modo agente de Copilot Chat, servidores MCP y agentes personalizados sin salir del editor que ya utilizas. Es ideal si quieres integrar la asistencia de IA directamente en el IDE. + +### 💻 [Copilot CLI](/es-es/learning-hub/copilot-workshops/cli/) + +**GitHub Copilot CLI** es un asistente basado en agentes que se ejecuta en el terminal. Instálalo, conecta servidores MCP, genera código con el modo de planificación y crea tus propias skills, agentes personalizados y comandos con barra diagonal, todo desde la línea de comandos. + +### 🤖 [Copilot App](/es-es/learning-hub/copilot-workshops/app/) + +La **aplicación GitHub Copilot** es una aplicación de escritorio basada en Copilot CLI. Ejecuta sesiones de agentes en paralelo, cambia el modo de las sesiones, colabora en lienzos y gestiona incidencias y solicitudes de incorporación de cambios de GitHub de forma nativa. También incluye **Agent Merge**, que guía una solicitud de incorporación de cambios durante los cambios de base, los comentarios de revisión, las correcciones de integración continua y la combinación. + +### ☁️ [Copilot Cloud Agent](/es-es/learning-hub/copilot-workshops/cloud/) + +El **agente de Copilot en la nube** es un compañero de programación asíncrono que trabaja en segundo plano en las incidencias de GitHub. Asígnale trabajo, guíalo con agentes personalizados, supervisa el progreso desde el panel de agentes y revisa las solicitudes de incorporación de cambios que abre. + +## Escenario + +Acabas de incorporarte como desarrollador a Tailspin Toys, una empresa ficticia que ofrece financiación colectiva para juegos de mesa de temática tecnológica: ¡un mercado enorme! El trabajo pendiente del equipo ya está registrado como incidencias de GitHub para que puedas comenzar. Incluye tanto funcionalidades, como el filtrado y la paginación, como mejoras de calidad, como la accesibilidad y los estándares de programación. Trabajarás de forma iterativa para completar las tareas mientras exploras el sitio y las capacidades de Copilot. + +## Primeros pasos + +Elige uno de los entornos anteriores para empezar. Cada uno comienza con la configuración necesaria para que puedas ponerte manos a la obra. \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/0-prerequisites.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/0-prerequisites.md new file mode 100644 index 00000000..3d49bcf2 --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "レッスン 0 - 前提条件" +description: "GitHub Copilot app のレッスンに向けて、Tailspin Toys プロジェクト用の Node.js をインストールし、テンプレートからリポジトリの自分用コピーを作成します。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +GitHub Copilot app は、Copilot と GitHub の両方を一元的に扱うデスクトップアプリです。Issue や pull request にすばやくアクセスでき、もちろん GitHub Copilot を使った開発も可能です。このワークショップでは、Astro で構築された Tailspin Toys アプリと GitHub Copilot app を使い、ローカル環境で作業します。始める前に、Node.js がローカルにインストールされていることを確認してから、Copilot app をインストールします。 + +このレッスンでは、次の内容を学習します。 + +- プロジェクトのテストを実行できるよう Node.js をインストールする。 +- テンプレートから Tailspin Toys プロジェクトの自分用コピーを作成する。 + +## Node.js をインストールする + +いくつかのレッスンでは、エージェントに機能を構築させ、Tailspin Toys のテストスイートをローカルで実行します。そのためには [**Node.js**][nodejs] (プロジェクトに必要な唯一のランタイム) が必要です。バージョン **22 以降**をインストールしてください。現在の **LTS** リリースを選ぶと安心です。 + +どのプラットフォームでも、公式インストーラーを使うのが最も簡単です。 + +1. Windows Terminal、macOS のターミナル、または普段使用しているターミナルを開きます。 +2. 次のコマンドを実行し、Node.js 22 以降がインストールされていることを確認します。 + + ```shell + node --version + ``` + +3. `v22` 以上のバージョン番号が表示された場合は、次のセクションに進めます。 + +> [!TIP] +> Node.js がインストールされていない場合、または更新が必要な場合にのみ、以降の手順を実行してください。 + +4. [Node.js のダウンロードページ][node-download]を開きます。 +5. 使用しているオペレーティングシステム向けの **LTS** ビルドをダウンロードします。 +6. インストーラーを実行し、既定の設定を選択します。Windows では、**Add to PATH** を選択したままにします。 +7. インストールが完了したら、新しいターミナルを開きます。 +8. 新しいターミナルで次のコマンドを実行し、インストールを確認します。 + + ```bash + node --version + ``` + +9. `v22.x.x` 以上が表示されることを確認します。 + +> [!TIP] +> コンテナーを使用する場合、[**Docker**][docker] があれば、Node.js をローカルにインストールする代わりにリポジトリの [dev container][dev-containers] を使用できます。dev container には Node.js が含まれているため、両方を用意する必要はありません。 + +## ラボ用リポジトリを設定する + +Tailspin Toys プロジェクトの自分用コピーを使って作業します。[テンプレートリポジトリ][template-repository]からコピーを作成してください。新しいリポジトリにはラボに必要なすべてのファイルが含まれています。次のレッスンで、このリポジトリをアプリに接続します。 + +1. 新しいブラウザーウィンドウで、このラボの GitHub リポジトリ `https://github.com/github-samples/tailspin-toys` を開きます。 +2. ラボ用リポジトリのページで **Use this template** ボタンを選択し、**Create a new repository** を選択して、リポジトリの自分用コピーを作成します。 + + ![Use this template ボタンのドロップダウンで Create a new repository が選択されている画面](/images/learning-hub/copilot-workshops/app-0-use-template.png) + +3. GitHub または Microsoft が主催するイベントの一環としてワークショップに参加している場合は、メンターの指示に従ってください。それ以外の場合は、GitHub Copilot を利用できる Organization に新しいリポジトリを作成できます。 + + ![github-samples/tailspin-toys がテンプレートに設定され、リポジトリ名が入力された Create a new repository フォーム](/images/learning-hub/copilot-workshops/app-0-create-repository.png) + +4. 作成したリポジトリのパス (**organization-or-user-name/repository-name**) を記録します。このラボで後ほど使用します。 + +> [!NOTE] +> テンプレートからリポジトリを作成すると、GitHub Issue のバックログが自動的に作成されます。ワークショップ全体を通してこれらの Issue を使用するため、自分で作成する必要はありません。 + +## まとめと次のステップ + +準備が整いました。プロジェクトをコンピューター上でビルドしてテストできるように Node.js をインストールし、テンプレートから Tailspin Toys リポジトリの自分用コピーを作成しました。 + +次は GitHub Copilot app をインストールし、作成したリポジトリを接続して、ワークスペースを確認します。[レッスン 1「GitHub Copilot app のインストール」][next-lesson]に進んでください。 + +## リソース + +- [Node.js のダウンロード][node-download] +- [テンプレートからのリポジトリの作成][template-repository] +- [GitHub Copilot app について][about-copilot-app] + +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/1-install-copilot-app/ +[nodejs]: https://nodejs.org/ +[node-download]: https://nodejs.org/en/download +[docker]: https://www.docker.com/products/docker-desktop/ +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/1-install-copilot-app.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/1-install-copilot-app.md new file mode 100644 index 00000000..b9ae4a4a --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "レッスン 1 - GitHub Copilot app のインストール" +description: "GitHub Copilot app をインストールし、テンプレートから作成したリポジトリを接続して、ワークスペースを確認し、クイックチャットを試します。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[**GitHub Copilot app**][about-copilot-app] は、エージェント主導の開発に使用するデスクトップアプリケーションです。GitHub Copilot CLI を基盤とし、GitHub とネイティブに統合されているため、リポジトリ、ブランチ、CI パイプラインをすぐに利用できます。すべての作業を自分で行うのではなく、複数のエージェントをそれぞれ分離されたワークスペースで並列に指示し、繰り返し発生するタスクを自動化するワークフロー向けに設計されています。Node.js のインストールとプロジェクトのコピーが完了したので、次はアプリをインストールして、そのリポジトリを接続します。 + +このレッスンでは、次の内容を学習します。 + +- GitHub Copilot app をインストールしてサインインする。 +- GitHub リポジトリからプロジェクトをアプリに追加する。 +- テンプレートによって用意されたバックログを含め、ワークスペースを確認する。 +- クイックチャットを試して、アプリ自体について学ぶ。 + +## シナリオ + +チームは、増え続けるバックログに対応するために AI エージェントを導入しています。Copilot app では、Issue の選択、エージェントの実行、変更のレビュー、pull request のマージを一か所から指示できます。このレッスンでは、アプリをインストールして接続し、プロジェクトについての会話を始められるようにします。 + +> [!NOTE] +> 対象となる Copilot プランが必要です。Copilot Student またはいずれかの有料プラン (Pro、Pro+、Business、Enterprise) を利用してください。Copilot Business または Copilot Enterprise を使用している場合、アプリを動作させるには管理者が **Copilot CLI** ポリシーを有効にする必要があります。 + +## GitHub Copilot app をインストールして構成する + +GitHub Copilot app を使用するには、まずアプリをインストールします。Windows、macOS、Linux 向けのバージョンが用意されています。アプリをインストールして認証し、Tailspin Toys リポジトリを追加します。 + +1. ブラウザーで [GitHub Copilot app のランディングページ][download-app]を開きます。 +2. 使用しているプラットフォーム向けのアプリをダウンロードし、ランディングページの手順に従ってインストールします。 +3. インストールが完了したら、アプリを開きます。 +4. **Sign in to GitHub** を選択し、画面の指示に従って認証します。GitHub Enterprise Server を使用している場合は **Use GitHub Enterprise** を選択し、求められたらサーバーアドレスを入力します。 +5. 認証後、リポジトリを接続するよう求められます。先ほど作成した `/tailspin-toys` という名前の Tailspin Toys リポジトリを選択します。 +6. **Continue** を選択してオンボーディングを続けます。 +7. テーマの選択を求められたら、最も好みのものを選び、**Finish** を選択します。 + +> [!NOTE] +> Tailspin Toys のコピーが一覧に自動的に表示されなかった場合は、アプリのオンボーディングを完了した後に追加できます。完了すると、Copilot app のホーム画面が表示されます。そこで **Choose from GitHub** を選択し、リポジトリ名 (\/tailspin-toys) で検索して選択します。これでリポジトリが Copilot app に追加されます。 + +## ワークスペースを確認する + +プロジェクトを接続したら、各領域を確認します。アプリのサイドバーは、主に次の領域で構成されています。 + +- **Sessions** - エージェントが作業する場所です。各セッションは分離された独自のワークスペースで実行されるため、変更が競合することなく複数のセッションを同時に実行できます。次のレッスンで最初のセッションを開始します。 +- **Quick chats** - 独自のブランチやワークスペースを必要としない、質問やブレインストーミング向けの簡易的な会話です。このレッスンの最後に試します。 +- **My work** - アプリの **GitHub ネイティブ統合**を通じて表示される Issue と pull request です。アプリを離れずに、Issue と pull request の参照や絞り込み、CI ステータスの確認、Issue からのセッション開始、pull request のレビューを行えます。 +- **Automations** - スケジュールまたはオンデマンドで実行する、保存済みのエージェントタスクです。ハーネスの終盤で作成します。 + +### 用意されたバックログを確認する + +アプリは GitHub とネイティブに統合されているため、リポジトリで待機中の作業がアプリ内に表示されます。テンプレートからリポジトリを作成したときに、バックログとなる Issue が用意されています。表示されていることを確認します。 + +1. サイドバーで **My work** を選択します。 +2. テンプレートはバックログに 8 件の Issue を用意しています。このハーネスでは次の 3 件に焦点を当てます。表示されていることを確認してください。 + + - Allow users to filter games by category and publisher + - Update our repository coding standards + - Implement pagination on the game list page + +3. Issue を選択して詳細を読みます。各 Issue はエージェントセッションの開始点にもなります。ハーネスの後半では、これらの Issue から作業を開始します。 + +> [!NOTE] +> My work の項目一覧は自動的に絞り込まれ、Copilot app に追加したリポジトリの項目だけが表示されます。ほかのリポジトリの作業項目を表示するには、そのリポジトリをアプリに追加してください。 + +## クイックチャットを試す + +アプリに慣れるには、アプリ自体について質問するのが効果的です。その用途には **quick chat** が適しています。Quick chats ではブランチや worktree を作成せずに質問やブレインストーミングができるため、セッションを必要としない、その場限りの簡単な質問に最適です。 + +1. サイドバーで **Quick chats** の横にある **+** を選択し、新しいチャットを開きます。 +2. アプリのセッションがどのように動作するかを尋ねます。 + + ```plaintext + How does the GitHub Copilot app use worktrees? + ``` + +3. 会話ビューで回答を読みます。各セッションが分離された独自の git worktree で実行されるため、変更が競合することなく複数のエージェントを並列実行できることがわかります。会話はいつでも継続でき、新しいチャットも開始できます。 + +## まとめと次のステップ + +GitHub Copilot app をインストールし、プロジェクトを接続して、ワークスペースを確認しました。学習した内容は次のとおりです。 + +- アプリをインストールして GitHub にサインインする。 +- GitHub リポジトリからプロジェクトを追加する。 +- ワークスペースを確認し、**My work** で用意されたバックログを見つける。 +- クイックチャットを使って、その場限りの簡単な質問をする。 + +次は、最初のエージェントセッションを開始し、ゲームカードに星評価を表示する最初の変更をプロジェクトに加えます。[レッスン 2「最初のエージェントセッションの実行」][next-lesson]に進んでください。 + +## リソース + +- [GitHub Copilot app について][about-copilot-app] +- [GitHub Copilot app の概要][getting-started] +- [GitHub Copilot app でのエージェントセッションの操作][agent-sessions] + +[ex0]: /ja-jp/learning-hub/copilot-workshops/app/0-prerequisites/ +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/2-add-star-rating/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[download-app]: https://gh.io/app \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/2-add-star-rating.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/2-add-star-rating.md new file mode 100644 index 00000000..23a99826 --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "レッスン 2 - 最初のエージェントセッションの実行" +description: "GitHub Copilot app で最初のエージェントセッションを開始し、ゲームカードに小さな変更を加えて、最初の pull request としてマージします。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +前のレッスンでは、ワークスペースを確認し、クイックチャットを使いました。ここでは、**エージェントセッション**を開始し、プロジェクトに最初の変更を加えます。変更は小規模なものにします。ゲームのデータにはすでに星評価が含まれていますが、ホームページのゲームカードにはまだ表示されていません。エージェントに表示を依頼し、変更をレビューして、最初の pull request としてマージします。 + +このレッスンでは、次の内容を学習します。 + +- エージェントセッションを開始し、セッションの構成を理解する。 +- プロジェクトに小規模で対象を絞った変更を加えるようエージェントに依頼する。 +- ワークスペースの差分ビューで変更をレビューする。 +- アプリをローカルで実行し、ブラウザーで変更を確認する。 +- 最初の pull request を作成してマージする。 + +## シナリオ + +Tailspin Toys の各ゲームには星評価を設定でき、ゲーム詳細ページにはすでに表示されています。一方、ホームページのゲームカードには、タイトル、カテゴリー、パブリッシャー、説明だけが表示されています。最初のセッションの準備運動として、各カードに既存の評価を表示するようエージェントに依頼します。小規模で自己完結した、最初のセッションに最適な変更です。 + +## セッションの構造 + +**セッション**とは、分離された独自のワークスペースで実行されるエージェントとの会話です。すべてのセッションに**専用の git worktree とブランチ**が割り当てられます。そのため、一方では機能を追加し、もう一方ではバグを修正するなど、変更を競合させずに複数のセッションを同時に実行できます。セッションはリポジトリごとにグループ化されてサイドバーに表示され、選択すると切り替えられます。 + +セッション内には、エージェントとの**会話**、ファイルを調査および編集するときのエージェントの**ツールアクティビティ**、差分付きの**変更済みファイル**一覧という3つの要素が表示されます。 + +## セッションを開始して変更を依頼する + +新しいセッションを開始し、プロジェクトの調査と機能の実装に取りかかります。[前のレッスン][prior-lesson]では、GitHub リポジトリからプロジェクトを追加しました。そのリポジトリ用の新しいセッションを作成し、変更を依頼します。 + +1. GitHub Copilot app に戻ります。アプリを閉じている場合は開きます。 +2. **Home screen** を選択します。 +3. リポジトリに `tailspin-toys` が選択されていることを確認します。 + + ![リポジトリセレクターに tailspin-toys が設定され、プロンプトの下にモデルセレクターが表示された GitHub Copilot app のプロンプトボックス](/images/learning-hub/copilot-workshops/app-2-start-session.png) + +4. 次のプロンプトを使って変更を依頼します。 + + ```plaintext + On the game cards, show each game's star rating. The Game type already includes a starRating field — it's a number out of 5, or null when a game hasn't been rated yet. Display it on each card in src/components/GameCard.astro, and when starRating is null show "No rating yet" instead. Keep the change small and don't restructure the card layout. + ``` + +> [!NOTE] +> プロンプトに、Copilot が更新するファイル名が含まれていることに注目してください。Copilot が作業に含めるファイルを指定する必要はありませんが、方向性を示すことで、コードをすばやく生成し、トークン使用量を削減できます。 + +5. Enter を選択して、プロンプトを Copilot に送信します。 + +Copilot app は、最初にプロジェクトの分離されたコピーである新しい worktree を作成して作業を開始します。次にプロジェクトを調査し、新機能の追加に必要な更新対象ファイルを見つけて、必要なコードを作成します。これで Copilot app を使って新機能を追加できました。 + +## 差分をレビューする + +AI が生成したすべての変更は、どれほど小さくてもマージ前にレビューする必要があります。Copilot app 内で変更を確認します。 + +1. アプリの右上隅にある **Toggle review panel** を選択します。Copilot が行った未処理の変更がすべて表示される差分画面が開きます。 + + ![Create PR の右側にある Toggle review panel ボタンを矢印で示した GitHub Copilot app の上部ツールバー](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. ゲームの詳細表示に使用される中心的なファイル `GameCard.astro` にコードが追加されていることを確認します。次のような小さなブロックが追加されているはずです。評価がある場合は表示し、`starRating` が `null` の場合は "No rating yet" を表示します。 + + ```astro + {game.starRating !== null ? ( + + ★ {game.starRating} / 5 + + ) : ( + + No rating yet + + )} + ``` + +> [!NOTE] +> Copilot は、すべての生成 AI ツールと同様に決定論的ではなく確率的に動作するため、実際のコードは上記と異なる場合があります。ただし、比較的よく似たものになります。 + +## 変更を確認する + +コードを読むだけで動作すると判断せず、視覚的にもテストします。そのためには、ターミナルからアプリを起動して、すべてが動作することを確認する必要があります。Copilot app にはターミナルが組み込まれています。 + +1. Copilot app の右側にあるレビューパネルで **Terminal** を選択します。**Terminal** ボタンがない場合は、**+** (**Open in panel** というラベルが付いています) を選択してから **Terminal** を選択します。 + + ![GitHub Copilot app のレビューパネルにある Terminal ボタン](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +2. ターミナルウィンドウに次のコマンドを入力し、Web アプリの開発サーバーを起動します。 + + ```shell + npm run dev + ``` + +3. サーバーが起動したら、ブラウザーウィンドウを開きます。起動には少し時間がかかります。 +4. http://localhost:4321 に移動します。 +5. ランディングページのすべてのゲームに星評価が表示されていることを確認します。 +6. ターミナルウィンドウに戻ります。 +7. Ctrl+C を選択して開発サーバーを停止します。 + +## 最初の pull request を作成してマージする + +変更に問題がないことを確認できたので、リリースします。エージェントに pull request の作成を依頼し、github.com で自分でレビューしてマージします。今回は手動で管理します。後のレッスンでは、Copilot でこの作業の一部を自動的に処理する方法を確認します。 + +1. 右上隅にある **Create PR** を選択します。 +2. 求められた場合は **Sign in with your browser** を選択し、画面の指示に従って認証します。 +3. Copilot が PR の作成を開始します。 + +PR が作成されると、Copilot はリポジトリで実行する必要があるワークフローを監視します。しばらくすると、右上のボタンが **Ready to merge** に変わります。これは PR をマージする準備が整ったことを示します。 + +4. チャットのすぐ上にある **PR** バブルを選択し、レビューペインで PR を開いて pull request を確認します。必要に応じて、ここで PR をレビューできます。 +5. 準備ができたら **Ready to merge** を選択します。 +6. 新しいダイアログウィンドウで **Merge pull request** を選択し、pull request をマージします。 + +これで Web サイトに新機能を反映できました。 + +## まとめと次のステップ + +最初のエージェントセッションを開始し、最初の変更をリリースしました。具体的には、次の作業を行いました。 + +- エージェントセッションを開始し、セッションの構成を学習した。 +- ゲームカードに小規模で対象を絞った変更を加えるようエージェントに指示した。 +- ワークスペースの差分ビューで変更をレビューした。 +- アプリをローカルで実行し、ブラウザーで星評価を確認した。 +- pull request を作成し、github.com で自分でマージした。 + +次は、アプリを使ってリポジトリにカスタム指示の標準を追加します。バックログ内の Issue の1つから作業を開始します。[レッスン 3「カスタム指示による Copilot のガイド」][next-lesson]に進んでください。 + +## リソース + +- [GitHub Copilot app でのエージェントセッションの操作][agent-sessions] +- [GitHub Copilot app について][about-copilot-app] +- [GitHub Copilot app での Issue と pull request の管理][managing-issues-prs] + +[prior-lesson]: /ja-jp/learning-hub/copilot-workshops/app/1-install-copilot-app/#github-copilot-app-をインストールして構成する +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/3-custom-instructions/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/3-custom-instructions.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/3-custom-instructions.md new file mode 100644 index 00000000..f57694ef --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "レッスン 3 - カスタム指示による Copilot のガイド" +description: "GitHub Copilot app を使い、バックログの Issue から始めてカスタム指示の標準をリポジトリに追加し、変更を pull request としてマージします。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +生成 AI を扱うとき、コンテキストは重要です。タスクを特定の方法で実行する必要がある場合や、Copilot が把握しておくべき背景情報がある場合は、そのコンテキストを利用できるようにします。特に強力なツールの1つが[指示ファイル][instruction-files]です。指示ファイルには、必要なコードの内容だけでなく、その構成方法も記述します。このレッスンでは、リポジトリにドキュメント標準を追加します。ここから先の多くの作業と同様に、バックログの Issue から開始し、エージェントに変更を行わせます。 + +このレッスンでは、次の内容を学習します。 + +- リポジトリ指示とパス固有の指示ファイルがエージェントにどのように渡されるかを確認する。 +- バックログ内の指示に関する Issue からセッションを開始する。 +- `.github/copilot-instructions.md` にドキュメント標準を追加するようエージェントに依頼する。 +- 変更をレビューし、pull request としてマージする。 + +## シナリオ + +優れた開発組織と同様に、Tailspin Toys にも開発プラクティスのガイドラインと要件があります。内容は次のとおりです。 + +- TSDoc doc comment の形式でコードにドキュメントを追加する。 +- フォーマット方法を文書化し、lint によって適用する。 + +指示ファイルを使用すると、示されたプラクティスに沿ってタスクを実行するために必要な情報を Copilot に提供できます。 + +## 指示ファイル + +カスタム指示を使うと、Copilot にコンテキストと設定を提供でき、コーディングスタイルや要件をより正確に理解させることができます。Copilot をガイドし、より関連性の高い提案やコードスニペットを得るための強力な機能です。希望するコーディング規約、ライブラリ、コードに含めるコメントの種類まで指定できます。リポジトリ全体に適用する指示や、タスクレベルのコンテキストとして特定のファイル種類に適用する指示を作成できます。 + +指示ファイルには2つの種類があります。 + +- `.github/copilot-instructions.md` は、リポジトリに対する**すべての**リクエストで Copilot に送信される単一の指示ファイルです。このファイルには、Copilot に送信するほとんどのチャットまたは CLI リクエストに関係する、プロジェクトレベルの情報を記載します。使用する技術スタック、構築するものの概要、ベストプラクティスなど、全体に適用するガイダンスを含められます。 +- `.github/instructions/*.instructions.md` ファイルは、特定のタスクやファイル種類向けに作成できます。特定の言語 (TypeScript や Astro など) や、UI コンポーネントまたは新しい単体テスト一式の作成といったタスクに関するガイドラインを提供できます。 + +> [!NOTE] +> Copilot は AGENTS.md、CLAUDE.md、GEMINI.md を通じて指示のガイダンスを取り込むほかの標準もサポートしており、常に適切なコンテキストを提供できます。 + +### 指示ファイルを管理するためのベストプラクティス + +指示ファイルの作成方法を詳しく説明することは、このワークショップの範囲外です。ただし、サンプルプロジェクトに含まれる例は、代表的なアプローチを示しています。概要は次のとおりです。 + +- `copilot-instructions.md` の指示は、構築するものの説明、プロジェクトの構造、全体的なコーディング標準など、プロジェクトレベルのガイダンスに絞ります。 +- `*.instructions.md` ファイルは、ファイル種類 (単体テスト、Astro コンポーネント、データレイヤー) または特定のタスクに固有の指示を提供するために使用します。 +- 自然言語を使います。ガイダンスは明確にし、コードの適切な例と不適切な例を提示します。 + +AI の使い方に唯一の方法がないのと同様に、指示ファイルの作成方法にも唯一の正解はありません。プロジェクトに最適な方法は、試行を重ねることで見つけられます。 + +> [!TIP] +> GitHub Copilot を使用するすべてのプロジェクトには、充実した指示ファイル一式を用意することをお勧めします。このプロジェクトのファイルを確認すると、多くのコードファイル種類に対応する指示ファイルがあることがわかります。 +> +> テンプレートや出発点が必要な場合は、指示ファイル、カスタムエージェントなどのリソースが揃ったリポジトリ [awesome-copilot][awesome-copilot] を確認してください。 + +## このプロジェクトのカスタム指示ファイルを確認する + +このリポジトリに含まれる指示ファイルを確認します。中心となる `copilot-instructions.md` が1つと、さまざまなタスクに対応する `*.instructions.md` ファイル一式があります。エディターまたは GitHub Web UI で開いてください。 + +1. レビューパネルが表示されていない場合は、右上の **Toggle review panel** を選択して開きます。 + + ![Create PR の右側にある Toggle review panel ボタンを矢印で示した GitHub Copilot app の上部ツールバー](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. **+** を選択し、レビューパネルに新しい項目を追加します。 +3. **File** を選択します。 +4. `copilot-instructions.md` を検索します。 +5. ファイル一覧から `copilot-instructions.md` を選択して開きます。 +6. ファイルを確認します。プロジェクトの簡単な説明に加えて、**Agent notes**、**Code standards**、**Scripts**、**Repository Structure** などのセクションがあります。**Code standards** の下には、ネストされた **GitHub Actions Workflows** のガイダンスがあります。これらは Copilot とのすべてのやり取りに適用されます。 +7. **Show folder view** を選択して、フォルダーナビゲーターを開きます。 + + ![GitHub Copilot app でファイルを開いたレビューパネルにある Show folder view ボタン](/images/learning-hub/copilot-workshops/app-show-folder-view.png) + +8. `.github/instructions` フォルダーに移動し、ファイルを確認します。Astro ファイル、Drizzle データレイヤー、テストなどに対応する指示があります。 +9. `.github/instructions/unit-tests.instructions.md` を開きます。先頭の `applyTo` フィールドに注目してください。これはリポジトリのルートを基準とする glob で、指示を適用するファイルを決定します。ここでは、TypeScript のテストファイル (`**/*.test.ts` に一致するファイルなど) が対象になります。 +10. このプロジェクトで単体テストを作成するための固有の指示を確認します。 +11. 最後に `.github/instructions/drizzle.instructions.md` を開き、末尾まで移動します。ほかの指示ファイル (`unit-tests.instructions.md` など) と、プロジェクト内の既存ファイルへのリンクに注目してください。これにより、大きな指示セットを小さく再利用可能なファイルに分割し、コード生成時に参照する例を Copilot に提示できます。そこに記載されたパスは、リポジトリのルートではなく指示ファイルを基準とします。 + +> [!NOTE] +> `copilot-instructions.md` の **Code formatting requirements** セクションにはプロジェクトのコーディング標準が記載されていますが、コード内のドキュメントはまだ必須ではありません。次の手順で、TSDoc doc comment とファイルコメントヘッダーの規則を追加します。 + +## 指示に関する Issue から開始する + +前のレッスンでは、直接入力したプロンプトからセッションを開始しました。しかし、多くの作業は Issue から始まります。指示ファイルを更新するために登録された Issue に基づいて新しいセッションを作成し、更新を依頼します。 + +> [!NOTE] +> 指示ファイルは Copilot が生成するコードに大きな影響を与えるため、Copilot を明確にガイドする内容になっていることを慎重に確認してください。このレッスンのように、Copilot で最初のバージョンを作成した後、自分でレビューして更新内容が要件を満たすことを確認する方法が効果的です。 + +1. サイドバーで **My work** を選択します。 +2. **Update our repository coding standards** というタイトルの Issue を選択して開きます。 +3. 右上の **New session** を選択し、Issue に基づく新しいセッションを開始します。 + + ![GitHub Copilot app の Issue ビューで、右上の New session ボタンを矢印で示した画面](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. 次のプロンプトを使い、Issue に記載された要件を満たすように指示ファイルを更新することを Copilot に依頼します。 + + ```plaintext + Following this issue, make the updates to the instructions files in this project to meet the requirements documented. Don't create the PR quite yet! + ``` + +Copilot が更新を行います。 + +## 変更をレビューする + +Copilot が行った更新を読み、更新された指示に基づいて生成するコード例も提示させます。 + +1. 右上の **Changes** を選択してコードの変更を開きます。 + + ![GitHub Copilot app のセッションパネルにあるタブで、Changes タブを矢印で示した画面](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. 更新された指示ファイルをレビューします。コードにドキュメントとコメントを追加するためのガイドラインが含まれていることを確認します。 + +> [!NOTE] +> AI は決定論的ではなく確率的に動作するため、実際のテキストは異なります。 + +3. 次のプロンプトを使い、Copilot が今後生成するコード例を作成するよう依頼します。 + + ```plaintext + Do not make any updates, but show me what the code would look like. Based on the new instructions, if I asked Copilot to create a new library component to return all Publishers what would that code look like? + ``` + +4. Copilot が提案するコードをレビューします。更新された指示で求めたとおり、TSDoc doc comment とファイルヘッダーコメントが含まれていることを確認します。 + +これでプロジェクトの指示ファイルを更新し、その効果を確認できました。 + +## pull request を作成してマージする + +指示ファイルはリポジトリのアセットとなり、チームのほかのメンバーと共有されます。ほかのアセットと同様に、作業内容を含む PR を作成します。 + +1. 右上隅にある **Create PR** を選択します。 +2. 求められた場合は **Sign in with your browser** を選択し、画面の指示に従って認証します。 +3. Copilot が PR の作成を開始します。 + +PR が作成されると、Copilot はリポジトリで実行する必要があるワークフローを監視します。しばらくすると、右上のボタンが **Ready to merge** に変わります。これは PR をマージする準備が整ったことを示します。 + +4. **Ready to merge** を選択します。 +5. 新しいダイアログウィンドウで **Merge pull request** を選択し、pull request をマージします。 + +> [!NOTE] +> 標準がデフォルトブランチにマージされると、すべてのメンバーと新しいセッションでプロジェクトの一部として利用できます。次のレッスンで最新のデフォルトブランチからフィルター機能のセッションを開始すると、エージェントは自動的にこの標準に従います。生成された TypeScript に、依頼していなくても TSDoc doc comment が含まれます。指示が生成コードを形作ることを示す、小さいながらも実際的な例です。 + +## まとめと次のステップ + +アプリが指示ファイルからコンテキストを取得する仕組みを確認し、セッションを使ってリポジトリ全体の標準を追加してマージしました。具体的には、次の作業を行いました。 + +- リポジトリの `copilot-instructions.md` とパス固有の `*.instructions.md` ファイルを確認した。 +- バックログ内の指示に関する Issue からセッションを開始した。 +- `.github/copilot-instructions.md` にドキュメント標準を追加するようエージェントに依頼した。 +- 変更をレビューし、pull request としてマージした。 + +次は、新しいセッションでフィルター機能を構築し、先ほどマージした標準が適用される様子を確認します。[レッスン 4「Autopilot による機能の構築」][next-lesson]に進んでください。 + +## リソース + +- [GitHub Copilot をカスタマイズするための指示ファイル][instruction-files] +- [GitHub Copilot app のカスタマイズ][customize-app] +- [カスタム指示を作成するためのベストプラクティス][instructions-best-practices] +- [Awesome Copilot - 指示ファイルなどのリソース集][awesome-copilot] + +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/4-build-filtering/ +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[awesome-copilot]: https://awesome-copilot.github.com/ +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/4-build-filtering.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/4-build-filtering.md new file mode 100644 index 00000000..54a955df --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "レッスン 4 - Autopilot による機能の構築" +description: "GitHub Copilot app の Plan モードと Autopilot モードを使って静的なクライアント側フィルター機能を構築し、ドキュメント標準が継承されることを確認して、エージェントスキルで検証します。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +ここまで、プロジェクトに小さな更新をいくつか加えました。しかし、より本格的な変更には、よりしっかりしたプロセスが必要です。GitHub Copilot app は既存のフローと連携できるように設計されており、適切なものを適切な方法で構築できます。このレッスンから3回にわたり、一般的な開発プロセスに従います。まず Issue を使って新機能を生成し、エージェントスキルで検証テストと linter を実行します。 + +このレッスンでは、次の内容を学習します。 + +- フィルター機能に関する Issue から新しいセッションを開始する。 +- **Plan** モードで機能を計画し、**Autopilot** で構築する。 +- 生成されたコードが、以前マージしたドキュメント標準に従っていることを確認する。 +- プロジェクトの `quality-checks` スキルで作業を検証する。 + +## シナリオ + +ホームページにはすべてのゲームが一覧表示されますが、訪問者は一覧を絞り込めません。フィルター機能に関する Issue では、**カテゴリー**と**パブリッシャー**でゲームを絞り込めるようにすることが求められています。Copilot を使ってこの機能を実装します。 + +## 背景 + +AI コーディングエージェントを開発フローに導入しても、基本は変わりません。むしろ、基本はさらに重要になります。多くの開発者は、次のようなフローに従います。 + +1. 必要な作業の詳細が記載された Issue を開く。 +2. 構築する内容の計画を作成する。 +3. コードを構築してレビューする。 +4. テストを実行してコードを検証する。 +5. 新機能を手動で検証する。 +6. pull request (PR) を作成する。 +7. コードのレビューと継続的インテグレーションプロセスが成功したら、コードをマージする。 + +> [!NOTE] +> 正確な手順はチームや Organization によって異なりますが、多くの場合は上記の流れを変形したものです。 + +この標準的なアプローチを守ることで、AI が生成したコードが定められた要件を満たし、人間が作成したコードと同じ審査プロセスを通るようにできます。 + +## セッションモード + +**セッションモード**は、エージェントの自律性を制御します。プロンプトフィールド下のドロップダウンから設定し、いつでも変更できます。 + +- **Interactive**: ユーザーとエージェントが共同で作業します。エージェントは変更を提案し、続行前に入力を待ちます。 +- **Plan**: エージェントが最初に計画を作成します。計画実行前に内容をレビューして承認します。 +- **Autopilot**: エージェントが完全に自律して作業し、入力を待たずにコードの作成、テストの実行、反復を行います。 + +## フィルター機能を計画する + +潜在的な問題を見つける最適なタイミングは、コードを作成する前です。そのためには、事前に少し計画を立てるのが効果的です。Copilot と計画を立てると、一連の手順と採用するアプローチが生成されます。その計画をレビューし、改善案があれば提案してから、計画に基づいて Copilot にコードを生成させることができます。 + +Issue を開いて新しいセッションを開始し、Plan モードに切り替えて計画を作成します。 + +1. ナビゲーションタブから **My work** を選択します。 +2. **Allow users to filter games by category and publisher** というタイトルの Issue を選択します。 +3. 右上の **New session** を選択します。 + + ![GitHub Copilot app の Issue ビューで、右上の New session ボタンを矢印で示した画面](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. モードに **Plan** と表示されるまで Shift+Tab を選択します。 + + ![モードセレクターが Plan に設定され、矢印で示された GitHub Copilot app のプロンプトボックス](/images/learning-hub/copilot-workshops/app-4-plan-mode.png) + +5. 次のプロンプトを送信します。Issue から開始したため、フィルター機能の Issue はすでにこのセッションのコンテキストに含まれています。 + + ```plaintext + Plan the work based on the requirements documented in the issue. Please ask any clarifying questions you might have as you build the plan. + ``` + +6. 計画の作成中に、エージェントから追加の質問が提示される場合があります。自分で機能を構築するときの方針に基づいて回答します。 + +> [!NOTE] +> Copilot は確率的に動作するため、追加で尋ねられる質問は異なります。質問がまったくない場合もありますが、問題ありません。 + +7. 完了すると、Copilot が計画の概要を提示します。計画をレビューしてください。クエリの構築、フィルターコントロールの追加、テストの作成が提案されているはずです。必要に応じてフィードバックを返して改善できます。エージェントは提案を新しいバージョンに反映します。 + +## Autopilot で構築する + +計画が完成したので、Copilot に実装を構築させます。 + +1. **Plan summary** ダイアログのオプション一覧で、**Approve and implement with autopilot** に最も近いオプションを選択します。 + +Copilot が実装作業を開始します。 + +> [!NOTE] +> Copilot が必要なコードの作成を自動的に開始しない場合は、"Go ahead and start building out the plan!" のようなプロンプトを使って開始を依頼できます。 +> +> 必要な更新の作成には数分かかります。エージェントはファイルを編集および作成し、テストを作成して実行し、反復します。この時間に、ここまで学習した内容を振り返ったり、飲み物を用意したりできます。 + +## 変更をレビューする + +AI が生成したすべてのコードは、マージ前にレビューする必要があります。コードをレビューし、サイトを実行して問題がないことを確認します。 + +1. 右上の **Changes** を選択してコードの変更を開きます。 + + ![GitHub Copilot app のセッションパネルにあるタブで、Changes タブを矢印で示した画面](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. 変更をレビューします。新しい TypeScript ファイル、Astro ファイル、テストファイルが表示されます。新しいヘルパー関数には、レッスン3でマージしたドキュメント標準に従い、依頼していなくても TSDoc doc comment とファイルヘッダーコメントが含まれていることを確認します。 +3. Copilot app の右側にあるレビューパネルで **Terminal** を選択します。**Terminal** ボタンがない場合は、**+** (**Open in panel** というラベルが付いています) を選択してから **Terminal** を選択します。 + + ![GitHub Copilot app のレビューパネルにある Terminal ボタン](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +4. ターミナルウィンドウに次のコマンドを入力し、Web アプリの開発サーバーを起動します。 + + ```shell + npm run dev + ``` + +5. サーバーが起動したら、ブラウザーウィンドウを開きます。起動には少し時間がかかります。 +6. http://localhost:4321 に移動します。 +7. ランディングページでフィルターを使用できることを確認します。 +8. 問題がある場合は、Copilot に更新を依頼できます。 +9. 問題がなければ、ターミナルウィンドウに戻ります。 +10. Ctrl+C を選択して開発サーバーを停止します。 + +## quality-checks スキルで作業を検証する + +差分を目視で確認するだけで完了とすることもできますが、このチームには明確な品質基準と、それを繰り返し確認する方法があります。 + +**エージェントスキル**を使うと、テストの実行、ビルドの生成、pull request の作成など、繰り返し発生するタスクの実行方法を Copilot に指示できます。スキルは、エージェントが必要に応じて読み込める指示、スクリプト、リソースのフォルダーです。[Agent Skills はオープン標準][agent-skills-repo]であり、さまざまなエージェントで使用されています。そのため、同じスキルをエージェントモードの Copilot Chat、Copilot cloud agent、Copilot CLI、GitHub Copilot app で使用できます。 + +スキルはプロジェクトの `.github/skills` フォルダー、またはグローバルの `~/.copilot/skills` に配置します。各スキルは、YAML frontmatter (`name` と `description`) と、それに続く Markdown の指示が記載された `SKILL.md` ファイルを含むフォルダーです。 + +```yaml +--- +name: quality-checks +description: Run the project's test suites and linter to verify code changes are ready to commit, push, or merge. +--- +``` + +スキルには、スクリプト、アセット、参考資料を含むサブフォルダーも追加できます。完全な構造については、[エージェントスキルの仕様][agent-skills-spec]を参照してください。 + +> [!TIP] +> スキルは動的に読み込まれます。エージェントは `description` フィールドに基づいて適用するスキルを判断します。明確でシナリオに合った説明を記述することが、スキルが使用されるか無視されるかを左右します。 + +## quality-checks スキルを確認する + +スキルの内容を確認します。 + +1. レビューパネルが表示されていない場合は、右上の **Toggle review panel** を選択して開きます。 + + ![Create PR の右側にある Toggle review panel ボタンを矢印で示した GitHub Copilot app の上部ツールバー](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. **+** を選択し、レビューパネルに新しい項目を追加します。 +3. **File** を選択します。 +4. `SKILL.md` を検索します。 +5. ファイル一覧から `SKILL.md .github/skills/quality-checks` を選択して開きます。 +6. `name` と `description` を確認します。説明は、コード変更を commit、push、merge する前にテスト、lint、検証する必要がある場合に、このスキルを使用することをエージェントに伝えます。 +7. スキル全体を読みます。単体テスト、Playwright のエンドツーエンドテスト、ESLint の各スイートを実行するスクリプト、実行順序、一般的な失敗のデバッグ方法が記載されています。そのため、エージェントは推測するのではなく、チームの方法でチェックを実行できます。 + +## チェックを実行する + +同じフィルター機能のセッションで、エージェントに作業の検証を依頼します。スキル名を説明する必要はありません。エージェントがリクエストに一致するスキルを見つけます。 + +1. Copilot app に戻ります。 +2. スラッシュコマンド `/quality-checks` を使ってスキルを直接呼び出し、Enter を選択します。 +3. エージェントはスキルに従って単体テスト、linter、エンドツーエンドテストを実行し、結果を報告します。失敗したものがあれば、問題を修正して、すべて成功するまでチェックを再実行するよう依頼します。 +4. **このセッションを開いたままにします。** 次のレッスンでは Playwright MCP server を追加し、実際のブラウザーでフィルター機能が動作することを確認します。 + +## まとめと次のステップ + +実際の機能をエンドツーエンドで構築し、チームの基準に照らして検証しました。具体的には、次の作業を行いました。 + +- 最新のプロジェクトで、フィルター機能に関する Issue から新しいセッションを開始した。 +- Plan モードで機能を計画し、Autopilot で構築した。 +- 生成されたヘルパーが、レッスン3でマージしたドキュメント標準に従っていることを確認した。 +- `quality-checks` スキルで作業を検証した。 + +次は Playwright MCP server を接続し、実際のブラウザーでフィルター機能を確認するようエージェントに依頼します。[レッスン 5「Playwright MCP server によるテスト」][next-lesson]に進んでください。 + +## リソース + +- [GitHub Copilot app でのエージェントセッションの操作][agent-sessions] +- [Agent Skills について][about-agent-skills] +- [GitHub Copilot app のカスタマイズ][customize-app] +- [GitHub Copilot のクラウドサンドボックスとローカルサンドボックスについて][sandboxes] + +[ex0]: /ja-jp/learning-hub/copilot-workshops/app/0-prerequisites/ +[ex2]: /ja-jp/learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /ja-jp/learning-hub/copilot-workshops/app/3-custom-instructions/ +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/5-mcp-playwright/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[agent-skills-repo]: https://github.com/agentskills/agentskills +[agent-skills-spec]: https://agentskills.io/specification \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/5-mcp-playwright.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/5-mcp-playwright.md new file mode 100644 index 00000000..dd29e1a1 --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "レッスン 5 - Playwright MCP server によるテスト" +description: "Playwright MCP server を GitHub Copilot app に追加し、実際のブラウザーでフィルター機能を手動テストするようエージェントに依頼します。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +前のレッスンでは、プロジェクトの自動テストスイートを使ってフィルター機能を作成し、検証しました。テストによってコードの検証を自動化できますが、エージェント自身が動作を確認できるようにすることも効果的です。実際に作成している UI で問題を見つけた場合に、エージェントが対応できるようになります。MCP を使って AI エージェントに外部機能へのアクセスを提供する方法を確認し、Copilot が構築中のサイトを直接操作できるように Playwright MCP server を追加します。 + +このレッスンでは、次の内容を学習します。 + +- Model Context Protocol (MCP) の概要と、GitHub Copilot app での使用方法を理解する。 +- アプリの設定から Playwright MCP server を追加する。 +- エージェントにブラウザーを操作させ、フィルター機能を確認する。 + +## シナリオ + +単体テストとエンドツーエンドテストは重要ですが、UI の更新を検証するには、実際に UI を操作する必要があります。変更作業をさらに自動化し、更新が期待どおりに動作するという確信を高めるために、ユーザーと同じ方法で Copilot が作業中の Web サイトを使用できるようにします。 + +## Model Context Protocol (MCP) とは + +[Model Context Protocol (MCP)][mcp-blog-post] は、AI エージェントが外部のツールやサービスと通信するための手段を提供します。MCP を使うと、AI エージェントは外部のツールやサービスとリアルタイムで通信できます。その結果、最新情報へのアクセス (resources を使用) や、ユーザーに代わる操作 (tools を使用) が可能になります。 + +これらの tools と resources には、AI エージェントと外部のツールやサービスをつなぐ MCP server を通じてアクセスします。MCP server は、AI エージェントと外部ツール (既存の API や NPM パッケージなどのローカルツール) 間の通信を管理します。各 MCP server は、AI エージェントがアクセスできる異なる tools と resources のセットを表します。 + +よく使われる既存の MCP server には、次のものがあります。 + +- [**GitHub MCP Server**](https://github.com/github/github-mcp-server): GitHub リポジトリを管理するための API セットにアクセスできます。AI エージェントは、新しいリポジトリの作成、既存のリポジトリの更新、Issue と pull request の管理などを行えます。 +- [**Playwright MCP Server**][playwright-mcp-server]: Playwright を使ったブラウザー自動化機能を提供します。AI エージェントは、Web ページへの移動、フォームへの入力、ボタンの選択などを行えます。 + +さまざまな tools と resources にアクセスできる MCP server がほかにも多数あります。GitHub は、エコシステム内での発見と貢献を促進するために [MCP registry](https://github.com/mcp) をホストしています。 + +> [!CAUTION] +> MCP server は、プロジェクト内のほかの依存関係と同様に扱ってください。使用する前にソースコードを慎重に確認し、発行元を検証して、セキュリティ上の影響を考慮します。信頼できる MCP server だけを使用し、機密性の高いリソースや操作へのアクセスを許可するときは注意してください。 + +## Playwright MCP server を追加する + +MCP server はアプリの設定から追加して管理します。アプリには一般的なサーバーのカタログが含まれているため、[Playwright MCP server][playwright-mcp-server] は数回の操作で追加できます。 + +1. Ctrl+, を選択して、Copilot app の設定ページを開きます。 +2. **MCP servers** を選択します。 +3. 検索ダイアログに `Playwright` と入力します。 +4. **Popular MCP servers** の一覧から **Playwright** を選択します。 +5. **Add server** を選択し、利用可能な MCP server の一覧に追加します。 +6. Esc を選択して設定ダイアログを閉じます。 + +これで Playwright MCP server を追加できました。 + +## Playwright で機能を確認するよう Copilot に依頼する + +Playwright MCP server を使って機能を手動テストするよう Copilot に依頼します。 + +1. 次のプロンプトを使い、新しい機能を検証するよう Copilot に依頼します。 + + ```plaintext + Start the dev server then use the Playwright MCP server to validate the functionality you just added exists. Use the details in the issue to ensure the newly added behavior matches the specs. + ``` + +Copilot は Playwright MCP server を通じてブラウザーを起動し、各手順を実行して、確認結果を報告します。タスクの実行中、システム上で実際にブラウザーが開く様子を確認できます。 + +2. Issue の受け入れ条件と照らし合わせて概要を読みます。問題がある場合は、pull request を作成する前に追加の質問をするか、コードを修正するよう依頼します。 +3. 次のレッスンでこの作業を完了するため、セッションを開いたままにします。 + +これで Copilot は、ユーザーと同じように機能を確認し、ブラウザーでも動作を検証しました。 + +## まとめと次のステップ + +GitHub Copilot app から Playwright MCP server を使い、実際のブラウザーで機能を確認しました。学習した内容は次のとおりです。 + +- Model Context Protocol (MCP) の概要と、アプリで MCP tools を利用する仕組みを学習した。 +- アプリの設定から Playwright MCP server を追加した。 +- エージェントにブラウザーを操作させ、フィルター機能を確認した。 + +機能の構築と検証が完了し、動作することも確認できました。次は、**Agent Merge** を使って pull request の作成とマージをエージェントに任せ、機能をリリースします。[レッスン 6「Agent Merge によるマージ」][next-lesson]に進んでください。 + +## リソース + +- [MCP とは何か、なぜ注目されているのか][mcp-blog-post] +- [Microsoft Playwright MCP Server][playwright-mcp-server] +- [GitHub Copilot app での MCP server の構成][customize-app] + +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/6-agent-merge/ +[mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/ +[playwright-mcp-server]: https://github.com/microsoft/playwright-mcp +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/6-agent-merge.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/6-agent-merge.md new file mode 100644 index 00000000..916d1b8b --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "レッスン 6 - Agent Merge によるマージ" +description: "フィルター機能の pull request を作成して My work でレビューし、マージを妨げる問題の修正とマージを Agent Merge に任せて、段階的なマージ自動化の最上位まで進みます。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +フィルター機能の構築と検証が完了し、ブラウザーで動作することも確認できました。最後のステップはマージです。このハーネスではすでに2回マージしており、どちらも pull request を作成して github.com で自分でマージしました。今回は、pull request のライフサイクル全体をアプリ内から管理する **Agent Merge** に処理を任せます。 + +このレッスンでは、次の内容を学習します。 + +- Agent Merge の概要と、マージのライフサイクルを自動化する仕組みを学ぶ。 +- フィルター機能のセッションで Agent Merge を有効にする。 +- pull request の作成、CI の実行、すべて成功した後のマージを確認する。 + +## シナリオ + +ここ数回のモジュールでは、コードの作成から Copilot による UI の直接検証まで、さまざまなレベルの自動化を確認しました。開発をさらに高速化するために、Tailspin Toys は審査および検証済みの pull request を自動的にマージする方法を検討しています。 + +## Agent Merge の概要 + +**Agent Merge** を使うと、Copilot app で pull request をマージするまでの最終工程を自動化できます。有効にすると、アプリのセッションが pull request を読み取り、失敗した CI チェックの修正、レビューコメントへの対応、必要に応じたリベースなど、マージを妨げる問題に対処します。そして GitHub で許可され次第、pull request をマージします。バックグラウンドで動作し、アプリを再起動しても継続し、pull request がマージされると自動的に無効になります。 + +ここまでは、github.com で自分で **Merge pull request** を選択していました。Agent Merge はその責任をエージェントに移すため、エージェントが PR の完了までを管理している間に次のタスクへ進めます。作業のレビューと承認は引き続き自分で行い、エージェントには機械的な最終工程だけを任せます。 + +## Agent Merge で PR を管理する + +コードを手動でレビューし、テストを実行し、Copilot による UI の検証も完了しました。新しいコードをコードベースにマージします。Agent Merge に PR を継続的インテグレーション (CI) のプロセスからマージまで管理させます。 + +1. 前のモジュールでフィルター機能を追加していたセッションに戻ります。 +2. 右上隅にある **Create PR** の横のドロップダウンを選択します。 +3. **Agent merge** を選択して Agent Merge を有効にします。 + + ![GitHub Copilot app で展開された Create PR ドロップダウンの Agent merge オプションを矢印で示した画面](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. ボタンのテキストが **Agent merge** に変わります。 +5. **Agent merge** ボタンを選択し、Agent Merge のプロセスを開始します。 + +Copilot app が PR の作成と管理を開始します。最初にプロジェクトを調査して PR の最適な作成方法を判断し、新しい PR を作成します。 + +しばらくすると、Copilot が再び作業を開始し、リポジトリ上ですべてのテストを実行する CI プロセスなど、PR の条件を確認します。ほかのチームメンバーによるレビュー、実行が必要なチェック (CI プロセス)、PR をマージできるかどうかのステータスを報告します。 + +6. **Agent merge** の横にあるドロップダウンを選択してから **Merge pull request** を選択し、Agent Merge に pull request のマージを許可します。 + + ![Agent merge ドロップダウンで、エージェントに許可された Address reviews、Fix CI failures、Resolve conflicts の操作と、矢印で示された Merge pull request](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. すべての CI プロセスが成功すると、つまりテストに合格すると、Copilot が pull request をマージします。 + +## まとめと次のステップ + +コードの生成、テストと検証、pull request のプロセスなど、開発プロセスの複数の部分を自動化しました。具体的には、次の作業を行いました。 + +- Agent Merge の概要と、マージのライフサイクルを自動化する仕組みを学習した。 +- フィルター機能のセッションで Agent Merge を有効にした。 +- pull request の作成、CI の実行、すべて成功した後のマージを確認した。 + +次は、エージェントと一緒に作業を計画して視覚化する、より高度な方法である**キャンバス**を確認します。[レッスン 7「キャンバスを使った計画」][next-lesson]に進んでください。 + +## リソース + +- [GitHub Copilot app での Issue と pull request の管理][managing-issues-prs] +- [GitHub Copilot app について][about-copilot-app] + +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/7-canvases/ +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/7-canvases.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/7-canvases.md new file mode 100644 index 00000000..2097d21e --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "レッスン 7 - キャンバスを使った計画" +description: "GitHub Copilot app でエージェント主導の共有キャンバスを作成し、エージェントと一緒に作業を計画して追跡します。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +ここまでは、チャットを通じてエージェントを指示してきました。しかし、多くの作業は会話の中ではなく、ボード、ドキュメント、チェックリスト上で行われます。**キャンバス**は、まさにそのような作業のために、アプリ内でユーザーとエージェントが共有できる領域です。このレッスンでは、ここまで取り組んできたバックログの計画と追跡に使用する、シンプルなキャンバスを作成します。 + +このレッスンでは、次の内容を学習します。 + +- キャンバスの概要と使用する場面を理解する。 +- バックログをトリアージする共有 Kanban ボードのキャンバスを作成する。 +- キャンバスをリポジトリに保存し、チーム向けにマージする。 +- 新しいセッションでキャンバスを開き、そこから作業を開始する。 + +## シナリオ + +Issue の一覧は、どのような状況でも負担に感じることがあります。Tailspin Toys の開発者は、Issue をすばやくトリアージし、Copilot app で作業を開始できるツールを探しています。 + +## キャンバスとは + +[キャンバス][canvas-docs]は、計画、トリアージボード、リリースチェックリスト、ダッシュボード、ドキュメントなどの作業成果物を扱う、共有の対話型領域です。チャットは意図の説明や曖昧さの検討に適していますが、多くの作業は具体的な*領域*上で行われます。キャンバスを使うと、その領域でエージェントと直接共同作業できます。 + +キャンバスは**双方向**です。エージェントが作業中にキャンバスを更新できる一方で、ユーザーも同じ領域を編集できます。キャンバスを作成すると、エージェントはプロンプトとワークフローに基づいて内容を構築します。その後も、機能の追加、削除、修正を依頼できます。作成したキャンバスは、アプリの右側のパネルに開きます。 + +一般的な例は次のとおりです。 + +- 1日の計画を立て、Issue と pull request に優先順位を付けるための **Markdown canvases**。 +- ユーザーとエージェントがカードを追加し、作業を列間で移動する **Agentic kanban boards**。 +- リポジトリの重要な Issue と繰り返し現れるテーマをまとめる **Issue triage boards**。 + +## キャンバスを使用する理由 + +タスクに構造、反復、検証が必要で、チャットだけでは不十分な場合はキャンバスを使用します。キャンバスでは次のことができます。 + +- ワークフローに合った実際の成果物に、エージェントの作業を結び付ける。 +- 共有領域で作業を直接調整または修正し、その変更を基にエージェントに作業を続けさせる。 +- チャットの応答だけでなく、成果物への目に見える変更として進捗を確認する。 + +## 作業を追跡するキャンバスを作成する + +星評価、ドキュメント標準、フィルター機能をすべてマージし、多くの成果をリリースしました。しかし、バックログにはまだ項目が残っています。作業をすばやくトリアージするためのキャンバスを作成します。 + +1. GitHub Copilot app に戻ります。アプリを閉じている場合は開きます。 +2. **Home screen** を選択します。 +3. リポジトリに `tailspin-toys` が選択されていることを確認します。 +4. プロンプトボックスで次のプロンプトを使用し、要件を満たすキャンバスを作成します。 + + ```plaintext + Create a basic Kanban board canvas that allows me to quickly triage work. Highlight the three issues which are most likely to need attention right now, with the remainder in a second section down below. The top three cards should include a description of the issue's content and a justification of why they're at the top of the list. Each issue should have a button that allows me to add it to the current context for the current session so I can get to work on it straightaway. + ``` + +Copilot がキャンバスの作成を開始します。 + +> [!NOTE] +> 作成には数分かかります。複雑なタスクであるため、最初のバージョンでは満足できない場合があります。理想のツールになるまで、プロンプトで構築を続けるよう依頼できます。 + +## キャンバスを保存してリポジトリにマージする + +キャンバスは、指示ファイルやスキルと同様に、リポジトリのアセットにできます。Copilot にリポジトリへの追加とマージを依頼し、チーム全体で使用できるようにします。 + +1. 同じセッションで、次のプロンプトを使ってキャンバスをリポジトリに保存するよう Copilot に依頼します。 + + ```plaintext + Let's save this canvas definition to the repository so I can share it with my development team + ``` + +2. Copilot がキャンバスファイルを保存したら、右上隅にある **Create PR** の横のドロップダウンを選択します。 +3. **Agent merge** を選択して Agent Merge を有効にします。 + + ![GitHub Copilot app で展開された Create PR ドロップダウンの Agent merge オプションを矢印で示した画面](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. ボタンのテキストが **Agent merge** に変わります。 +5. **Agent merge** ボタンを選択し、Agent Merge のプロセスを開始します。 + +Copilot app が PR の作成と管理を開始します。最初にプロジェクトを調査して PR の最適な作成方法を判断し、PR を作成します。 + +しばらくすると、Copilot が再び作業を開始し、リポジトリ上ですべてのテストを実行する CI プロセスなど、PR の条件を確認します。ほかのチームメンバーによるレビュー、実行が必要なチェック (CI プロセス)、PR をマージできるかどうかのステータスを報告します。 + +6. **Agent merge** の横にあるドロップダウンを選択してから **Merge pull request** を選択し、Agent Merge に pull request のマージを許可します。 + + ![Agent merge ドロップダウンで、エージェントに許可された Address reviews、Fix CI failures、Resolve conflicts の操作と、矢印で示された Merge pull request](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. すべての CI プロセスが成功するまで待ちます。成功すると、Copilot が pull request を自動的にマージします。 + +これでチーム用の新しい共有キャンバスを作成できました。 + +## キャンバスで作業する + +キャンバスを作成できたので、新しいセッションを開始して使用します。 + +1. Copilot app で **tailspin-toys** の横にある **New session** を選択し、新しいセッションを開始します。 +2. 次のプロンプトを使い、トリアージ用キャンバスを開くよう Copilot に依頼します。 + + ```plaintext + Open the triage issues canvas + ``` + +3. 作成したキャンバスが新しいセッションで開いたことを確認します。 +4. 最も関心のある Issue の1つで **Add to current context** を選択します。 +5. Copilot が Issue の作業を開始します。 + +これで、作成したキャンバスを使って開発プロセスを効率化できました。 + +## まとめと次のステップ + +ユーザーとエージェントが共同作業できる共有領域を作成しました。具体的には、次の作業を行いました。 + +- キャンバスの概要と使用する場面を学習した。 +- エージェントと共有の Kanban トリアージボードのキャンバスを作成した。 +- Agent Merge を使ってキャンバスをリポジトリに保存し、マージした。 +- 新しいセッションでキャンバスを開き、そこから作業を開始した。 + +バックログを追跡できるようになったので、ここまで構築した内容と今後の進め方を振り返ります。[レッスン 8「振り返りと次のステップ」][next-lesson]に進んでください。 + +## リソース + +- [GitHub Copilot app での canvas extension の操作][canvas-docs] +- [Awesome Copilot の Canvases][awesome-copilot-canvases] +- [GitHub Copilot app について][about-copilot-app] + +[next-lesson]: /ja-jp/learning-hub/copilot-workshops/app/8-review/ +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/8-review.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/8-review.md new file mode 100644 index 00000000..9eb64557 --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "レッスン 8 - 振り返りと次のステップ" +description: "GitHub Copilot app のハーネスを振り返り、繰り返し発生する作業を自動化して、次に学ぶ内容を確認します。" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +ここ数回のレッスンでは、GitHub Copilot app を使い、アイデアから機能のマージまでを実践しました。取り組んだ内容は次のとおりです。 + +- リポジトリを接続し、アプリのワークスペースと用意されたバックログを確認した。 +- 直接指定したタスクと Issue からセッションを開始し、Plan モードと Autopilot モードでエージェントの動作を制御した。 +- カスタム指示と再利用可能なスキルでエージェントをガイドした。 +- Playwright MCP server を使い、実際のブラウザーで作業をテストした。 +- 共有キャンバスでエージェントと共同作業した。 +- github.com で自分でマージする方法から、**Agent Merge** に pull request のマージを任せる方法まで、段階的なマージ自動化を使って変更をリリースした。 + +繰り返し発生する作業を自動化し、ベストプラクティスと今後の進め方を確認します。 + +## 繰り返し発生する作業を自動化する + +アプリでは、**automations** を使って、スケジュールまたはオンデマンドでエージェントを実行できます。新しい Issue のトリアージや最近のアクティビティの振り返りなど、定型的なタスクに適しています。シンプルで破壊的でない automation を作成します。 + +1. サイドバーで **Automations** を選択してから **New automation** を選択します。 +2. `Recap my recent work` などの名前を付けます。 +3. トリガーを選択します。**Manual** はオンデマンドで実行し、**On a schedule** は自動的に実行し、**When an issue is created** は新しい Issue に反応します。このレッスンでは **Manual** を選択します。 +4. automation が何も変更しないように、次の例のような読み取り専用のプロンプトを入力します。 + + ```plaintext + Summarize the pull requests merged in this repository over the last week, and list any issues still open in the backlog. + ``` + +5. プロジェクト (Tailspin Toys リポジトリ) を選択し、automation を作成します。 +6. オンデマンドで実行し、結果を確認します。 + +> [!TIP] +> Automations はローカルまたはクラウドで実行できます。スケジュールに従って無人で実行する場合は、**Run in the cloud** を有効にし、automation に使用を許可する **Tools** を選択します。出力を信頼できるようになるまでは、スケジュールされた automations の範囲を限定し、破壊的でないものにしてください。 + +## ベストプラクティス + +AI ツールを使用するときは、その周辺の基盤が出力の品質を左右します。このワークショップでは、指示ファイル、スキル、カスタムエージェントがそれぞれ役割を果たしました。これらに投資し、セッション間で再利用してください。 + +タスクに合わせて**モードとモデル**を選択します。構築前にアプローチを検討するには **Plan**、対象を絞った変更で作業に関与し続けるには **Interactive**、範囲が明確で分離されたタスクに限って **Autopilot** を使用します。定型的な編集には高速なモデルを選び、複雑な作業には推論能力が高く、より多くの推論を行うモデルを選びます。 + +基盤と同じくらい、コンテキストも重要です。何を、なぜ、どのように構築するかを明確に説明すると、出力は大きく変わります。アイデアを本格的なセッションに移す前に範囲を決める場所として、Quick chats が役立ちます。 + +## さらに確認する機能 + +コアワークフローを学習しました。ほかにも確認する価値がある機能があります。 + +- 完全なセッションを必要としない、その場限りの簡単な質問に使用する **Quick chats**。 +- 構築前に問題について対話し、重要なフィードバックを得るための **Rubber duck**。 +- ロール、その tools、指示をまとめ、繰り返し使用する専門的な作業に対応する [**Custom agents**][custom-agents]。 +- セッションで起きたことの記録を生成する [`/chronicle`][chronicle]。 +- Ollama、Foundry Local、LM Studio を介したローカルモデルなど、独自のプロバイダーのモデルを使用する [Bring your own key (BYOK)][byok]。 +- GitHub がホストする分離環境でセッションを実行する [Cloud sandboxes][sandboxes]。 +- アプリを直接リポジトリ、セッション、プロンプトの画面で開く [Deep links][deep-links]。 + +## 次のステップ + +ツールを使いこなす最良の方法は、使い続けることです。実稼働コード、趣味のコード、長年構想していながら構築できていなかった小さなアプリなどに活用してください。学んだことをチームと共有し、チームからも学びましょう。そして、引き続きドキュメントを確認してください。 + +GitHub Copilot エコシステムをさらに学ぶには、[VS Code ハーネス](/ja-jp/learning-hub/copilot-workshops/vscode/)、[Copilot CLI ハーネス](/ja-jp/learning-hub/copilot-workshops/cli/)、[Cloud agent ハーネス](/ja-jp/learning-hub/copilot-workshops/cloud/)を確認してください。 + +## リソース + +- [GitHub Copilot app について][about-copilot-app] +- [GitHub Copilot app の概要][getting-started] +- [GitHub Copilot app のカスタマイズ][customize] +- [Automations の使用][using-automations] +- [Canvas extensions の操作][canvas-docs] +- [クラウドサンドボックスとローカルサンドボックスについて][sandboxes] + +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[customize]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[using-automations]: https://docs.github.com/copilot/how-tos/github-copilot-app/using-automations +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/index.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/index.md new file mode 100644 index 00000000..a2797eb1 --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/app/index.md @@ -0,0 +1,57 @@ +--- +title: "GitHub Copilot app" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[**GitHub Copilot app**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) は Copilot CLI を基盤とするデスクトップアプリケーションで、エージェント主導の開発を単一の作業用ワークスペースで実現します。並列エージェントセッション、切り替え可能なセッションモード、共有キャンバス、GitHub Issue と pull request のネイティブ管理機能を備えています。さらに、リベース、レビューのフィードバック、CI の修正、マージまで pull request を導く **Agent Merge** も利用できます。 + +一連のレッスンでは、アプリをインストールしてプロジェクトを設定した後、アプリのワークスペースと、テンプレートによって用意されたバックログを確認します。まず、星評価を追加する小さな変更に取り組みます。次に、Issue に基づいてカスタム指示の標準を追加し、分離されたエージェントセッションでフィルター機能を構築して、再利用可能なスキルで検証します。Playwright MCP server を追加して実際のブラウザーで機能を確認した後、段階的にマージの自動化を進め、最後は **Agent Merge** で pull request をマージします。最後に、共有キャンバスで共同作業し、繰り返し発生する作業を自動化します。アイデアから機能のマージまで、開発の一連の流れを体験できます。 + +## レッスン + +| レッスン | トピック | 説明 | +|--------|-------|-------------| +| [0. 前提条件][ex0] | セットアップ | Node.js をインストールし、Tailspin Toys プロジェクトの自分用コピーを作成します | +| [1. Copilot app のインストール][ex1] | セットアップ | アプリをインストールしてプロジェクトを接続し、ワークスペースを確認します | +| [2. 最初のエージェントセッションの実行][ex2] | 最初の変更 | セッションを開始し、最初の pull request として小さな変更をリリースします | +| [3. カスタム指示による Copilot のガイド][ex3] | コンテキスト | Issue に基づいてドキュメント標準を追加し、マージします | +| [4. Autopilot による機能の構築][ex4] | コア機能 | Plan と Autopilot を使ってフィルター機能を構築し、スキルで検証します | +| [5. Playwright MCP によるテスト][ex5] | 外部ツール | Playwright MCP server を追加し、ブラウザーで機能を確認します | +| [6. Agent Merge によるマージ][ex6] | マージ | Agent Merge でフィルター機能の pull request を修正してマージします | +| [7. キャンバスを使った計画][ex7] | コラボレーション | 共有キャンバスを作成し、作業の計画と追跡に使用します | +| [8. 振り返りと次のステップ][ex8] | まとめ | 繰り返し発生するタスクを自動化し、次に学ぶ内容を確認します | + +## 前提条件 + +このワークショップに参加する前に、次のものを用意してください。 + +- [ ] 有効な **Copilot Student、Pro、Pro+、Business、Enterprise** のいずれかのプランが設定された GitHub アカウント +- [ ] **macOS、Linux、Windows** のいずれかを実行するコンピューター +- [ ] コンピューターに[インストールされた Git][install-git] + +> [!TIP] +> 有料プランを利用していない場合、認証済みの学生は [GitHub Education][callout-student-plan-education] を通じて GitHub Copilot を無料で利用できます。**Copilot Student** プランには、このワークショップで使用するエージェント、MCP、コードレビュー、Copilot CLI の各機能が含まれているため、すべてのハーネスを完了できます。 + +> [!NOTE] +> Copilot app は codespace ではなく自分のコンピューターで実行するため、[レッスン 0][ex0] では、アプリをインストールする前に Node.js をインストールし、プロジェクトの自分用コピーを作成します。 + +> [!NOTE] +> Copilot Business または Copilot Enterprise を使用している場合、アプリを使用するには管理者が **Copilot CLI** ポリシーを有効にする必要があります。 + +## はじめる + +[**レッスン 0「前提条件」から始める →**][ex0] + +[ex0]: /ja-jp/learning-hub/copilot-workshops/app/0-prerequisites/ +[ex1]: /ja-jp/learning-hub/copilot-workshops/app/1-install-copilot-app/ +[ex2]: /ja-jp/learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /ja-jp/learning-hub/copilot-workshops/app/3-custom-instructions/ +[ex4]: /ja-jp/learning-hub/copilot-workshops/app/4-build-filtering/ +[ex5]: /ja-jp/learning-hub/copilot-workshops/app/5-mcp-playwright/ +[ex6]: /ja-jp/learning-hub/copilot-workshops/app/6-agent-merge/ +[ex7]: /ja-jp/learning-hub/copilot-workshops/app/7-canvases/ +[ex8]: /ja-jp/learning-hub/copilot-workshops/app/8-review/ +[install-git]: https://github.com/git-guides/install-git +[callout-student-plan-education]: https://github.com/education/students \ No newline at end of file diff --git a/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/index.md b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/index.md new file mode 100644 index 00000000..98b0ba69 --- /dev/null +++ b/website/src/content/docs/ja-jp/learning-hub/copilot-workshops/index.md @@ -0,0 +1,41 @@ +--- +title: "GitHub Copilot のエージェントを実践で学ぶ" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +GitHub Copilot に最近追加された機能は、ソフトウェア開発ライフサイクル (SDLC) 全体を通して開発者を支援する強力なツールです。GitHub の Issue や pull request を使った作業、外部サービスとの連携、そしてもちろんコードの作成も含まれます。このラボでは、実際のユースケースを通して機能を試し、ツールを最大限に活用するためのヒントを紹介します。 + +> [!CAUTION] +> GitHub Copilot は決定論的ではなく確率的に動作するため、生成されるコードや変更されるファイルなどは毎回異なる場合があります。そのため、ラボ内のスクリーンショットやコード スニペットと、実際の結果に多少の違いが生じることがあります。これは想定される動作であり、この種のツールが持つ特性によるものです。 +> +> 何かが壊れているように見える場合や正しく動作しない場合は、メンターに相談してください。 + +## 利用環境を選ぶ + +GitHub Copilot は、どの環境で作業していても利用できます。希望する開発方法に合った利用環境を選び、共通の Tailspin Toys バックログに沿って演習を進めます。どの利用環境にも専用のセットアップ手順が用意されているため、選んだものからすぐに始められます。 + +### 🖥️ [VS Code](/ja-jp/learning-hub/copilot-workshops/vscode/) + +**Visual Studio Code** と GitHub Codespaces 内で GitHub Copilot を使用します。普段使っているエディターを離れることなく、Copilot Chat のエージェント モード、MCP サーバー、カスタム エージェントを利用できます。AI 支援を IDE に直接組み込んで使いたい場合に最適です。 + +### 💻 [Copilot CLI](/ja-jp/learning-hub/copilot-workshops/cli/) + +**GitHub Copilot CLI** は、ターミナルで動作するエージェント型アシスタントです。インストールして MCP サーバーに接続し、プラン モードでコードを生成できます。さらに、独自のスキル、カスタム エージェント、スラッシュ コマンドをすべてコマンド ラインから構築できます。 + +### 🤖 [Copilot App](/ja-jp/learning-hub/copilot-workshops/app/) + +**GitHub Copilot app** は、Copilot CLI を基盤とするデスクトップ アプリケーションです。複数のエージェント セッションを並行して実行し、セッション モードの切り替え、キャンバスでの共同作業、GitHub Issue と pull request の管理をアプリ内で行えます。さらに **Agent Merge** を使用すると、リベース、レビュー フィードバックへの対応、CI の修正、マージまで、pull request の一連の作業を進められます。 + +### ☁️ [Copilot Cloud Agent](/ja-jp/learning-hub/copilot-workshops/cloud/) + +**Copilot cloud agent** は、GitHub Issue の作業をバックグラウンドで進める非同期のペア プログラマーです。作業の割り当て、カスタム エージェントによる指示、エージェント ダッシュボードでの進捗確認、作成された pull request のレビューを行えます。 + +## シナリオ + +架空の企業 Tailspin Toys に新しく参加した開発者として作業します。Tailspin Toys は、開発者をテーマにしたボード ゲームのクラウドファンディングを提供しています。これは巨大な市場です。チームのバックログはすでに GitHub Issue として登録されており、フィルタリングやページネーションなどの機能開発に加えて、アクセシビリティやコーディング規約などの品質改善にもすぐに取り組めます。サイトと Copilot の機能を確認しながら反復的に作業し、タスクを完了させます。 + +## はじめる + +上から利用環境を選んで開始します。どの利用環境も、開発に必要なセットアップから始まります。 \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/0-prerequisites.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/0-prerequisites.md new file mode 100644 index 00000000..466bd236 --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "Lesson 0 - 필수 조건" +description: "Tailspin Toys 프로젝트에 필요한 Node.js를 설치하고 템플릿에서 리포지토리 복사본을 만들어 GitHub Copilot app 레슨을 준비합니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +GitHub Copilot app은 Copilot과 GitHub를 모두 사용하는 중앙 허브 역할을 하는 데스크톱 앱입니다. 이 앱에서 이슈와 끌어오기 요청에 빠르게 접근하고 GitHub Copilot을 사용해 빌드할 수 있습니다. 이 워크숍에서는 Astro로 구축된 Tailspin Toys 앱과 GitHub Copilot app을 모두 로컬에서 사용합니다. 시작하기 전에 Node.js가 로컬에 설치되어 있는지 확인한 다음 Copilot app을 설치합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- 프로젝트 테스트를 컴퓨터에서 실행할 수 있도록 Node.js를 설치합니다. +- 템플릿에서 Tailspin Toys 프로젝트의 복사본을 만듭니다. + +## Node.js 설치 + +여러 레슨에서 에이전트에게 기능을 구축하고 Tailspin Toys 테스트 도구 모음을 로컬에서 실행하도록 요청합니다. 이 작업에는 프로젝트에 필요한 유일한 런타임인 [**Node.js**][nodejs]가 필요합니다. **22 이상** 버전을 설치합니다. 현재 **LTS** 릴리스가 안전한 선택입니다. + +모든 플랫폼에서 가장 간단한 방법은 공식 설치 프로그램을 사용하는 것입니다. + +1. 운영 체제에서 Windows Terminal, macOS 터미널 또는 평소 사용하는 도구로 터미널 창을 엽니다. +2. 다음 명령을 실행하여 Node.js 22 이상이 설치되어 있는지 확인합니다. + + ```shell + node --version + ``` + +3. `v22` 이상의 숫자가 표시되면 다음 섹션으로 건너뛸 수 있습니다. + +> [!TIP] +> Node가 설치되어 있지 않거나 업데이트해야 하는 경우에만 다음 단계를 수행하면 됩니다. + +4. [Node.js 다운로드 페이지][node-download]를 엽니다. +5. 운영 체제에 맞는 **LTS** 빌드를 다운로드합니다. +6. 설치 프로그램을 실행하고 기본값을 적용합니다. Windows에서는 **Add to PATH** 옵션을 선택한 상태로 유지합니다. +7. 설치가 끝나면 새 터미널 창을 엽니다. +8. 새 터미널 창에서 다음 명령을 실행하여 설치를 확인합니다. + + ```bash + node --version + ``` + +9. `v22.x.x` 이상이 표시되어야 합니다. + +> [!TIP] +> 컨테이너를 선호합니까? [**Docker**][docker]가 있다면 Node.js를 로컬에 설치하는 대신 리포지토리의 [dev container][dev-containers]를 사용할 수 있습니다. 이 컨테이너에는 Node가 포함되어 있으므로 두 가지가 모두 필요하지는 않습니다. + +## 실습 리포지토리 설정 + +Tailspin Toys 프로젝트의 복사본에서 작업합니다. 지금 [템플릿 리포지토리][template-repository]에서 복사본을 만듭니다. 새 리포지토리에는 실습에 필요한 모든 파일이 들어 있으며, 다음 레슨에서 앱에 연결합니다. + +1. 새 브라우저 창에서 이 실습의 GitHub 리포지토리인 `https://github.com/github-samples/tailspin-toys`로 이동합니다. +2. 실습 리포지토리 페이지에서 **Use this template** 버튼을 선택한 다음 **Create a new repository**를 선택하여 리포지토리 복사본을 만듭니다. + + ![드롭다운에서 Create a new repository가 선택된 Use this template 버튼](/images/learning-hub/copilot-workshops/app-0-use-template.png) + +3. GitHub 또는 Microsoft가 진행하는 이벤트에서 워크숍을 수행하는 경우 멘토가 제공한 지침을 따릅니다. 그렇지 않으면 GitHub Copilot에 접근할 수 있는 조직에 새 리포지토리를 만들 수 있습니다. + + ![github-samples/tailspin-toys가 템플릿으로 설정되고 리포지토리 이름이 입력된 Create a new repository 양식](/images/learning-hub/copilot-workshops/app-0-create-repository.png) + +4. 이 실습에서 나중에 참조할 수 있도록 만든 리포지토리 경로(**organization-or-user-name/repository-name**)를 기록합니다. + +> [!NOTE] +> 템플릿에서 리포지토리를 만들면 GitHub 이슈 백로그가 자동으로 생성됩니다. 워크숍 전체에서 이 이슈를 사용하므로 직접 등록할 항목은 없습니다. + +## 요약 및 다음 단계 + +설정이 완료되었습니다. 프로젝트를 컴퓨터에서 빌드하고 테스트할 수 있도록 Node.js를 설치하고, 템플릿에서 Tailspin Toys 리포지토리의 복사본을 만들었습니다. + +다음으로 GitHub Copilot app을 설치하고, 방금 만든 리포지토리를 연결하고, 워크스페이스를 살펴봅니다. [레슨 1 - GitHub Copilot app 설치][next-lesson]를 계속 진행합니다. + +## 리소스 + +- [Node.js 다운로드][node-download] +- [템플릿에서 리포지토리 만들기][template-repository] +- [GitHub Copilot app 정보][about-copilot-app] + +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/1-install-copilot-app/ +[nodejs]: https://nodejs.org/ +[node-download]: https://nodejs.org/en/download +[docker]: https://www.docker.com/products/docker-desktop/ +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/1-install-copilot-app.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/1-install-copilot-app.md new file mode 100644 index 00000000..9e0f9636 --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "Lesson 1 - GitHub Copilot app 설치" +description: "GitHub Copilot app을 설치하고, 템플릿에서 만든 리포지토리를 연결하고, 워크스페이스를 살펴보고, 빠른 채팅을 사용해 봅니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[**GitHub Copilot app**][about-copilot-app]은 에이전트 기반 개발을 위한 데스크톱 애플리케이션입니다. GitHub Copilot CLI를 기반으로 하며 GitHub와 기본적으로 통합되어 리포지토리, 브랜치, CI 파이프라인을 바로 사용할 수 있습니다. 모든 작업을 직접 수행하고 반복 작업을 자동화하는 방식 대신, 각자 격리된 워크스페이스에서 여러 에이전트를 병렬로 지시하는 워크플로를 위해 설계되었습니다. Node.js를 설치하고 프로젝트 복사본을 준비했으므로 이제 앱을 설치하고 해당 리포지토리를 연결합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- GitHub Copilot app을 설치하고 로그인합니다. +- GitHub 리포지토리에서 프로젝트를 앱에 추가합니다. +- 템플릿에서 미리 생성한 백로그를 포함하여 워크스페이스를 살펴봅니다. +- 빠른 채팅을 사용하여 앱 자체에 관해 알아봅니다. + +## 시나리오 + +팀에서 늘어나는 백로그를 처리하기 위해 AI 에이전트를 도입하고 있습니다. Copilot app에서는 이슈 선택, 에이전트 실행, 변경 내용 검토, 끌어오기 요청 병합을 한곳에서 지시할 수 있습니다. 이 레슨에서는 앱을 설치하고 연결한 다음 프로젝트에 관한 대화를 시작하는 방법을 익힙니다. + +> [!NOTE] +> 적격 Copilot 플랜인 Copilot Student 또는 유료 플랜(Pro, Pro+, Business, Enterprise)이 필요합니다. Copilot Business 또는 Copilot Enterprise를 사용하는 경우 앱을 사용하려면 관리자가 **Copilot CLI** 정책을 활성화해야 합니다. + +## GitHub Copilot app 설치 및 구성 + +GitHub Copilot app을 사용하려면 먼저 앱을 설치해야 합니다. Windows, macOS, Linux용 버전이 제공됩니다. 앱을 설치하고 인증한 다음 Tailspin Toys 리포지토리를 앱에 추가합니다. + +1. 브라우저에서 [GitHub Copilot app 랜딩 페이지][download-app]를 엽니다. +2. 플랫폼에 맞는 앱을 다운로드하고 랜딩 페이지의 지침에 따라 설치합니다. +3. 설치가 끝나면 앱을 엽니다. +4. **Sign in to GitHub**을 선택하고 안내에 따라 인증합니다. GitHub Enterprise Server를 사용하는 경우 **Use GitHub Enterprise**를 선택하고 메시지가 표시되면 서버 주소를 입력합니다. +5. 인증한 후 리포지토리를 연결하라는 메시지가 표시되면 방금 만든 `/tailspin-toys`라는 이름의 Tailspin Toys 리포지토리를 선택합니다. +6. **Continue**를 선택하여 온보딩을 계속합니다. +7. 테마를 선택하라는 메시지가 표시되면 가장 마음에 드는 테마를 선택한 다음 **Finish**를 선택합니다. + +> [!NOTE] +> Tailspin Toys 복사본이 목록에 자동으로 나타나지 않으면 앱에서 온보딩을 완료한 후 추가할 수 있습니다. 온보딩이 끝나면 Copilot app에 홈 화면이 표시됩니다. 여기에서 **Choose from GitHub**을 선택하고 리포지토리 이름(\/tailspin-toys)을 검색한 다음 해당 리포지토리를 선택합니다. 이제 리포지토리가 Copilot app에 추가됩니다. + +## 워크스페이스 살펴보기 + +프로젝트를 연결했으므로 잠시 워크스페이스의 구성을 살펴봅니다. 앱의 사이드바는 몇 가지 영역으로 구성됩니다. + +- **Sessions** — 에이전트가 작업하는 곳입니다. 각 세션은 격리된 워크스페이스에서 실행되므로 변경 내용이 충돌하지 않게 여러 세션을 동시에 실행할 수 있습니다. 다음 레슨에서 첫 번째 세션을 시작합니다. +- **Quick chats** — 별도의 브랜치나 워크스페이스가 필요하지 않은 질문과 브레인스토밍을 위한 가벼운 대화입니다. 이 레슨의 마지막에서 사용해 봅니다. +- **My work** — 앱의 **GitHub 기본 통합**을 통해 이슈와 끌어오기 요청을 표시합니다. 앱을 벗어나지 않고 이슈와 끌어오기 요청을 찾아 필터링하고, CI 상태를 확인하고, 이슈에서 세션을 시작하고, 끌어오기 요청을 검토할 수 있습니다. +- **Automations** — 일정에 따라 또는 요청 시 실행되는 저장된 에이전트 작업입니다. 이 실습 과정의 끝부분에서 하나를 만듭니다. + +### 미리 생성된 백로그 찾기 + +앱은 GitHub와 기본적으로 통합되므로 리포지토리에서 대기 중인 작업을 앱 안에서 바로 볼 수 있습니다. 템플릿에서 리포지토리를 만들 때 이슈 백로그가 생성되었습니다. 백로그가 있는지 확인합니다. + +1. 사이드바에서 **My work**를 선택합니다. +2. 템플릿은 백로그에 여덟 개의 이슈를 생성했습니다. 이 하네스에서는 다음 세 이슈에 집중합니다. 표시되는지 확인합니다. + + - Allow users to filter games by category and publisher + - Update our repository coding standards + - Implement pagination on the game list page + +3. 이슈를 선택하여 세부 정보를 읽습니다. 각 이슈는 에이전트 세션을 시작하는 지점이기도 합니다. 이 실습 과정의 뒷부분에서 이 이슈를 바탕으로 작업을 시작합니다. + +> [!NOTE] +> My work의 항목 목록은 Copilot app에 추가한 리포지토리의 항목만 표시하도록 자동으로 필터링됩니다. 다른 리포지토리의 작업 항목을 보려면 해당 리포지토리를 앱에 추가합니다. + +## 빠른 채팅 사용해 보기 + +앱에 익숙해지는 좋은 방법은 앱을 사용하여 *앱 자체*에 관해 알아보는 것입니다. 이때 **빠른 채팅**이 적합합니다. 빠른 채팅에서는 브랜치나 작업 트리를 만들지 않고 질문하거나 브레인스토밍할 수 있으므로, 세션이 필요 없는 일회성 질문에 알맞습니다. + +1. 사이드바에서 **Quick chats** 옆의 **+**를 선택하여 새 채팅을 엽니다. +2. 앱의 세션이 어떻게 작동하는지 질문합니다. + + ```plaintext + How does the GitHub Copilot app use worktrees? + ``` + +3. 대화 보기에서 응답을 읽습니다. 각 세션이 격리된 git 작업 트리에서 실행되므로 변경 내용이 충돌하지 않게 여러 에이전트를 병렬로 실행할 수 있다는 점을 확인할 수 있습니다. 언제든지 대화를 계속하거나 새 채팅을 시작할 수 있습니다. + +## 요약 및 다음 단계 + +GitHub Copilot app을 설치하고 프로젝트를 연결하고 워크스페이스를 살펴봤습니다. 다음 방법을 배웠습니다. + +- 앱을 설치하고 GitHub에 로그인합니다. +- GitHub 리포지토리에서 프로젝트를 추가합니다. +- 워크스페이스를 살펴보고 **My work**에서 미리 생성된 백로그를 찾습니다. +- 빠른 채팅을 사용하여 일회성 질문을 합니다. + +다음으로 첫 번째 에이전트 세션을 시작하고 프로젝트를 처음으로 변경하여 게임 카드에 별점을 표시합니다. [레슨 2 - 첫 번째 에이전트 세션 실행][next-lesson]을 계속 진행합니다. + +## 리소스 + +- [GitHub Copilot app 정보][about-copilot-app] +- [GitHub Copilot app 시작하기][getting-started] +- [GitHub Copilot app에서 에이전트 세션 사용][agent-sessions] + +[ex0]: /ko-kr/learning-hub/copilot-workshops/app/0-prerequisites/ +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/2-add-star-rating/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[download-app]: https://gh.io/app \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/2-add-star-rating.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/2-add-star-rating.md new file mode 100644 index 00000000..ec5874bf --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "Lesson 2 - 첫 번째 에이전트 세션 실행" +description: "GitHub Copilot app에서 첫 번째 에이전트 세션을 시작하고 게임 카드를 조금 변경한 다음 첫 번째 끌어오기 요청으로 병합합니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +이전 레슨에서는 워크스페이스를 살펴보고 빠른 채팅을 사용했습니다. 이제 **에이전트 세션**을 시작하고 프로젝트를 처음으로 변경합니다. 변경 범위는 작게 유지합니다. 게임 데이터에는 이미 별점이 있지만 홈페이지의 게임 카드에는 아직 표시되지 않습니다. 에이전트에게 별점을 표시하도록 요청하고, 변경 내용을 검토하고, 첫 번째 끌어오기 요청으로 병합합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- 에이전트 세션을 시작하고 세션의 구조를 알아봅니다. +- 에이전트에게 프로젝트를 작고 구체적으로 변경하도록 요청합니다. +- 워크스페이스의 diff 보기에서 변경 내용을 검토합니다. +- 앱을 로컬에서 실행하여 브라우저에서 변경 내용을 확인합니다. +- 첫 번째 끌어오기 요청을 열고 병합합니다. + +## 시나리오 + +Tailspin Toys의 각 게임에는 별점이 있을 수 있으며, 별점은 이미 게임 세부 정보 페이지에 표시됩니다. 하지만 홈페이지의 게임 카드에는 제목, 카테고리, 퍼블리셔, 설명만 표시됩니다. 첫 세션 연습으로 에이전트에게 각 카드에 기존 별점을 표시하도록 요청합니다. 첫 번째 세션에 적합한 작고 독립적인 변경입니다. + +## 세션 구조 + +**세션**은 격리된 자체 워크스페이스에서 실행되는 에이전트와의 대화입니다. 모든 세션에는 **전용 git 작업 트리와 브랜치**가 제공됩니다. 따라서 변경 내용이 충돌하지 않게 한 세션에서는 기능을 추가하고 다른 세션에서는 버그를 수정하는 등 여러 세션을 동시에 실행할 수 있습니다. 세션은 사이드바에서 리포지토리별로 그룹화되며, 원하는 세션을 선택하여 전환할 수 있습니다. + +세션 안에는 에이전트와의 **대화**, 에이전트가 파일을 탐색하고 편집할 때의 **도구 활동**, diff와 함께 표시되는 **변경된 파일** 목록이 있습니다. + +## 세션을 시작하고 변경 요청하기 + +새 세션을 시작하여 프로젝트를 탐색하고 기능을 구현합니다. [이전 레슨][prior-lesson]에서 GitHub 리포지토리의 프로젝트를 추가했습니다. 해당 리포지토리에 새 세션을 만들고 변경을 요청합니다. + +1. GitHub Copilot app으로 돌아가거나 앱을 엽니다. +2. **Home screen**을 선택합니다. +3. 리포지토리로 `tailspin-toys`가 선택되어 있는지 확인합니다. + + ![리포지토리 선택기가 tailspin-toys로 설정되고 프롬프트 아래에 모델 선택기가 표시된 GitHub Copilot app 프롬프트 상자](/images/learning-hub/copilot-workshops/app-2-start-session.png) + +4. 다음 프롬프트를 사용하여 변경을 요청합니다. + + ```plaintext + On the game cards, show each game's star rating. The Game type already includes a starRating field — it's a number out of 5, or null when a game hasn't been rated yet. Display it on each card in src/components/GameCard.astro, and when starRating is null show "No rating yet" instead. Keep the change small and don't restructure the card layout. + ``` + +> [!NOTE] +> 프롬프트에 Copilot이 업데이트할 파일 이름을 포함했습니다. Copilot이 작업에 포함할 파일을 반드시 지정할 필요는 없지만, 방향을 제시하면 Copilot이 코드를 더 빠르게 생성하고 토큰 사용량을 줄이는 데 도움이 됩니다. + +5. Enter를 선택하여 Copilot에 프롬프트를 보냅니다. + +Copilot app은 먼저 프로젝트의 격리된 복사본인 새 작업 트리를 만들고 작업을 시작합니다. 그런 다음 프로젝트를 탐색하고 새 기능을 추가하기 위해 업데이트해야 할 파일을 찾은 후 필요한 코드를 만듭니다. 이제 Copilot app으로 새 기능을 추가했습니다. + +## diff 검토 + +AI가 생성한 모든 변경 내용은 작더라도 병합하기 전에 검토해야 합니다. Copilot app에서 바로 변경 내용을 살펴봅니다. + +1. 앱 오른쪽 위에서 **Toggle review panel**을 선택합니다. Copilot이 적용한 보류 중인 모든 변경 내용을 보여 주는 diff 화면이 열립니다. + + ![Create PR 오른쪽의 Toggle review panel 버튼을 화살표로 가리키는 GitHub Copilot app 위쪽 도구 모음](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. 게임 세부 정보를 표시하는 핵심 파일인 `GameCard.astro`에 코드가 추가된 것을 확인합니다. 다음 코드와 비슷해야 합니다. 별점이 있으면 표시하고 `starRating`이 `null`이면 "No rating yet"으로 대체하는 작은 블록입니다. + + ```astro + {game.starRating !== null ? ( + + ★ {game.starRating} / 5 + + ) : ( + + No rating yet + + )} + ``` + +> [!NOTE] +> 모든 생성형 AI 도구와 마찬가지로 Copilot은 결정론적이 아니라 확률적으로 작동하므로 정확한 코드는 위 예제와 다를 수 있지만 대체로 비슷해야 합니다. + +## 변경 내용 확인 + +코드를 읽고 작동한다고 가정해서는 안 됩니다. 모든 내용을 시각적으로 테스트해야 합니다. 터미널에서 앱을 시작한 다음 모든 기능이 작동하는지 확인합니다. Copilot app에는 터미널이 기본 제공됩니다. + +1. Copilot app 오른쪽의 검토 패널에서 **Terminal**을 선택합니다. **Terminal** 버튼이 없으면 **+**(**Open in panel** 레이블)를 선택한 다음 **Terminal**을 선택합니다. + + ![GitHub Copilot app 검토 패널의 Terminal 버튼](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +2. 터미널 창에 다음 명령을 입력하여 웹앱의 개발 서버를 시작합니다. + + ```shell + npm run dev + ``` + +3. 서버가 시작되면 브라우저 창을 엽니다. 잠시만 기다리면 됩니다. +4. [http://localhost:4321](http://localhost:4321)로 이동합니다. +5. 이제 랜딩 페이지의 모든 게임에 별점이 표시되어야 합니다. +6. 터미널 창으로 돌아갑니다. +7. Ctrl+C를 선택하여 개발 서버를 중지합니다. + +## 첫 번째 끌어오기 요청 열기 및 병합 + +변경 내용이 올바르게 작동하므로 이제 제공할 차례입니다. 에이전트에게 끌어오기 요청을 열도록 요청한 다음 github.com에서 직접 검토하고 병합합니다. 지금은 이 과정을 수동으로 관리합니다. 이후 레슨에서는 Copilot이 일부 작업을 자동으로 처리하는 방법을 살펴봅니다. + +1. 오른쪽 위에서 **Create PR**을 선택합니다. +2. 메시지가 표시되면 **Sign in with your browser**를 선택하고 안내에 따라 인증합니다. +3. Copilot이 PR을 만들기 시작합니다. + +PR이 만들어지면 Copilot은 리포지토리에서 실행해야 하는 워크플로를 모니터링합니다. 잠시 후 오른쪽 위의 버튼이 **Ready to merge**로 바뀝니다. 이는 PR을 병합할 준비가 되었다는 표시입니다. + +4. 채팅 바로 위의 **PR** 버블을 선택하여 검토 창에서 PR을 열고 끌어오기 요청을 확인합니다. 필요에 따라 여기에서 PR을 검토할 수 있습니다. +5. 준비가 되면 **Ready to merge**를 선택합니다. +6. 새 대화 상자에서 **Merge pull request**를 선택하여 끌어오기 요청을 병합합니다. + +이제 웹사이트에 새 기능을 제공했습니다. + +## 요약 및 다음 단계 + +첫 번째 에이전트 세션을 시작하고 첫 번째 변경을 제공했습니다. 구체적으로 다음 작업을 수행했습니다. + +- 에이전트 세션을 시작하고 세션의 구조를 알아봤습니다. +- 에이전트에게 게임 카드를 작고 구체적으로 변경하도록 지시했습니다. +- 워크스페이스의 diff 보기에서 변경 내용을 검토했습니다. +- 앱을 로컬에서 실행하여 브라우저에서 별점을 확인했습니다. +- 끌어오기 요청을 열고 github.com에서 직접 병합했습니다. + +다음으로 백로그의 이슈 중 하나에서 시작하여 앱으로 리포지토리에 사용자 지정 지침 표준을 추가합니다. [레슨 3 - 사용자 지정 지침으로 Copilot 안내][next-lesson]를 계속 진행합니다. + +## 리소스 + +- [GitHub Copilot app에서 에이전트 세션 사용][agent-sessions] +- [GitHub Copilot app 정보][about-copilot-app] +- [GitHub Copilot app으로 이슈 및 끌어오기 요청 관리][managing-issues-prs] + +[prior-lesson]: /ko-kr/learning-hub/copilot-workshops/app/1-install-copilot-app/#github-copilot-app-설치-및-구성 +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/3-custom-instructions/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/3-custom-instructions.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/3-custom-instructions.md new file mode 100644 index 00000000..0ea5c234 --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "Lesson 3 - 사용자 지정 지침으로 Copilot 안내" +description: "GitHub Copilot app을 사용하여 백로그의 이슈에서 시작해 리포지토리에 사용자 지정 지침 표준을 추가하고 변경 내용을 끌어오기 요청으로 병합합니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +생성형 AI를 사용할 때는 컨텍스트가 중요합니다. 작업을 특정 방식으로 수행해야 하거나 Copilot이 알아야 할 배경 정보가 있다면 해당 컨텍스트를 제공해야 합니다. 가장 강력한 도구 중 하나는 원하는 코드의 *내용*뿐 아니라 코드의 *구조*도 설명하는 [지침 파일][instruction-files]입니다. 이 레슨에서는 리포지토리에 문서화 표준을 추가합니다. 이후 대부분의 작업과 마찬가지로 백로그의 이슈에서 시작하여 에이전트가 변경하도록 합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- 리포지토리 지침과 경로 범위 지침 파일이 에이전트에 전달되는 방식을 살펴봅니다. +- 백로그의 지침 이슈에서 세션을 시작합니다. +- 에이전트에게 `.github/copilot-instructions.md`에 문서화 표준을 추가하도록 요청합니다. +- 변경 내용을 검토하고 끌어오기 요청으로 병합합니다. + +## 시나리오 + +모범적인 개발 조직인 Tailspin Toys에는 개발 방식에 관한 지침과 요구 사항이 있습니다. 여기에는 다음 항목이 포함됩니다. + +- 코드에 TSDoc doc comments 형식의 문서를 추가해야 합니다. +- 형식을 문서화하고 린팅으로 적용해야 합니다. + +지침 파일을 사용하면 Copilot이 이러한 방식에 맞게 작업을 수행하는 데 필요한 정보를 제공할 수 있습니다. + +## 지침 파일 + +사용자 지정 지침은 Copilot에 컨텍스트와 기본 설정을 제공하여 코딩 스타일과 요구 사항을 더 잘 이해하게 합니다. 이 기능을 사용하면 Copilot이 더 관련성 높은 제안과 코드 조각을 생성하도록 안내할 수 있습니다. 선호하는 코딩 규칙과 라이브러리는 물론 코드에 포함할 주석 유형까지 지정할 수 있습니다. 리포지토리 전체에 적용되는 지침이나 작업 수준의 컨텍스트를 제공하는 특정 파일 유형용 지침을 만들 수 있습니다. + +지침 파일에는 두 가지 유형이 있습니다. + +- `.github/copilot-instructions.md`는 리포지토리의 **모든** 요청에서 Copilot에 전달되는 단일 지침 파일입니다. 이 파일에는 Copilot에 보내는 대부분의 채팅 또는 CLI 요청과 관련된 프로젝트 수준 정보를 포함해야 합니다. 사용 중인 기술 스택, 구축 중인 항목의 개요, 모범 사례, 기타 전역 지침을 포함할 수 있습니다. +- 특정 작업이나 파일 유형에 맞게 `.github/instructions/*.instructions.md` 파일을 만들 수 있습니다. TypeScript 또는 Astro 같은 특정 언어나 UI 구성 요소 또는 새 단위 테스트 집합 만들기와 같은 작업에 관한 지침을 제공할 수 있습니다. + +> [!NOTE] +> Copilot은 AGENTS.md, CLAUDE.md, GEMINI.md를 통해 지침을 가져오는 다른 표준도 지원하므로 항상 올바른 컨텍스트를 제공할 수 있습니다. + +### 지침 파일 관리 모범 사례 + +지침 파일 만들기를 모두 다루는 것은 이 워크숍의 범위를 벗어납니다. 하지만 샘플 프로젝트의 예제는 대표적인 접근 방식을 보여 줍니다. 개괄적인 지침은 다음과 같습니다. + +- `copilot-instructions.md`의 지침은 구축 중인 항목의 설명, 프로젝트 구조, 전역 코딩 표준 등 프로젝트 수준의 안내에 집중합니다. +- `*.instructions.md` 파일을 사용하여 파일 유형(단위 테스트, Astro 구성 요소, 데이터 계층) 또는 특정 작업에 관한 구체적인 지침을 제공합니다. +- 자연어를 사용하고 지침을 명확하게 유지합니다. 코드가 따라야 하는 예와 피해야 하는 예를 제공합니다. + +AI를 사용하는 방식이 하나로 정해져 있지 않듯 지침 파일을 만드는 방식도 하나로 정해져 있지 않습니다. 실험을 통해 프로젝트에 가장 적합한 방법을 찾을 수 있습니다. + +> [!TIP] +> GitHub Copilot을 사용하는 모든 프로젝트에는 충실한 지침 파일 모음이 있어야 합니다. 이 프로젝트의 파일을 살펴보면 여러 코드 파일 유형을 위한 지침 파일이 있다는 것을 알 수 있습니다. +> +> 템플릿이나 시작점을 찾고 있습니까? 지침 파일, 사용자 지정 에이전트, 기타 리소스가 가득한 리포지토리인 [awesome-copilot][awesome-copilot]을 살펴봅니다. + +## 프로젝트의 사용자 지정 지침 파일 살펴보기 + +이 리포지토리와 함께 제공되는 지침 파일을 읽어 봅니다. 핵심 `copilot-instructions.md` 하나와 여러 작업을 위한 `*.instructions.md` 파일 모음이 있습니다. 편집기 또는 GitHub 웹 UI에서 파일을 엽니다. + +1. 검토 패널이 표시되지 않으면 오른쪽 위의 **Toggle review panel**을 선택하여 엽니다. + + ![Create PR 오른쪽의 Toggle review panel 버튼을 화살표로 가리키는 GitHub Copilot app 위쪽 도구 모음](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. 검토 패널에 새 항목을 추가하려면 **+**를 선택합니다. +3. **File**을 선택합니다. +4. `copilot-instructions.md`를 검색합니다. +5. 파일 목록에서 `copilot-instructions.md`를 선택하여 엽니다. +6. 파일을 살펴봅니다. 프로젝트에 관한 간단한 설명과 **Agent notes**, **Code standards**, **Scripts**, **Repository Structure** 같은 섹션을 확인합니다. **Code standards** 아래에서 중첩된 **GitHub Actions Workflows** 지침을 확인합니다. 이 내용은 Copilot과의 모든 상호 작용에 적용됩니다. +7. 폴더 탐색기를 열려면 **Show folder view**를 선택합니다. + + ![GitHub Copilot app에서 파일이 열린 검토 패널의 Show folder view 버튼](/images/learning-hub/copilot-workshops/app-show-folder-view.png) + +8. `.github/instructions` 폴더로 이동하여 파일을 살펴봅니다. Astro 파일, Drizzle 데이터 계층, 테스트 등에 관한 지침이 있습니다. +9. `.github/instructions/unit-tests.instructions.md`를 엽니다. 위쪽의 `applyTo` 필드는 지침이 적용되는 파일을 결정하는 glob을 리포지토리 루트 기준으로 설정합니다. 여기서는 TypeScript 테스트 파일(예: `**/*.test.ts`와 일치하는 파일)이 모두 일치합니다. +10. 이 프로젝트의 단위 테스트 작성에 관한 구체적인 지침을 확인합니다. +11. 마지막으로 `.github/instructions/drizzle.instructions.md`를 열고 아래쪽으로 스크롤합니다. 다른 지침 파일(예: `unit-tests.instructions.md`)과 프로젝트의 기존 파일로 연결되는 링크를 확인합니다. 이를 통해 큰 지침 집합을 더 작고 재사용 가능한 파일로 나누고 Copilot이 코드를 생성할 때 따를 예제를 지정할 수 있습니다. 이 경로는 리포지토리 루트가 아니라 지침 파일을 기준으로 합니다. + +> [!NOTE] +> `copilot-instructions.md`의 **Code formatting requirements** 섹션에는 프로젝트의 코딩 표준이 있지만 아직 코드 내 문서는 요구하지 않습니다. 다음 단계에서 TSDoc doc comments와 파일 주석 헤더에 관한 규칙을 추가합니다. + +## 지침 이슈에서 시작 + +이전 레슨에서는 직접 프롬프트로 세션을 시작했습니다. 하지만 대부분의 작업은 이슈에서 시작합니다. 지침 파일 업데이트를 위해 등록된 이슈를 바탕으로 새 세션을 만들고 업데이트를 요청합니다. + +> [!NOTE] +> 지침 파일은 Copilot이 생성하는 코드에 큰 영향을 주므로 Copilot을 명확하게 안내하는지 주의 깊게 확인해야 합니다. 이 레슨처럼 Copilot으로 초안을 만든 다음 요구 사항을 충족하는지 직접 검토하는 방법이 좋습니다. + +1. 사이드바에서 **My work**를 선택합니다. +2. **Update our repository coding standards** 이슈를 선택하여 엽니다. +3. 오른쪽 위의 **New session**을 선택하여 이슈를 바탕으로 새 세션을 시작합니다. + + ![오른쪽 위의 New session 버튼을 화살표로 가리키는 GitHub Copilot app 이슈 보기](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. 다음 프롬프트를 사용하여 이슈에 문서화된 요구 사항에 맞게 지침 파일을 업데이트하도록 Copilot에 요청합니다. + + ```plaintext + Following this issue, make the updates to the instructions files in this project to meet the requirements documented. Don't create the PR quite yet! + ``` + +Copilot이 업데이트를 적용합니다. + +## 변경 내용 검토 + +Copilot이 적용한 업데이트를 읽고, 업데이트된 지침을 바탕으로 앞으로 생성할 코드의 예제도 요청합니다. + +1. 오른쪽 위의 **Changes**를 선택하여 코드 변경 내용을 엽니다. + + ![Changes 탭을 화살표로 가리키는 GitHub Copilot app 세션 패널 탭](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. 업데이트된 지침 파일을 검토합니다. 코드에 문서와 주석을 추가하는 지침이 있는지 확인합니다. + +> [!NOTE] +> AI는 결정론적이 아니라 확률적으로 작동하므로 정확한 텍스트는 달라질 수 있습니다. + +3. 다음 프롬프트를 사용하여 앞으로 생성할 코드의 예제를 만들도록 Copilot에 요청합니다. + + ```plaintext + Do not make any updates, but show me what the code would look like. Based on the new instructions, if I asked Copilot to create a new library component to return all Publishers what would that code look like? + ``` + +4. Copilot이 제안한 코드를 검토합니다. 업데이트된 지침에서 요구한 대로 TSDoc doc comments와 파일 헤더 주석이 포함되어 있는지 확인합니다. + +이제 프로젝트의 지침 파일을 업데이트하고 그 영향을 확인했습니다. + +## 끌어오기 요청 열기 및 병합 + +지침 파일은 리포지토리 자산이므로 팀의 다른 구성원과 공유됩니다. 다른 자산과 마찬가지로 작업 내용이 포함된 PR을 만듭니다. + +1. 오른쪽 위에서 **Create PR**을 선택합니다. +2. 메시지가 표시되면 **Sign in with your browser**를 선택하고 안내에 따라 인증합니다. +3. Copilot이 PR을 만들기 시작합니다. + +PR이 만들어지면 Copilot은 리포지토리에서 실행해야 하는 워크플로를 모니터링합니다. 잠시 후 오른쪽 위의 버튼이 **Ready to merge**로 바뀝니다. 이는 PR을 병합할 준비가 되었다는 표시입니다. + +4. **Ready to merge**를 선택합니다. +5. 새 대화 상자에서 **Merge pull request**를 선택하여 끌어오기 요청을 병합합니다. + +> [!NOTE] +> 표준을 기본 브랜치에 병합하면 모든 사용자와 새 세션에서 프로젝트의 일부로 사용됩니다. 다음 레슨에서 최신 기본 브랜치로 필터링 세션을 시작하면 에이전트가 이 표준을 자동으로 따릅니다. 요청하지 않아도 생성된 TypeScript에 TSDoc doc comments가 포함되는 것을 통해 지침이 생성 코드에 미치는 작지만 실제적인 영향을 확인할 수 있습니다. + +## 요약 및 다음 단계 + +앱이 지침 파일에서 컨텍스트를 가져오는 방식을 살펴본 다음 세션을 사용하여 리포지토리 전체에 적용되는 표준을 추가하고 병합했습니다. 구체적으로 다음 작업을 수행했습니다. + +- 리포지토리의 `copilot-instructions.md`와 경로 범위 `*.instructions.md` 파일을 살펴봤습니다. +- 백로그의 지침 이슈에서 세션을 시작했습니다. +- 에이전트에게 `.github/copilot-instructions.md`에 문서화 표준을 추가하도록 요청했습니다. +- 변경 내용을 검토하고 끌어오기 요청으로 병합했습니다. + +다음으로 새 세션에서 필터링 기능을 구축하고 방금 병합한 표준이 자동으로 적용되는지 확인합니다. [레슨 4 - Autopilot으로 기능 구축][next-lesson]을 계속 진행합니다. + +## 리소스 + +- [GitHub Copilot 사용자 지정을 위한 지침 파일][instruction-files] +- [GitHub Copilot app 사용자 지정][customize-app] +- [사용자 지정 지침 만들기 모범 사례][instructions-best-practices] +- [Awesome Copilot — 지침 파일 및 기타 리소스 모음][awesome-copilot] + +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/4-build-filtering/ +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[awesome-copilot]: https://awesome-copilot.github.com/ +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/4-build-filtering.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/4-build-filtering.md new file mode 100644 index 00000000..2d926c2b --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "Lesson 4 - Autopilot으로 기능 구축" +description: "GitHub Copilot app의 Plan 및 Autopilot 모드로 정적 클라이언트 쪽 필터링 기능을 구축하고, 문서화 표준이 적용되는지 확인하고, 에이전트 스킬로 검증합니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +지금까지 프로젝트를 작게 몇 차례 업데이트했습니다. 하지만 더 큰 변경에는 더 탄탄한 프로세스가 필요합니다. GitHub Copilot app은 기존 흐름과 함께 작동하도록 구축되어 올바른 항목을 올바른 방식으로 만들 수 있게 합니다. 이 레슨은 일반적인 개발 프로세스를 따르는 세 레슨 중 첫 번째입니다. 이슈를 사용하여 새 기능을 생성하고 에이전트 스킬로 검증 테스트와 린터를 실행합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- 필터링 이슈에서 새 세션을 시작합니다. +- **Plan** 모드로 기능을 계획한 다음 **Autopilot**으로 구축합니다. +- 생성된 코드가 이전에 병합한 문서화 표준을 따르는지 확인합니다. +- 프로젝트의 `quality-checks` 스킬로 작업을 검증합니다. + +## 시나리오 + +홈페이지에는 모든 게임이 표시되지만 방문자는 목록을 좁힐 수 없습니다. 필터링 이슈에서는 **category**와 **publisher**로 게임을 필터링할 수 있게 해 달라고 요청합니다. Copilot을 사용하여 이 기능을 구현합니다. + +## 배경 + +AI 코딩 에이전트를 개발 흐름에 도입해도 기본 원칙은 달라지지 않습니다. 오히려 더 중요해집니다. 대부분의 개발자는 다음과 비슷한 흐름을 따릅니다. + +1. 수행할 작업의 세부 정보가 담긴 이슈를 엽니다. +2. 구축할 항목을 계획합니다. +3. 코드를 구축하고 검토합니다. +4. 테스트를 실행하여 코드를 검증합니다. +5. 새 기능을 수동으로 검증합니다. +6. 끌어오기 요청(PR)을 만듭니다. +7. 코드를 검토하고 지속적 통합 프로세스가 성공하면 코드를 병합합니다. + +> [!NOTE] +> 정확한 세부 사항은 팀과 조직에 따라 달라지지만 대부분 위 주제의 변형입니다. + +이 표준 접근 방식을 따르면 AI가 생성한 코드가 요구 사항을 충족하고 사람이 작성한 코드와 동일한 검증 과정을 거치게 할 수 있습니다. + +## 세션 모드 + +**세션 모드**는 에이전트의 자율성 수준을 제어합니다. 프롬프트 필드 아래의 드롭다운에서 설정하고 언제든지 변경할 수 있습니다. + +- **Interactive**: 사용자와 에이전트가 함께 작업합니다. 에이전트는 변경을 제안하고 진행하기 전에 사용자의 입력을 기다립니다. +- **Plan**: 에이전트가 먼저 계획을 만듭니다. 에이전트가 실행하기 전에 계획을 검토하고 승인합니다. +- **Autopilot**: 에이전트가 입력을 기다리지 않고 코드 작성, 테스트 실행, 반복 작업을 완전히 자율적으로 수행합니다. + +## 필터링 기능 계획 + +잠재적인 문제는 코드를 작성하기 전에 발견하는 것이 가장 좋으며, 사전 계획이 이를 돕습니다. Copilot에 계획을 요청하면 단계와 접근 방식을 문서화합니다. 계획을 검토하고 개선 제안을 한 후 해당 계획을 바탕으로 Copilot이 코드를 생성하게 할 수 있습니다. + +이슈를 열고 새 세션을 시작한 다음 Plan 모드로 전환하여 계획을 만듭니다. + +1. 탐색 탭에서 **My work**를 선택합니다. +2. **Allow users to filter games by category and publisher** 이슈를 선택합니다. +3. 오른쪽 위의 **New session**을 선택합니다. + + ![오른쪽 위의 New session 버튼을 화살표로 가리키는 GitHub Copilot app 이슈 보기](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. 모드에 **Plan**이 표시될 때까지 Shift+Tab을 선택합니다. + + ![Plan으로 설정된 모드 선택기를 화살표로 가리키는 GitHub Copilot app 프롬프트 상자](/images/learning-hub/copilot-workshops/app-4-plan-mode.png) + +5. 다음 프롬프트를 보냅니다. 이슈에서 세션을 시작했으므로 필터링 이슈는 이미 세션의 컨텍스트에 있습니다. + + ```plaintext + Plan the work based on the requirements documented in the issue. Please ask any clarifying questions you might have as you build the plan. + ``` + +6. 에이전트가 계획을 세우면서 후속 질문을 할 수 있습니다. 기능을 구축할 방식에 따라 답변합니다. + +> [!NOTE] +> Copilot은 확률적으로 작동하므로 정확한 후속 질문은 달라질 수 있으며 질문을 하지 않을 수도 있습니다. 이는 정상입니다. + +7. 완료되면 Copilot이 계획 요약을 제공합니다. 계획을 검토합니다. 쿼리 구축, 필터 컨트롤 추가, 테스트를 제안해야 합니다. 원하는 경우 피드백을 제공하여 구체화할 수 있으며 에이전트는 제안을 새 버전에 반영합니다. + +## Autopilot으로 구축 + +계획을 만들었으므로 Copilot이 구현을 구축하게 합니다. + +1. **Plan summary** 대화 상자의 옵션 목록에서 **Approve and implement with autopilot**과 가장 가까운 옵션을 선택합니다. + +Copilot이 구현 작업을 시작합니다. + +> [!NOTE] +> Copilot이 필요한 코드를 자동으로 만들기 시작하지 않으면 "Go ahead and start building out the plan!" 같은 프롬프트로 요청할 수 있습니다. +> +> 필요한 업데이트를 만드는 데 몇 분 정도 걸립니다. 에이전트는 파일을 편집하고 만들며, 테스트를 작성하고 실행하고, 반복해서 개선합니다. 지금까지 살펴본 내용을 돌아보거나 잠시 쉬어도 좋습니다. + +## 변경 내용 검토 + +AI가 생성한 모든 코드는 병합 전에 검토해야 합니다. 코드를 검토하고 사이트를 실행하여 올바르게 작동하는지 확인합니다. + +1. 오른쪽 위의 **Changes**를 선택하여 코드 변경 내용을 엽니다. + + ![Changes 탭을 화살표로 가리키는 GitHub Copilot app 세션 패널 탭](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. 변경 내용을 검토합니다. 새 TypeScript, Astro, 테스트 파일이 표시되어야 합니다. 새 도우미 함수에 TSDoc doc comments와 파일 헤더 주석이 있는지 확인합니다. 레슨 3에서 병합한 문서화 표준이 요청 없이 자동으로 적용된 것입니다. +3. Copilot app 오른쪽의 검토 패널에서 **Terminal**을 선택합니다. **Terminal** 버튼이 없으면 **+**(**Open in panel** 레이블)를 선택한 다음 **Terminal**을 선택합니다. + + ![GitHub Copilot app 검토 패널의 Terminal 버튼](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +4. 터미널 창에 다음 명령을 입력하여 웹앱의 개발 서버를 시작합니다. + + ```shell + npm run dev + ``` + +5. 서버가 시작되면 브라우저 창을 엽니다. 잠시만 기다리면 됩니다. +6. [http://localhost:4321](http://localhost:4321)로 이동합니다. +7. 이제 랜딩 페이지에 필터가 표시되어야 합니다. +8. 올바르게 보이지 않는 항목이 있으면 Copilot에 업데이트를 요청할 수 있습니다. +9. 만족하면 터미널 창으로 돌아갑니다. +10. Ctrl+C를 선택하여 개발 서버를 중지합니다. + +## quality-checks 스킬로 작업 검증 + +diff를 눈으로 확인하고 끝낼 수도 있지만 팀에는 정해진 품질 기준과 이를 반복해서 확인하는 방법이 있습니다. + +**에이전트 스킬(Agent skills)**은 테스트 실행, 빌드 생성, 끌어오기 요청 만들기처럼 반복 가능한 작업을 수행하는 방법을 Copilot에 안내합니다. 스킬은 에이전트가 필요할 때 불러올 수 있는 지침, 스크립트, 리소스가 담긴 폴더입니다. [Agent Skills는 공개 표준][agent-skills-repo]이며 다양한 에이전트에서 사용되므로 동일한 스킬을 에이전트 모드의 Copilot Chat, Copilot cloud agent, Copilot CLI, GitHub Copilot app에서 사용할 수 있습니다. + +스킬은 프로젝트의 `.github/skills` 폴더 또는 전역 `~/.copilot/skills`에 있습니다. 각 스킬은 YAML frontmatter의 `name`과 `description` 뒤에 Markdown 지침이 이어지는 `SKILL.md` 파일을 포함하는 폴더입니다. + +```yaml +--- +name: quality-checks +description: Run the project's test suites and linter to verify code changes are ready to commit, push, or merge. +--- +``` + +스킬에는 스크립트, 자산, 참조 자료가 담긴 하위 폴더도 포함할 수 있습니다. 전체 구조는 [에이전트 스킬 사양][agent-skills-spec]에서 확인할 수 있습니다. + +> [!TIP] +> 스킬은 동적으로 불러옵니다. 에이전트는 `description` 필드를 바탕으로 적용할 스킬을 결정하므로, 명확하고 시나리오에 맞는 설명이 있어야 스킬을 제대로 사용할 수 있습니다. + +## quality-checks 스킬 살펴보기 + +스킬의 작동 방식을 살펴봅니다. + +1. 검토 패널이 표시되지 않으면 오른쪽 위의 **Toggle review panel**을 선택하여 엽니다. + + ![Create PR 오른쪽의 Toggle review panel 버튼을 화살표로 가리키는 GitHub Copilot app 위쪽 도구 모음](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. 검토 패널에 새 항목을 추가하려면 **+**를 선택합니다. +3. **File**을 선택합니다. +4. `SKILL.md`를 검색합니다. +5. 파일 목록에서 `SKILL.md .github/skills/quality-checks`를 선택하여 엽니다. +6. `name`과 `description`을 확인합니다. 설명은 커밋, 푸시, 병합 전에 코드 변경을 테스트하거나 린팅하거나 검증할 때 이 스킬을 사용하라고 에이전트에 알려 줍니다. +7. 스킬을 읽습니다. 어떤 스크립트가 어떤 도구 모음(단위 테스트, Playwright 엔드투엔드 테스트, ESLint)을 어떤 순서로 실행하는지, 일반적인 실패를 디버그하는 방법은 무엇인지 확인합니다. 따라서 에이전트가 추측하지 않고 팀의 방식대로 검사를 실행합니다. + +## 검사 실행 + +동일한 필터링 세션에서 에이전트에게 작업을 검증하도록 요청합니다. 스킬 이름을 설명하지 않아도 에이전트가 요청과 일치시킵니다. + +1. Copilot app으로 돌아갑니다. +2. 슬래시 명령 `/quality-checks`를 사용하여 스킬을 직접 호출하고 Enter를 선택합니다. +3. 에이전트는 스킬에 따라 단위 테스트, 린터, 엔드투엔드 테스트를 실행하고 결과를 보고합니다. 실패하는 항목이 있으면 문제를 수정하고 모두 통과할 때까지 검사를 다시 실행하도록 요청합니다. +4. **이 세션을 열어 둡니다.** 다음 레슨에서 Playwright MCP 서버를 추가하고 실제 브라우저에서 필터링 기능이 작동하는지 확인합니다. + +## 요약 및 다음 단계 + +실제 기능을 처음부터 끝까지 구축하고 팀의 품질 기준에 맞게 검증했습니다. 구체적으로 다음 작업을 수행했습니다. + +- 최신 프로젝트의 필터링 이슈에서 새 세션을 시작했습니다. +- Plan 모드로 기능을 계획하고 Autopilot으로 구축했습니다. +- 생성된 도우미가 레슨 3에서 병합한 문서화 표준을 따르는지 확인했습니다. +- `quality-checks` 스킬로 작업을 검증했습니다. + +다음으로 Playwright MCP 서버를 연결하고 에이전트에게 실제 브라우저에서 필터링 기능을 살펴보도록 요청합니다. [레슨 5 - Playwright MCP 서버로 테스트][next-lesson]를 계속 진행합니다. + +## 리소스 + +- [GitHub Copilot app에서 에이전트 세션 사용][agent-sessions] +- [Agent Skills 정보][about-agent-skills] +- [GitHub Copilot app 사용자 지정][customize-app] +- [GitHub Copilot용 클라우드 및 로컬 샌드박스 정보][sandboxes] + +[ex0]: /ko-kr/learning-hub/copilot-workshops/app/0-prerequisites/ +[ex2]: /ko-kr/learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /ko-kr/learning-hub/copilot-workshops/app/3-custom-instructions/ +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/5-mcp-playwright/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[agent-skills-repo]: https://github.com/agentskills/agentskills +[agent-skills-spec]: https://agentskills.io/specification \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/5-mcp-playwright.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/5-mcp-playwright.md new file mode 100644 index 00000000..86ceb576 --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "Lesson 5 - Playwright MCP 서버로 테스트" +description: "GitHub Copilot app에 Playwright MCP 서버를 추가하고 에이전트에게 실제 브라우저에서 필터링 기능을 수동으로 테스트하도록 요청합니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +이전 레슨에서는 프로젝트의 자동화된 테스트 도구 모음으로 필터링 기능을 만들고 검증했습니다. 테스트는 코드 검증을 자동화하지만 에이전트가 동작을 직접 확인하게 하는 것도 강력합니다. 에이전트는 자신이 만드는 실제 UI에서 발견한 문제에 대응할 수 있습니다. MCP가 AI 에이전트에 외부 기능을 제공하는 방식을 살펴보고, Copilot이 구축 중인 사이트와 직접 상호 작용할 수 있도록 Playwright MCP 서버를 추가합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- Model Context Protocol (MCP)의 개념과 GitHub Copilot app에서 사용하는 방식을 이해합니다. +- 앱 설정에서 Playwright MCP 서버를 추가합니다. +- 에이전트에게 브라우저를 조작하여 필터링 기능을 살펴보도록 요청합니다. + +## 시나리오 + +단위 테스트와 엔드투엔드 테스트도 중요하지만 UI 업데이트를 검증하려면 실제로 UI와 상호 작용해야 합니다. Copilot이 사용자처럼 작업 중인 웹사이트를 사용하도록 하여 변경 작업을 더 자동화하고, 업데이트가 예상대로 작동한다는 확신을 높이려고 합니다. + +## Model Context Protocol (MCP)이란? + +[Model Context Protocol (MCP)][mcp-blog-post]은 AI 에이전트가 외부 도구 및 서비스와 통신하는 방법을 제공합니다. MCP를 사용하면 AI 에이전트가 외부 도구 및 서비스와 실시간으로 통신할 수 있습니다. 따라서 리소스를 사용하여 최신 정보에 접근하고 도구를 사용하여 사용자를 대신해 작업을 수행할 수 있습니다. + +이러한 도구와 리소스에는 AI 에이전트와 외부 도구 및 서비스를 연결하는 MCP 서버를 통해 접근합니다. MCP 서버는 AI 에이전트와 외부 도구(예: 기존 API 또는 NPM 패키지 같은 로컬 도구) 간의 통신을 관리합니다. 각 MCP 서버는 AI 에이전트가 접근할 수 있는 서로 다른 도구 및 리소스 집합을 나타냅니다. + +널리 사용되는 기존 MCP 서버의 예는 다음과 같습니다. + +- [**GitHub MCP Server**](https://github.com/github/github-mcp-server): GitHub 리포지토리 관리를 위한 API 집합에 접근할 수 있게 합니다. AI 에이전트가 새 리포지토리 만들기, 기존 리포지토리 업데이트, 이슈 및 끌어오기 요청 관리 같은 작업을 수행할 수 있습니다. +- [**Playwright MCP Server**][playwright-mcp-server]: Playwright를 사용하는 브라우저 자동화 기능을 제공합니다. AI 에이전트가 웹페이지 이동, 양식 작성, 버튼 선택 같은 작업을 수행할 수 있습니다. + +다양한 도구와 리소스에 접근할 수 있는 다른 MCP 서버도 많습니다. GitHub는 MCP 서버를 쉽게 찾고 생태계에 기여할 수 있도록 [MCP registry](https://github.com/mcp)를 호스팅합니다. + +> [!CAUTION] +> MCP 서버를 프로젝트의 다른 종속성과 동일하게 취급합니다. MCP 서버를 사용하기 전에 소스 코드를 주의 깊게 검토하고, 게시자를 확인하고, 보안 영향을 고려합니다. 신뢰하는 MCP 서버만 사용하고 중요한 리소스나 작업에 대한 접근 권한을 부여할 때 주의합니다. + +## Playwright MCP 서버 추가 + +앱 설정에서 MCP 서버를 추가하고 관리합니다. 앱에는 인기 서버 카탈로그가 포함되어 있으므로 몇 번의 선택만으로 [Playwright MCP 서버][playwright-mcp-server]를 추가할 수 있습니다. + +1. Ctrl+,를 선택하여 Copilot app 설정 페이지를 엽니다. +2. **MCP servers**를 선택합니다. +3. 검색 대화 상자에 `Playwright`를 입력합니다. +4. **Popular MCP servers** 목록에서 **Playwright**를 선택합니다. +5. **Add server**를 선택하여 사용 가능한 MCP 서버 목록에 추가합니다. +6. Esc를 선택하여 설정 대화 상자를 닫습니다. + +이제 Playwright MCP 서버를 추가했습니다. + +## Copilot에 Playwright로 기능 탐색 요청 + +Copilot에 Playwright MCP 서버를 사용하여 기능을 수동으로 테스트하도록 요청합니다. + +1. 다음 프롬프트를 사용하여 새 기능을 검증하도록 Copilot에 요청합니다. + + ```plaintext + Start the dev server then use the Playwright MCP server to validate the functionality you just added exists. Use the details in the issue to ensure the newly added behavior matches the specs. + ``` + +Copilot은 Playwright MCP 서버를 통해 브라우저를 시작하고 각 단계를 수행한 다음 발견한 내용을 보고합니다. 작업을 수행하기 위해 시스템에서 브라우저가 실제로 열리는 것을 볼 수 있습니다. + +2. 이슈의 승인 조건과 비교하여 요약을 읽습니다. 올바르지 않은 부분이 있으면 후속 질문을 하거나 끌어오기 요청을 열기 전에 코드를 수정하도록 요청합니다. +3. 다음 레슨에서 이 세션을 마무리하므로 세션을 열어 둡니다. + +이제 Copilot은 사용자처럼 기능을 살펴보며 브라우저에서도 기능을 검증했습니다. + +## 요약 및 다음 단계 + +GitHub Copilot app에서 Playwright MCP 서버를 사용하여 실제 브라우저로 기능을 살펴봤습니다. 요약하면 다음 작업을 수행했습니다. + +- Model Context Protocol (MCP)의 개념과 앱에서 MCP 도구를 제공하는 방식을 배웠습니다. +- 앱 설정에서 Playwright MCP 서버를 추가했습니다. +- 에이전트에게 브라우저를 조작하여 필터링 기능을 살펴보도록 요청했습니다. + +기능을 구축하고 검증하고 작동하는 모습까지 확인했습니다. 이제 **Agent Merge**를 사용하여 끌어오기 요청을 열고 병합하도록 합니다. [레슨 6 - Agent Merge로 병합][next-lesson]을 계속 진행합니다. + +## 리소스 + +- [MCP란 무엇이며 왜 모두가 이야기할까요?][mcp-blog-post] +- [Microsoft Playwright MCP Server][playwright-mcp-server] +- [GitHub Copilot app에서 MCP 서버 구성][customize-app] + +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/6-agent-merge/ +[mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/ +[playwright-mcp-server]: https://github.com/microsoft/playwright-mcp +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/6-agent-merge.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/6-agent-merge.md new file mode 100644 index 00000000..7491a3d6 --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "Lesson 6 - Agent Merge로 병합" +description: "필터링 끌어오기 요청을 열고 My work에서 검토한 다음, Agent Merge가 차단 요소를 수정하고 병합하도록 하여 병합 자동화의 최상위 단계를 경험합니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +필터링 기능을 구축하고 검증하고 브라우저에서 작동하는 모습까지 확인했습니다. 마지막 단계는 병합입니다. 이 실습 과정에서 이미 두 번 병합했으며, 두 번 모두 끌어오기 요청을 열고 github.com에서 직접 병합했습니다. 이번에는 앱 안에서 끌어오기 요청의 전체 수명 주기를 관리하는 **Agent Merge**를 사용하여 앱이 번거로운 작업을 처리하게 합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- Agent Merge의 개념과 병합 수명 주기를 자동화하는 방식을 알아봅니다. +- 필터링 세션에서 Agent Merge를 활성화합니다. +- Agent Merge가 끌어오기 요청을 만들고 CI를 실행한 다음 모든 검사가 통과하면 병합하는 과정을 확인합니다. + +## 시나리오 + +지난 몇 개 모듈에서 코드 생성부터 Copilot이 UI를 직접 검증하도록 하는 것까지 다양한 자동화 수준을 살펴봤습니다. Tailspin Toys는 개발 속도를 더욱 높이기 위해 검토와 검증을 마친 끌어오기 요청을 자동으로 병합할 방법이 있는지 알아보려고 합니다. + +## Agent Merge 소개 + +**Agent Merge**는 Copilot app을 통해 끌어오기 요청을 병합하는 마지막 단계를 자동화합니다. 활성화하면 앱의 세션이 끌어오기 요청을 읽고, 실패한 CI 검사 수정, 검토 의견 대응, 필요할 때 리베이스 수행 등 병합을 차단하는 문제를 해결한 다음 GitHub에서 허용하는 즉시 병합합니다. 백그라운드에서 실행되고 앱을 다시 시작해도 계속 작동하며 끌어오기 요청이 병합되면 자동으로 꺼집니다. + +지금까지는 github.com에서 직접 **Merge pull request**를 선택했습니다. Agent Merge는 해당 책임을 에이전트로 옮기므로, 에이전트가 PR 완료 과정을 관리하는 동안 다음 작업으로 넘어갈 수 있습니다. 작업을 검토하고 승인하는 책임은 여전히 사용자에게 있으며, 에이전트는 기계적인 마무리 작업만 처리합니다. + +## Agent Merge로 PR 관리 + +코드를 직접 검토하고 테스트를 실행했으며 Copilot이 UI를 검증하도록 했습니다. 이제 새 코드를 코드베이스에 병합합니다. Agent Merge가 지속적 통합(CI)과 병합 과정을 관리하게 합니다. + +1. 이전 모듈에서 필터링 기능을 추가하며 열어 둔 세션으로 돌아갑니다. +2. 오른쪽 위에서 **Create PR** 옆의 드롭다운을 선택합니다. +3. **Agent merge**를 선택하여 Agent Merge를 활성화합니다. + + ![Agent merge 옵션을 화살표로 가리키는 펼쳐진 GitHub Copilot app Create PR 드롭다운](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. 이제 버튼 텍스트가 **Agent merge**로 바뀝니다. +5. **Agent merge** 버튼을 선택하여 Agent Merge 프로세스를 시작합니다. + +Copilot app이 PR을 만들고 관리하는 프로세스를 시작합니다. 먼저 프로젝트를 탐색하여 PR을 만드는 최적의 방법을 결정한 다음 새 PR을 만듭니다. + +잠시 후 Copilot이 다시 작업을 시작하여 PR 조건, 즉 리포지토리의 모든 테스트를 실행하는 CI 프로세스를 확인합니다. 다른 팀 구성원이 남긴 검토, 실행해야 하는 검사(CI 프로세스), PR의 병합 가능 여부를 보고합니다. + +6. **Agent merge** 옆의 드롭다운을 선택한 다음 **Merge pull request**를 선택하여 Agent Merge가 끌어오기 요청을 병합하도록 허용합니다. + + ![에이전트에 허용된 작업인 Address reviews, Fix CI failures, Resolve conflicts와 화살표로 강조된 Merge pull request를 보여 주는 Agent merge 드롭다운](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. 모든 CI 프로세스가 통과하면, 즉 테스트가 성공하면 Copilot이 끌어오기 요청을 병합합니다. + +## 요약 및 다음 단계 + +코드 생성, 코드 테스트와 검증, 끌어오기 요청 프로세스를 포함한 개발 프로세스의 여러 부분을 자동화했습니다. 다음 작업을 수행했습니다. + +- Agent Merge의 개념과 병합 수명 주기를 자동화하는 방식을 배웠습니다. +- 필터링 세션에서 Agent Merge를 활성화했습니다. +- Agent Merge가 끌어오기 요청을 만들고 CI를 실행한 다음 모든 검사가 통과했을 때 병합하는 과정을 확인했습니다. + +다음으로 에이전트와 함께 작업을 계획하고 시각화하는 더 풍부한 방법인 **캔버스**를 살펴봅니다. [레슨 7 - 캔버스로 계획 수립][next-lesson]을 계속 진행합니다. + +## 리소스 + +- [GitHub Copilot app으로 이슈 및 끌어오기 요청 관리][managing-issues-prs] +- [GitHub Copilot app 정보][about-copilot-app] + +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/7-canvases/ +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/7-canvases.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/7-canvases.md new file mode 100644 index 00000000..c954ce73 --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "Lesson 7 - 캔버스로 계획 수립" +description: "GitHub Copilot app에서 공유 에이전트 기반 캔버스를 만들어 에이전트와 함께 작업을 계획하고 추적합니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +지금까지 채팅을 통해 에이전트를 지시했습니다. 하지만 많은 작업은 대화가 아니라 보드, 문서, 검사 목록에서 이루어집니다. **캔버스**는 바로 이러한 작업을 위해 앱 안에서 사용자와 에이전트가 함께 사용하는 화면을 제공합니다. 이 레슨에서는 지금까지 처리한 백로그를 계획하고 추적하는 간단한 캔버스를 만듭니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- 캔버스의 개념과 사용 시점을 이해합니다. +- 백로그를 분류하는 공유 Kanban 보드 캔버스를 만듭니다. +- 캔버스를 리포지토리에 저장하고 팀에서 사용할 수 있도록 병합합니다. +- 새 세션에서 캔버스를 열고 캔버스에서 작업을 시작합니다. + +## 시나리오 + +이슈 목록은 아무리 좋은 상황에서도 부담스러울 수 있습니다. Tailspin Toys 개발자는 이슈를 빠르게 분류하고 Copilot app에서 작업을 시작할 수 있는 도구를 찾고 있습니다. + +## 캔버스란? + +[캔버스][canvas-docs]는 계획, 분류 보드, 릴리스 검사 목록, 대시보드, 문서 같은 작업 산출물을 위한 공유 대화형 화면입니다. 채팅은 의도를 설명하고 모호한 부분을 함께 추론하는 데 유용하지만 대부분의 작업은 *화면*에서 이루어집니다. 캔버스를 사용하면 해당 화면에서 에이전트와 직접 협업할 수 있습니다. + +캔버스는 **양방향**입니다. 에이전트가 작업하면서 캔버스를 업데이트할 수 있고 사용자도 동일한 화면을 편집할 수 있습니다. 캔버스를 만들면 에이전트가 프롬프트와 워크플로를 바탕으로 구축하며, 진행하면서 기능을 추가하거나 제거하거나 수정하도록 요청할 수 있습니다. 캔버스를 만들면 앱의 오른쪽 패널에서 열립니다. + +일반적인 예는 다음과 같습니다. + +- 하루를 계획하고 이슈와 끌어오기 요청의 우선순위를 정하는 **Markdown 캔버스** +- 사용자와 에이전트가 카드를 추가하고 열 사이에서 작업을 이동하는 **에이전트 Kanban 보드** +- 리포지토리의 주요 이슈와 반복되는 주제를 요약하는 **이슈 분류 보드** + +## 캔버스를 사용하는 이유 + +작업에 구조화, 반복, 검증이 필요하고 채팅만으로 충분하지 않다면 캔버스를 사용합니다. 캔버스로 다음 작업을 수행할 수 있습니다. + +- 워크플로에 맞는 실제 산출물을 기반으로 에이전트가 작업하게 합니다. +- 공유 화면에서 작업을 직접 안내하거나 수정한 다음 에이전트가 변경 내용에서 계속 작업하게 합니다. +- 채팅 응답만 보는 대신 산출물의 눈에 보이는 변경으로 진행 상황을 확인합니다. + +## 작업 추적 캔버스 만들기 + +별점, 문서화 표준, 필터링 기능을 모두 병합하여 많은 작업을 제공했습니다. 하지만 백로그에는 아직 항목이 남아 있습니다. 작업을 빠르게 분류하는 데 도움이 되는 캔버스를 만듭니다. + +1. GitHub Copilot app으로 돌아가거나 앱을 엽니다. +2. **Home screen**을 선택합니다. +3. 리포지토리로 `tailspin-toys`가 선택되어 있는지 확인합니다. +4. 프롬프트 상자에서 다음 프롬프트를 사용하여 요구 사항을 충족하는 캔버스를 만듭니다. + + ```plaintext + Create a basic Kanban board canvas that allows me to quickly triage work. Highlight the three issues which are most likely to need attention right now, with the remainder in a second section down below. The top three cards should include a description of the issue's content and a justification of why they're at the top of the list. Each issue should have a button that allows me to add it to the current context for the current session so I can get to work on it straightaway. + ``` + +Copilot이 캔버스를 만들기 시작합니다. + +> [!NOTE] +> 이 작업에는 몇 분 정도 걸립니다. 복잡한 작업이므로 첫 번째 버전이 만족스럽지 않을 수 있습니다. 원하는 도구가 완성될 때까지 프롬프트로 계속 개선할 수 있습니다. + +## 캔버스를 저장하고 리포지토리에 병합 + +캔버스는 지침 파일 및 스킬과 마찬가지로 리포지토리의 자산이 될 수 있습니다. Copilot에 캔버스를 리포지토리에 추가하고 병합하도록 요청하여 팀 전체에서 사용하게 합니다. + +1. 같은 세션에서 다음 프롬프트를 사용하여 캔버스를 리포지토리에 저장하도록 Copilot에 요청합니다. + + ```plaintext + Let's save this canvas definition to the repository so I can share it with my development team + ``` + +2. Copilot이 캔버스 파일을 저장하면 오른쪽 위에서 **Create PR** 옆의 드롭다운을 선택합니다. +3. **Agent merge**를 선택하여 Agent Merge를 활성화합니다. + + ![Agent merge 옵션을 화살표로 가리키는 펼쳐진 GitHub Copilot app Create PR 드롭다운](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. 이제 버튼 텍스트가 **Agent merge**로 바뀝니다. +5. **Agent merge** 버튼을 선택하여 Agent Merge 프로세스를 시작합니다. + +Copilot app이 PR을 만들고 관리하는 프로세스를 시작합니다. 먼저 프로젝트를 탐색하여 PR을 만드는 최적의 방법을 결정한 다음 PR을 만듭니다. + +잠시 후 Copilot이 다시 작업을 시작하여 PR 조건, 즉 리포지토리의 모든 테스트를 실행하는 CI 프로세스를 확인합니다. 다른 팀 구성원이 남긴 검토, 실행해야 하는 검사(CI 프로세스), PR의 병합 가능 여부를 보고합니다. + +6. **Agent merge** 옆의 드롭다운을 선택한 다음 **Merge pull request**를 선택하여 Agent Merge가 끌어오기 요청을 병합하도록 허용합니다. + + ![에이전트에 허용된 작업인 Address reviews, Fix CI failures, Resolve conflicts와 화살표로 강조된 Merge pull request를 보여 주는 Agent merge 드롭다운](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. 모든 CI 프로세스가 통과할 때까지 기다립니다. 모두 통과하면 Copilot이 끌어오기 요청을 자동으로 병합합니다. + +이제 팀을 위한 새 공유 캔버스를 만들었습니다. + +## 캔버스에서 작업 + +캔버스를 만들었으므로 새 세션을 시작하고 사용해 봅니다. + +1. Copilot app에서 **tailspin-toys** 옆의 **New session**을 선택하여 새 세션을 시작합니다. +2. 다음 프롬프트를 사용하여 분류 캔버스를 열도록 Copilot에 요청합니다. + + ```plaintext + Open the triage issues canvas + ``` + +3. 이제 새 세션에서 만든 캔버스가 열리는 것을 확인합니다. +4. 가장 관심 있는 이슈 중 하나에서 **Add to current context**를 선택합니다. +5. Copilot이 이슈 작업을 시작합니다. + +이제 직접 만든 캔버스를 사용하여 개발 프로세스를 간소화했습니다. + +## 요약 및 다음 단계 + +사용자와 에이전트가 협업하는 공유 화면을 만들었습니다. 다음 작업을 수행했습니다. + +- 캔버스의 개념과 사용 시점을 배웠습니다. +- 에이전트와 공유 Kanban 분류 보드 캔버스를 만들었습니다. +- Agent Merge를 사용하여 캔버스를 리포지토리에 저장하고 병합했습니다. +- 새 세션에서 캔버스를 열고 캔버스를 사용하여 작업을 시작했습니다. + +백로그를 추적하도록 설정했으므로 지금까지 구축한 항목과 다음 단계를 돌아봅니다. [레슨 8 - 검토 및 다음 단계][next-lesson]를 계속 진행합니다. + +## 리소스 + +- [GitHub Copilot app에서 캔버스 확장 사용][canvas-docs] +- [Awesome Copilot의 캔버스][awesome-copilot-canvases] +- [GitHub Copilot app 정보][about-copilot-app] + +[next-lesson]: /ko-kr/learning-hub/copilot-workshops/app/8-review/ +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/8-review.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/8-review.md new file mode 100644 index 00000000..14fb8d89 --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "Lesson 8 - 검토 및 다음 단계" +description: "GitHub Copilot app 실습 과정을 되짚어 보고, 반복 작업을 자동화하고, 다음에 살펴볼 내용을 알아봅니다." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +지난 여러 레슨에서 GitHub Copilot app으로 아이디어를 기능으로 만들고 병합하기까지 다음 작업을 수행했습니다. + +- 리포지토리를 연결하고 앱의 워크스페이스와 미리 생성된 백로그를 살펴봤습니다. +- 직접 작업과 이슈에서 세션을 시작하고 Plan 및 Autopilot 모드로 에이전트의 작업 방식을 제어했습니다. +- 사용자 지정 지침과 재사용 가능한 스킬로 에이전트를 안내했습니다. +- Playwright MCP 서버를 사용하여 실제 브라우저에서 작업을 테스트했습니다. +- 공유 캔버스에서 에이전트와 협업했습니다. +- github.com에서 직접 병합하는 단계부터 **Agent Merge**가 끌어오기 요청을 병합하는 단계까지 병합 자동화 수준을 높여 변경 내용을 제공했습니다. + +이제 반복 작업을 자동화하고 모범 사례를 살펴본 다음 앞으로 진행할 방향을 알아봅니다. + +## 반복 작업 자동화 + +앱은 **자동화**를 통해 일정에 따라 또는 요청 시 에이전트를 실행할 수 있습니다. 새 이슈 분류나 최근 활동 요약 같은 일상적인 작업에 유용합니다. 간단하고 비파괴적인 자동화를 하나 만듭니다. + +1. 사이드바에서 **Automations**를 선택한 다음 **New automation**을 선택합니다. +2. `Recap my recent work` 같은 이름을 지정합니다. +3. 트리거를 선택합니다. **Manual**은 요청 시 실행하고, **On a schedule**은 자동으로 실행하며, **When an issue is created**는 새 이슈에 반응합니다. 이 레슨에서는 **Manual**을 선택합니다. +4. 자동화가 내용을 변경할 수 없도록 다음과 같은 읽기 전용 프롬프트를 입력합니다. + + ```plaintext + Summarize the pull requests merged in this repository over the last week, and list any issues still open in the backlog. + ``` + +5. 프로젝트(Tailspin Toys 리포지토리)를 선택하고 자동화를 만듭니다. +6. 요청 시 실행하여 결과를 확인합니다. + +> [!TIP] +> 자동화는 로컬 또는 클라우드에서 실행할 수 있습니다. 일정에 따라 사용자 없이 실행하려면 **Run in the cloud**를 활성화하고 자동화에서 사용할 수 있는 **Tools**를 선택합니다. 출력 결과를 신뢰할 수 있을 때까지 예약 자동화의 범위를 제한하고 비파괴적으로 유지합니다. + +## 모범 사례 + +AI 도구를 사용할 때는 도구를 둘러싼 인프라가 결과의 품질을 좌우합니다. 이 워크숍에서는 지침 파일, 스킬, 사용자 지정 에이전트를 모두 사용했습니다. 이러한 항목에 투자하고 세션 간에 재사용합니다. + +작업에 맞는 **모드와 모델**을 선택합니다. 구축 전에 접근 방식을 검토하려면 **Plan**을 사용하고, 범위가 명확한 변경에서 계속 참여하려면 **Interactive**를 사용하며, 범위가 명확하고 격리된 작업에만 **Autopilot**을 사용합니다. 일상적인 편집에는 빠른 모델을 선택하고 복잡한 작업에는 추론 능력이 더 높은 모델을 선택합니다. + +컨텍스트는 인프라만큼 중요합니다. 만들려는 *항목*, 그 *이유*, 원하는 *방식*을 명확하게 설명하면 출력이 크게 달라집니다. 빠른 채팅은 아이디어를 전체 세션에 적용하기 전에 범위를 정하기에 적합합니다. + +## 더 살펴볼 내용 + +핵심 워크플로를 모두 살펴봤습니다. 다음 기능도 확인해 볼 만합니다. + +- 전체 세션이 필요 없는 빠른 일회성 질문을 위한 **Quick chats** +- 구축 전에 문제를 함께 검토하고 유용한 피드백을 받기 위한 **Rubber duck** +- 반복 가능한 전문 작업을 위해 역할, 도구, 지침을 패키지하는 [**Custom agents**][custom-agents] +- 세션에서 일어난 일을 서술형으로 생성하는 [`/chronicle`][chronicle] +- Ollama, Foundry Local, LM Studio를 통한 로컬 모델을 포함하여 자체 공급자의 모델을 사용하는 [Bring your own key (BYOK)][byok] +- GitHub에서 호스팅하는 격리된 환경에서 세션을 실행하는 [Cloud sandboxes][sandboxes] +- 리포지토리, 세션, 프롬프트에서 바로 앱을 여는 [Deep links][deep-links] + +## 다음 단계 + +어떤 도구든 더 능숙하게 사용하려면 계속 사용해야 합니다. 프로덕션 코드, 취미 프로젝트, 오랫동안 생각만 하고 만들지 못했던 작은 앱에 사용해 봅니다. 배운 내용을 팀과 공유하고 팀의 경험에서도 배웁니다. 언제나 그렇듯 문서를 살펴봅니다. + +GitHub Copilot 생태계를 더 살펴보려면 [VS Code 실습 과정](/ko-kr/learning-hub/copilot-workshops/vscode/), [Copilot CLI 실습 과정](/ko-kr/learning-hub/copilot-workshops/cli/), [Cloud agent 실습 과정](/ko-kr/learning-hub/copilot-workshops/cloud/)을 확인합니다. + +## 리소스 + +- [GitHub Copilot app 정보][about-copilot-app] +- [GitHub Copilot app 시작하기][getting-started] +- [GitHub Copilot app 사용자 지정][customize] +- [자동화 사용][using-automations] +- [캔버스 확장 사용][canvas-docs] +- [클라우드 및 로컬 샌드박스 정보][sandboxes] + +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[customize]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[using-automations]: https://docs.github.com/copilot/how-tos/github-copilot-app/using-automations +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/index.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/index.md new file mode 100644 index 00000000..82455ace --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/app/index.md @@ -0,0 +1,57 @@ +--- +title: "GitHub Copilot app" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[**GitHub Copilot app**](https://docs.github.com/copilot/concepts/agents/github-copilot-app)은 Copilot CLI를 기반으로 구축된 데스크톱 애플리케이션으로, 에이전트 기반 개발을 하나의 집중된 워크스페이스에서 수행할 수 있게 해 줍니다. 병렬 에이전트 세션, 전환 가능한 세션 모드, 공유 캔버스, GitHub 이슈 및 끌어오기 요청 기본 관리 기능을 제공합니다. 여기에는 끌어오기 요청의 리베이스, 검토 피드백, CI 수정, 병합 과정을 관리하는 **Agent Merge**도 포함됩니다. + +이 레슨에서는 앱을 설치하고 프로젝트를 설정한 다음, 앱 워크스페이스와 템플릿에서 미리 생성한 백로그를 살펴봅니다. 별점을 추가하는 작은 변경으로 시작한 뒤, 이슈를 바탕으로 사용자 지정 지침 표준을 추가하고, 격리된 에이전트 세션에서 필터링 기능을 구축하고, 재사용 가능한 스킬로 검증합니다. Playwright MCP 서버를 추가하여 실제 브라우저에서 기능을 살펴본 다음, **Agent Merge**가 끌어오기 요청을 병합하는 단계까지 병합 자동화 수준을 높입니다. 마지막으로 공유 캔버스에서 협업하고 반복 작업을 자동화하여 아이디어를 병합된 기능으로 완성하는 전체 과정을 경험합니다. + +## 레슨 + +| 레슨 | 주제 | 설명 | +|--------|-------|-------------| +| [0. 필수 조건][ex0] | 설정 | Node.js를 설치하고 Tailspin Toys 프로젝트의 복사본 만들기 | +| [1. Copilot app 설치][ex1] | 설정 | 앱을 설치하고 프로젝트를 연결한 다음 워크스페이스 살펴보기 | +| [2. 첫 번째 에이전트 세션 실행][ex2] | 첫 번째 변경 | 세션을 시작하고 작은 변경을 첫 번째 끌어오기 요청으로 제공하기 | +| [3. 사용자 지정 지침으로 Copilot 안내][ex3] | 컨텍스트 | 이슈를 바탕으로 문서화 표준을 추가하고 병합하기 | +| [4. Autopilot으로 기능 구축][ex4] | 핵심 기능 | Plan과 Autopilot으로 필터링 기능을 구축한 다음 스킬로 검증하기 | +| [5. Playwright MCP로 테스트][ex5] | 외부 도구 | Playwright MCP 서버를 추가하고 브라우저에서 기능 살펴보기 | +| [6. Agent Merge로 병합][ex6] | 병합 | Agent Merge가 필터링 끌어오기 요청을 수정하고 병합하도록 하기 | +| [7. 캔버스로 계획 수립][ex7] | 협업 | 작업을 계획하고 추적하는 공유 캔버스 만들기 | +| [8. 검토 및 다음 단계][ex8] | 요약 | 반복 작업을 자동화하고 다음에 살펴볼 내용 알아보기 | + +## 필수 조건 + +워크숍에 참여하기 전에 다음 항목을 준비했는지 확인합니다. + +- [ ] 활성 **Copilot Student, Pro, Pro+, Business, or Enterprise** 플랜이 있는 GitHub 계정 +- [ ] **macOS, Linux, or Windows**를 실행하는 컴퓨터 +- [ ] 컴퓨터에 [Git 설치][install-git] + +> [!TIP] +> 유료 플랜이 없습니까? 인증된 학생은 [GitHub Education][callout-student-plan-education]을 통해 GitHub Copilot을 무료로 사용할 수 있습니다. **Copilot Student** 플랜에는 이 워크숍에서 사용하는 에이전트, MCP, 코드 검토, Copilot CLI 기능이 포함되어 있으므로 모든 실습 과정을 완료할 수 있습니다. + +> [!NOTE] +> Copilot app은 codespace가 아니라 사용자의 컴퓨터에서 실행되므로, [레슨 0][ex0]에서는 앱을 설치하기 전에 Node.js를 설치하고 프로젝트 복사본을 만드는 방법을 안내합니다. + +> [!NOTE] +> Copilot Business 또는 Copilot Enterprise를 사용하는 경우 앱을 사용하려면 관리자가 **Copilot CLI** 정책을 활성화해야 합니다. + +## 시작하기 + +[**레슨 0: 필수 조건부터 시작 →**][ex0] + +[ex0]: /ko-kr/learning-hub/copilot-workshops/app/0-prerequisites/ +[ex1]: /ko-kr/learning-hub/copilot-workshops/app/1-install-copilot-app/ +[ex2]: /ko-kr/learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /ko-kr/learning-hub/copilot-workshops/app/3-custom-instructions/ +[ex4]: /ko-kr/learning-hub/copilot-workshops/app/4-build-filtering/ +[ex5]: /ko-kr/learning-hub/copilot-workshops/app/5-mcp-playwright/ +[ex6]: /ko-kr/learning-hub/copilot-workshops/app/6-agent-merge/ +[ex7]: /ko-kr/learning-hub/copilot-workshops/app/7-canvases/ +[ex8]: /ko-kr/learning-hub/copilot-workshops/app/8-review/ +[install-git]: https://github.com/git-guides/install-git +[callout-student-plan-education]: https://github.com/education/students \ No newline at end of file diff --git a/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/index.md b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/index.md new file mode 100644 index 00000000..c7ca6dcf --- /dev/null +++ b/website/src/content/docs/ko-kr/learning-hub/copilot-workshops/index.md @@ -0,0 +1,41 @@ +--- +title: "GitHub Copilot 에이전트 실습" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +최근 GitHub Copilot에 추가된 기능은 소프트웨어 개발 수명 주기(SDLC) 전반에서 개발자에게 강력한 도구를 제공합니다. 여기에는 GitHub의 이슈 및 끌어오기 요청 작업, 외부 서비스와의 상호 작용, 그리고 코드 작성이 포함됩니다. 이 랩에서는 이러한 기능을 살펴보고, 실제 사용 사례와 도구를 최대한 활용하는 방법을 소개합니다. + +> [!CAUTION] +> GitHub Copilot은 결정론적이 아니라 확률론적으로 작동하므로 정확한 코드와 변경되는 파일 등이 달라질 수 있습니다. 따라서 랩의 스크린샷 및 코드 조각과 실제 환경에서 약간의 차이가 나타날 수 있습니다. 이는 예상된 결과이며, 이러한 유형의 도구가 작동하는 방식에서 비롯됩니다. +> +> 무언가 제대로 작동하지 않거나 올바르게 실행되지 않는다면 멘토에게 문의하십시오! + +## 하네스(Harness) 선택 + +GitHub Copilot은 어떤 작업 환경에서든 함께할 수 있습니다. 원하는 개발 방식에 맞는 하네스를 선택하고, Tailspin Toys의 공통 백로그를 바탕으로 연습을 진행합니다. 각 하네스는 자체 설정 과정으로 시작하므로 원하는 하네스를 선택해 바로 시작할 수 있습니다. + +### 🖥️ [VS Code](/ko-kr/learning-hub/copilot-workshops/vscode/) + +**Visual Studio Code**와 GitHub Codespaces에서 GitHub Copilot을 사용합니다. 익숙한 편집기를 벗어나지 않고 Copilot Chat 에이전트 모드, MCP 서버, 사용자 지정 에이전트를 활용합니다. AI 지원을 IDE에 직접 통합하고 싶을 때 적합합니다. + +### 💻 [Copilot CLI](/ko-kr/learning-hub/copilot-workshops/cli/) + +**GitHub Copilot CLI**는 터미널에서 실행되는 에이전트형 도우미입니다. 이를 설치하고, MCP 서버를 연결하고, 계획 모드로 코드를 생성하고, 명령줄에서 직접 스킬, 사용자 지정 에이전트, 슬래시 명령을 만듭니다. + +### 🤖 [Copilot 앱](/ko-kr/learning-hub/copilot-workshops/app/) + +**GitHub Copilot 앱**은 Copilot CLI를 기반으로 구축된 데스크톱 애플리케이션입니다. 여러 에이전트 세션을 병렬로 실행하고, 세션 모드를 전환하고, 캔버스에서 협업하고, GitHub 이슈와 끌어오기 요청을 기본 기능으로 관리합니다. 여기에는 끌어오기 요청의 리베이스, 검토 피드백, CI 수정, 병합 과정을 관리하는 **Agent Merge**도 포함됩니다. + +### ☁️ [Copilot 클라우드 에이전트](/ko-kr/learning-hub/copilot-workshops/cloud/) + +**Copilot 클라우드 에이전트**는 백그라운드에서 GitHub 이슈를 처리하는 비동기 동료 프로그래머입니다. 작업을 할당하고, 사용자 지정 에이전트로 작업 방향을 안내하고, 에이전트 대시보드에서 진행 상황을 모니터링하고, 에이전트가 생성한 끌어오기 요청을 검토합니다. + +## 시나리오 + +여러분은 개발자 테마의 보드게임 크라우드펀딩을 제공하는 가상 기업 Tailspin Toys에 새로 합류한 개발자입니다. 아주 큰 시장입니다! 팀의 백로그는 이미 GitHub 이슈로 등록되어 있어 바로 작업을 시작할 수 있습니다. 필터링 및 페이지 매김과 같은 기능 작업과 접근성 및 코딩 표준과 같은 품질 개선 작업이 함께 준비되어 있습니다. 사이트와 Copilot의 기능을 모두 살펴보면서 반복적으로 작업을 진행해 과제를 완료합니다. + +## 시작하기 + +위에서 하네스를 선택해 시작합니다. 각 하네스는 개발을 시작하는 데 필요한 설정 과정으로 시작합니다. \ No newline at end of file diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/0-prerequisites.md b/website/src/content/docs/learning-hub/copilot-workshops/app/0-prerequisites.md new file mode 100644 index 00000000..00c6ca22 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "Lesson 0 - Prerequisites" +description: "Set up for the GitHub Copilot app lessons: install Node.js for the Tailspin Toys project and create your own copy of the repository from the template." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +The GitHub Copilot app is a desktop app, serving as your central hub for both Copilot and GitHub. It provides quick access to issues and pull requests, and of course allows you to build using GitHub Copilot. During this workshop you'll be working locally, using both the Tailspin Toys app, built on Astro, and of course the GitHub Copilot app. Before you get started, let's ensure Node.js is installed locally, then install the Copilot app. + +In this lesson, you will: + +- install Node.js so the project's tests can run on your machine. +- create your own copy of the Tailspin Toys project from the template. + +## Install Node.js + +Several lessons ask an agent to build features and run the Tailspin Toys test suite locally, which needs **[Node.js][nodejs]** — the only runtime the project requires. Install version **22 or newer**; the current **LTS** release is a safe choice. + +The simplest option on every platform is the official installer: + +1. In your operating system, open a terminal window using Windows Terminal, macOS terminal, or whatever you typically use. +2. Run the following command to confirm you have at least Node.js 22 or higher installed: + + ```shell + node --version + ``` + +3. If you see `v22` or a higher number, you can skip to the next section! + +> [!TIP] +> You only need to complete these steps if you don't have Node installed, or you need to update. + +4. Open the [Node.js download page][node-download]. +5. Download the **LTS** build for your operating system. +6. Run the installer and accept the defaults. On Windows, keep the **Add to PATH** option selected. +7. Once installed, open a new terminal window. +8. Confirm the install in the new terminal window by running the following: + + ```bash + node --version + ``` + +9. You should see `v22.x.x` or higher. + +> [!TIP] +> Prefer containers? If you have **[Docker][docker]**, you can use the repository's [dev container][dev-containers] instead of installing Node.js locally — it bundles Node for you. You don't need both. + +## Set up the lab repository + +You'll work against your own copy of the Tailspin Toys project. Create it now from the [template repository][template-repository]. The new repository contains every file the lab needs, and you'll connect it to the app in the next lesson. + +1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/tailspin-toys`. +2. Create your own copy of the repository by selecting the **Use this template** button on the lab repository page. Then select **Create a new repository**. + + ![The Use this template button with Create a new repository selected from the dropdown](/images/learning-hub/copilot-workshops/app-0-use-template.png) + +3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to GitHub Copilot. + + ![The Create a new repository form with github-samples/tailspin-toys set as the template and the repository name filled in](/images/learning-hub/copilot-workshops/app-0-create-repository.png) + +4. Make a note of the repository path you created (**organization-or-user-name/repository-name**), as you will be referring to this later in the lab. + +> [!NOTE] +> When you create your repository from the template, a backlog of GitHub issues is created for you automatically. You'll work from these issues throughout the workshop — there's nothing to file yourself. + +## Summary and next steps + +You're set up! You installed Node.js so the project can build and test on your machine, and you created your own copy of the Tailspin Toys repository from the template. + +Next, you'll install the GitHub Copilot app, connect the repository you just created, and get oriented in the workspace. Continue to [Lesson 1 - Installing the GitHub Copilot app][next-lesson]. + +## Resources + +- [Download Node.js][node-download] +- [Creating a repository from a template][template-repository] +- [About the GitHub Copilot app][about-copilot-app] + +[next-lesson]: /learning-hub/copilot-workshops/app/1-install-copilot-app/ +[nodejs]: https://nodejs.org/ +[node-download]: https://nodejs.org/en/download +[docker]: https://www.docker.com/products/docker-desktop/ +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/1-install-copilot-app.md b/website/src/content/docs/learning-hub/copilot-workshops/app/1-install-copilot-app.md new file mode 100644 index 00000000..71608681 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "Lesson 1 - Installing the GitHub Copilot app" +description: "Install the GitHub Copilot app, connect the repository you created from the template, get oriented in the workspace, and try a quick chat." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +The **[GitHub Copilot app][about-copilot-app]** is a desktop application for agent-driven development. It is built on GitHub Copilot CLI and integrates natively with GitHub, so your repositories, branches, and CI pipelines work out of the box. It's designed for workflows where you direct several agents in parallel — each in its own isolated workspace — rather than doing all of the work yourself, and automating repetitive tasks. With Node.js installed and your copy of the project ready, the next step is to install the app and connect that repository. + +In this lesson, you will: + +- install the GitHub Copilot app and sign in. +- add your project to the app from its GitHub repository. +- get oriented in the workspace, including the backlog the template seeded for you. +- try a quick chat to learn about the app itself. + +## Scenario + +Your team is adopting AI agents to work through a growing backlog. The Copilot app gives you one place to direct that work — picking up issues, running agents, reviewing changes, and merging pull requests. This lesson gets you installed, connected, and comfortable starting a conversation about your project. + +> [!NOTE] +> An eligible Copilot plan is required — Copilot Student or any paid plan (Pro, Pro+, Business, or Enterprise). If you are on Copilot Business or Copilot Enterprise, your administrator must enable the **Copilot CLI** policy before the app will work. + +## Install and configure the GitHub Copilot app + +To use the GitHub Copilot app the first step, as you might imagine, is to install it. Versions are available for Windows, macOS and Linux. Let's install the app, authenticate, and add our Tailspin Toys repo to the app. + +1. In a browser, open the [landing page for the GitHub Copilot app][download-app]. +2. Download the app for your platform and install it following the instructions provided on the landing page. +3. Open the app once it's installed. +4. Select **Sign in to GitHub** and follow the prompts to authenticate. If you use GitHub Enterprise Server, choose **Use GitHub Enterprise** and enter your server address when prompted. +5. After authenticating, you'll be asked about connecting your repositories. Select the Tailspin Toys repo you just created, which should be named `/tailspin-toys`. +6. Select **Continue** to continue the onboarding. +7. When prompted for a theme, select the one which brings you the most joy, then select **Finish**. + +> [!NOTE] +> If your copy of Tailspin Toys didn't appear in the list automatically, you can add it after completing the onboarding process in the app. When completed, the Copilot app will bring you to the home screen. From there you can select **Choose from GitHub**, and search for your repo by name (\/tailspin-toys), then select it. Your repo will now be added to the Copilot app! + +## Get oriented in the workspace + +With your project connected, take a moment to learn your way around. The app organizes everything into a few areas in the sidebar: + +- **Sessions** — where agents do their work. Each session runs in its own isolated workspace, so you can run several at once without their changes colliding. You'll start your first session in the next lesson. +- **Quick chats** — lightweight conversations for questions and brainstorming that don't need a branch or workspace of their own. You'll try one at the end of this lesson. +- **My work** — your issues and pull requests, surfaced through the app's **native GitHub integration**. From here you can browse and filter issues and pull requests, check CI status, start a session from an issue, and review pull requests — all without leaving the app. +- **Automations** — saved agent tasks that run on a schedule or on demand. You'll create one near the end of the harness. + +### Find your seeded backlog + +Because the app integrates with GitHub natively, the work waiting in your repository shows up right inside the app. When you created your repository from the template, a backlog of issues was filed for you — let's confirm it's there. + +1. Select **My work** in the sidebar. +2. The template seeded eight issues in your backlog. This harness focuses on the following three — confirm you can see them: + + - Allow users to filter games by category and publisher + - Update our repository coding standards + - Implement pagination on the game list page + +3. Select an issue to read its details. Each issue is also a launch point for an agent session — you'll start work from these issues later in the harness. + +> [!NOTE] +> The list of items in My work is automatically filtered to only display items from the repositories you've added to Copilot app. Want to see work items from other repos? Add them to the app! + +## Try a quick chat + +A great way to get comfortable with the app is to use it to learn about the *app itself* — and a **quick chat** is exactly the right tool for that. Quick chats let you ask a question or brainstorm without creating a branch or worktree, so they're perfect for a fast, throwaway question — no session required. + +1. In the sidebar, select **+** next to **Quick chats** to open a new chat. +2. Ask the app how its own sessions work: + + ```plaintext + How does the GitHub Copilot app use worktrees? + ``` + +3. Read the response in the conversation view. You'll see that each session runs in its own isolated git worktree — the detail that lets you run several agents in parallel without their changes colliding. You can continue the conversation or start a new chat at any time. + +## Summary and next steps + +Congratulations! You've installed the GitHub Copilot app, connected your project, and explored your workspace. You learned how to: + +- install the app and sign in to GitHub. +- add a project from its GitHub repository. +- get oriented in the workspace and find your seeded backlog in **My work**. +- use a quick chat to ask a fast, throwaway question. + +Next, you'll start your first agent session and make your first change to the project — showing a star rating on the game cards. Continue to [Lesson 2 - Running your first agent session][next-lesson]. + +## Resources + +- [About the GitHub Copilot app][about-copilot-app] +- [Getting started with the GitHub Copilot app][getting-started] +- [Working with agent sessions in the GitHub Copilot app][agent-sessions] + +[ex0]: /learning-hub/copilot-workshops/app/0-prerequisites/ +[next-lesson]: /learning-hub/copilot-workshops/app/2-add-star-rating/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[download-app]: https://gh.io/app diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/2-add-star-rating.md b/website/src/content/docs/learning-hub/copilot-workshops/app/2-add-star-rating.md new file mode 100644 index 00000000..ef2577b1 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "Lesson 2 - Running your first agent session" +description: "Start your first agent session in the GitHub Copilot app, make a small change to the game cards, and merge it as your first pull request." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +In the previous lesson you toured the workspace and used a quick chat. Now it's time to start an **agent session** and make your first change to the project. You'll keep it small: the games already have a star rating in their data, but the game cards on the home page don't show it yet. You'll ask the agent to surface it, review the change, and merge it as your first pull request. + +In this lesson, you will: + +- start an agent session and learn how a session is structured. +- ask the agent to make a small, focused change to the project. +- review the change in the workspace diff view. +- run the app locally to confirm the change in the browser. +- open and merge your first pull request. + +## Scenario + +Each game in Tailspin Toys can have a star rating, and it already appears on the game details page. The game cards on the home page, though, only show the title, category, publisher, and description. As a warm-up, you'll have the agent display the existing rating on each card — a tiny, self-contained change that's perfect for your first session. + +## Anatomy of a session + +A **session** is a conversation with an agent that runs in its own isolated workspace. Every session gets a **dedicated git worktree and branch**, which is what lets you run several sessions at once — one adding a feature, another fixing a bug — without their changes colliding. Your sessions appear in the sidebar grouped by repository; select any one to switch to it. + +Inside a session you'll see three things: the **conversation** with the agent, the agent's **tool activity** as it explores and edits files, and the list of **changed files** with their diffs. + +## Start a session and request our change + +Let's start a new session to begin exploring the project and implementing our feature. In a [prior lesson][prior-lesson] you added your project from its GitHub repository. We'll create a new session for that repository and request our change. + +1. Return to (or open) the GitHub Copilot app. +2. Select the **Home screen**. +3. Ensure `tailspin-toys` is selected for the repo. + + ![The GitHub Copilot app prompt box with the repository selector set to tailspin-toys and the model selector shown beneath the prompt](/images/learning-hub/copilot-workshops/app-2-start-session.png) + +4. Use the following prompt to request the change: + + ```plaintext + On the game cards, show each game's star rating. The Game type already includes a starRating field — it's a number out of 5, or null when a game hasn't been rated yet. Display it on each card in src/components/GameCard.astro, and when starRating is null show "No rating yet" instead. Keep the change small and don't restructure the card layout. + ``` + +> [!NOTE] +> Notice how the prompt contained the name of the file for Copilot to update. While it's not required at all to specify which files Copilot should include in its work, pointing it in the right direction both helps Copilot quickly generate code and reduce token usage. + +5. Select Enter to send the prompt to Copilot. + +Copilot app begins work by first creating a new worktree, an isolated copy of the project. It then explores the project, locating the necessary files to update to add the new feature. It will then create the necessary code. You've now added a new feature with Copilot app! + +## Review the diff + +All AI-generated changes deserve a review before they're merged, even small ones. Let's explore the changes, right here in Copilot app. + +1. In the upper right-hand corner of the app, select **Toggle review panel**. This will open the diff screen with all the outstanding changes made by Copilot. + + ![The GitHub Copilot app top toolbar with an arrow pointing to the Toggle review panel button to the right of Create PR](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. You should notice code added to `GameCard.astro`, the core file used to display game details. It should be similar to the following — a small block that renders the rating when present and falls back to "No rating yet" when `starRating` is `null`: + + ```astro + {game.starRating !== null ? ( + + ★ {game.starRating} / 5 + + ) : ( + + No rating yet + + )} + ``` + +> [!NOTE] +> Because Copilot, like all generative AI tools, is probabilistic rather than deterministic, the exact code may vary from the above. But it should be relatively similar. + +## Check the changes + +Of course we shouldn't just read the code and assume it works. We should visually test everything as well! To do so we'll need to start the app from the terminal, then confirm everything works. Fortunately there's a terminal built into Copilot app! + +1. In the review panel on the right side of Copilot app, select **Terminal**. If there is no **Terminal** button, select the **+** (labeled as **Open in panel**), then select **Terminal**. + + ![The Terminal button in the review panel of the GitHub Copilot app](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +2. Enter the following command in the terminal window to start the web app's dev server: + + ```shell + npm run dev + ``` + +3. Once the server starts (this will just take a moment), open a browser window. +4. Navigate to http://localhost:4321. +5. You should now see star ratings on all the games on the landing page! +6. Return to the terminal window. +7. Select Ctrl+C to stop the dev server. + +## Open and merge your first pull request + +Your change looks good — now it's time to ship it! You'll ask the agent to open a pull request, then review and merge it yourself on github.com. For now we'll manage this manually. In an upcoming lesson we'll explore how Copilot can handle some of the work for you automatically. + +1. In the upper right hand corner, select **Create PR**. +2. If prompted, select **Sign in with your browser** and follow the prompts to authenticate. +3. Copilot gets to work on creating the PR. + +Once the PR is created, Copilot will monitor any workflows on the repository that need to run. After a few moments, the button in the upper right will change to **Ready to merge**. This will be your indication your PR is ready to merge! + +4. Select the **PR** bubble just above chat to open your PR in the review pane to see your pull request. You can review the PR as needed here. +5. Once ready, select **Ready to merge**. +6. Select **Merge pull request** on the new dialog window to merge your pull request! + +You've now pushed a new feature to the website! + +## Summary and next steps + +You've started your first agent session and shipped your first change! Specifically, you: + +- started an agent session and learned how sessions are structured. +- directed the agent to make a small, focused change to the game cards. +- reviewed the change in the workspace diff view. +- ran the app locally to confirm the star rating in the browser. +- opened a pull request and merged it yourself on github.com. + +Next, you'll use the app to add a custom instructions standard to the repository — starting from one of the issues in your backlog. Continue to [Lesson 3 - Guiding Copilot with custom instructions][next-lesson]. + +## Resources + +- [Working with agent sessions in the GitHub Copilot app][agent-sessions] +- [About the GitHub Copilot app][about-copilot-app] +- [Managing issues and pull requests with the GitHub Copilot app][managing-issues-prs] + +[prior-lesson]: /learning-hub/copilot-workshops/app/1-install-copilot-app/#install-and-configure-the-github-copilot-app +[next-lesson]: /learning-hub/copilot-workshops/app/3-custom-instructions/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/3-custom-instructions.md b/website/src/content/docs/learning-hub/copilot-workshops/app/3-custom-instructions.md new file mode 100644 index 00000000..5024018e --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "Lesson 3 - Guiding Copilot with custom instructions" +description: "Use the GitHub Copilot app to add a custom instructions standard to your repository, starting from an issue in your backlog and merging the change as a pull request." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Context is key when working with generative AI. If a task needs to be done a particular way — or there's background information Copilot should know — you want that context available. One of the most powerful tools for this is [instruction files][instruction-files], which describe not just *what* code you want but *how* it should be structured. In this lesson you'll add a documentation standard to your repository, and you'll do it the way you'll do most work from here on: starting from an issue in your backlog and letting the agent make the change. + +In this lesson, you will: + +- explore how repository instructions and path-scoped instruction files reach the agent. +- start a session from the instructions issue in your backlog. +- ask the agent to add a documentation standard to `.github/copilot-instructions.md`. +- review the change and merge it as a pull request. + +## Scenario + +As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include: + +- Documentation should be added to code in the form of TSDoc doc comments. +- Formatting should be documented and enforced through linting. + +Through the use of instruction files you'll ensure Copilot has the right information to perform the tasks in alignment with the practices highlighted. + +## Instruction files + +Custom instructions allow you to provide context and preferences to Copilot, so that it can better understand your coding style and requirements. This is a powerful feature that can help you steer Copilot to get more relevant suggestions and code snippets. You can specify your preferred coding conventions, libraries, and even the types of comments you like to include in your code. You can create instructions for your entire repository, or for specific types of files for task-level context. + +There are two types of instructions files: + +- `.github/copilot-instructions.md`, a single instruction file sent to Copilot for **every** request for the repository. This file should contain project-level information — context relevant for most chat or CLI requests sent to Copilot. This could include the tech stack being used, an overview of what's being built, best practices, and other global guidance. +- `.github/instructions/*.instructions.md` files can be created for specific tasks or file types. You can use them to provide guidelines for particular languages (like TypeScript or Astro), or for tasks like creating a UI component or a new set of unit tests. + +> [!NOTE] +> Copilot supports other standards to bring in instructions guidance through AGENTS.md, CLAUDE.md and GEMINI.md, allowing you to ensure Copilot always has the right context. + +### Best practices for managing instructions files + +A full conversation about creating instructions files is beyond the scope of the workshop. However, the examples provided in the sample project show a representative approach. At a high level: + +- Keep instructions in `copilot-instructions.md` focused on project-level guidance, such as a description of what's being built, the structure of the project, and global coding standards. +- Use `*.instructions.md` files to provide specific instructions for file types (unit tests, Astro components, the data layer), or for specific tasks. +- Use natural language. Keep guidance clear. Provide examples of how code should (and shouldn't) look. + +There isn't one specific way to create instructions files, just as there isn't one specific way to use AI. You will find through experimentation what works best for your project. + +> [!TIP] +> Every project using GitHub Copilot should have a robust collection of instruction files. As you explore the ones in this project, you may notice there are instructions files for numerous types of code files. +> +> Looking for templates or a starting point? Explore [awesome-copilot][awesome-copilot], a repository full of instruction files, custom agents, and other resources. + +## Explore the custom instructions files in this project + +Take a moment to read the instruction files this repository ships with — there's one core `copilot-instructions.md` and a collection of `*.instructions.md` files for various tasks. Open these in your editor or the GitHub web UI. + +1. If the review panel is not already visible, open it by selecting **Toggle review panel** in the upper right. + + ![The GitHub Copilot app top toolbar with an arrow pointing to the Toggle review panel button to the right of Create PR](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. Select the **+** to add a new item to the review panel. +3. Select **File**. +4. Search for `copilot-instructions.md`. +5. Select `copilot-instructions.md` from the list of files to open it. +6. Explore the file, noting the brief description of the project plus sections such as **Agent notes**, **Code standards**, **Scripts**, and **Repository Structure**. Under **Code standards**, note the nested **GitHub Actions Workflows** guidance. These are applicable to any interactions you'd have with Copilot. +7. Select **Show folder view** to open the folder navigator. + + ![The Show folder view button in the review panel with a file open in the GitHub Copilot app](/images/learning-hub/copilot-workshops/app-show-folder-view.png) + +8. Navigate to the `.github/instructions` folder and explore the files. Note there are instructions for Astro files, the Drizzle data layer, tests, and more. +9. Open `.github/instructions/unit-tests.instructions.md`. Note the `applyTo` field at the top — this sets a glob (relative to the repo root) that determines which files the instructions apply to. Here, any TypeScript test file (for example, one matching `**/*.test.ts`) will match. +10. Note the instructions specific to creating unit tests for this project. +11. Finally, open `.github/instructions/drizzle.instructions.md` and scroll to the bottom. Note the links to other instruction files (like `unit-tests.instructions.md`) and existing files in the project. This lets you break larger instruction sets into smaller, reusable files, and point Copilot at examples to follow when generating code. (Paths there are relative to the instruction file rather than the repo root.) + +> [!NOTE] +> The **Code formatting requirements** section in `copilot-instructions.md` documents the project's coding standards, but it doesn't yet require in-code documentation. In the next steps, you'll add rules for TSDoc doc comments and file comment headers. + +## Start from the instructions issue + +In the previous lesson you started a session from a direct prompt. Most work, however, starts with an issue. Let's create a new session based off an issue filed to update the instructions files, then make the request for the update. + +> [!NOTE] +> Because instructions files have a large impact on the code generated by Copilot, care should be taken in ensuring they clearly guide Copilot. Having Copilot create a first version, like you'll do in this lesson is a great approach, followed by a review by you to ensure the updates meet your requirements. + +1. Select **My work** in the sidebar +2. Select the issue titled **Update our repository coding standards** to open the issue. +3. Select **New session** in the upper right to start a new session based on the issue. + + ![The issue view in the GitHub Copilot app with an arrow pointing to the New session button in the upper right](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. Use the following prompt to request Copilot update the instructions files to meet the requirements documented in the issue: + + ```plaintext + Following this issue, make the updates to the instructions files in this project to meet the requirements documented. Don't create the PR quite yet! + ``` + +Copilot will make the updates! + +## Review the change + +Let's both read through the updates Copilot made, but also ask it to provide an example of the code it will now generate based on the updated instructions. + +1. Select **Changes** in the upper right to open the code changes. + + ![The session panel tabs in the GitHub Copilot app with an arrow pointing to the Changes tab](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. Review the updated instructions file. Confirm it has the guidelines about adding documentation and comments to the code. + +> [!NOTE] +> Because AI is probabilistic rather than deterministic, the exact text will vary. + +3. Use the following prompt to ask Copilot to create an example of the code it will now generate: + + ```plaintext + Do not make any updates, but show me what the code would look like. Based on the new instructions, if I asked Copilot to create a new library component to return all Publishers what would that code look like? + ``` + +4. Review the code Copilot proposes. Note the TSDoc doc comments and the file header comment it includes — exactly what the updated instructions ask for. + +You've now updated the instructions files in the project and seen the impact it will have! + +## Open and merge the pull request + +Instructions files become assets in the repository, meaning they're shared with the rest of the team. Let's create a PR with our work, just like we would any other asset! + +1. In the upper right hand corner, select **Create PR**. +2. If prompted, select **Sign in with your browser** and follow the prompts to authenticate. +3. Copilot gets to work on creating the PR. + +Once the PR is created, Copilot will monitor any workflows on the repository that need to run. After a few moments, the button in the upper right will change to **Ready to merge**. This will be your indication your PR is ready to merge! + +4. Select **Ready to merge**. +5. Select **Merge pull request** on the new dialog window to merge your pull request! + +> [!NOTE] +> With the standard merged into your default branch, it becomes part of the project for everyone — and for every new session. When you start the filtering session in the next lesson from an up-to-date default branch, the agent will follow this standard automatically. You'll see the TypeScript it generates include TSDoc doc comments without being asked — a small but real demonstration of instructions shaping generated code. + +## Summary and next steps + +You explored how the app picks up context from instruction files, then used a session to add and merge a repository-wide standard. Specifically, you: + +- explored the repository's `copilot-instructions.md` and path-scoped `*.instructions.md` files. +- started a session from the instructions issue in your backlog. +- asked the agent to add a documentation standard to `.github/copilot-instructions.md`. +- reviewed the change and merged it as a pull request. + +Next, you'll build the filtering feature in a fresh session — and watch it pick up the standard you just merged. Continue to [Lesson 4 - Building a feature with Autopilot][next-lesson]. + +## Resources + +- [Instruction files for GitHub Copilot customization][instruction-files] +- [Customizing the GitHub Copilot app][customize-app] +- [Best practices for creating custom instructions][instructions-best-practices] +- [Awesome Copilot — a collection of instruction files and other resources][awesome-copilot] + +[next-lesson]: /learning-hub/copilot-workshops/app/4-build-filtering/ +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[awesome-copilot]: https://awesome-copilot.github.com/ +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/4-build-filtering.md b/website/src/content/docs/learning-hub/copilot-workshops/app/4-build-filtering.md new file mode 100644 index 00000000..5bbafae3 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "Lesson 4 - Building a feature with Autopilot" +description: "Use Plan and Autopilot modes in the GitHub Copilot app to build a static, client-side filtering feature, watch it inherit your documentation standard, and verify it with an agent skill." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +We've made a couple of small updates to our project thus far. But more robust changes require a more robust process. Fortunately, the GitHub Copilot app is built to work with our existing flow, ensuring we build the right things the right way. This is the first of three lessons where you will follow a typical development process, starting by using an issue to generate a new feature and an agent skill to run the validation tests and linters. + +In this lesson, you will: + +- start a fresh session from the filtering issue. +- use **Plan** mode to plan the feature, then **Autopilot** to build it. +- confirm the generated code follows the documentation standard you merged earlier. +- verify your work with the project's `quality-checks` skill. + +## Scenario + +The home page lists every game, but visitors can't narrow the list down. The filtering issue asks you to let them filter games by **category** and **publisher**. Let's use Copilot to implement that functionality. + +## Background + +Introducing AI coding agents to your development flow doesn't change the fundamentals. If anything, they become even more important! Most developers follow a flow that resembles: + +1. Open a filed issue with details of what needs to be done. +2. Create a plan of what needs to be built. +3. Build and review the code. +4. Run the tests to validate the code. +5. Manually validate the new functionality. +6. Create a pull request (PR). +7. Once the code has been reviewed and the continuous integration process succeeds, merge the code. + +> [!NOTE] +> Depending on your team and organization, the exact specifics will vary. But most will be a variation on the theme listed above. + +By sticking to this standard approach you ensure the code generated by AI meets the requirements set forth, and goes through the same vetting process as code written by hand. + +## Session modes + +The **session mode** controls how much autonomy the agent has. You can set it from the dropdown below the prompt field and change it at any time: + +- **Interactive**: You and the agent work together. The agent suggests changes and waits for your input before proceeding. +- **Plan**: The agent creates a plan first. You review and approve the plan before the agent executes it. +- **Autopilot**: The agent works fully autonomously—writing code, running tests, and iterating without waiting for input. + +## Plan the filtering feature + +The best time to catch a potential issue is before any code is written, and the best way to do that is a bit of planning in advance. By planning with Copilot you'll ask Copilot to generate a set of steps and document the approach it will take. You can then review the plan, make any suggestions you might have to improve it, before letting Copilot generate the code based on the plan. + +Let's open the issue, start a new session, and create a plan by switching into plan mode and making the request. + +1. Select **My work** from the navigation tab. +2. Select the issue titled **Allow users to filter games by category and publisher**. +3. Select **New session** in the upper right. + + ![The issue view in the GitHub Copilot app with an arrow pointing to the New session button in the upper right](/images/learning-hub/copilot-workshops/app-new-session-from-issue.png) + +4. Select Shift+Tab until the mode displays **Plan**. + + ![The GitHub Copilot app prompt box with an arrow pointing to the mode selector set to Plan](/images/learning-hub/copilot-workshops/app-4-plan-mode.png) + +5. Send the following prompt. The filtering issue is already in this session's context because you started from it: + + ```plaintext + Plan the work based on the requirements documented in the issue. Please ask any clarifying questions you might have as you build the plan. + ``` + +6. The agent may ask follow-up questions as it builds the plan. Answer them based on how you'd build the feature. + +> [!NOTE] +> Because Copilot is probabilistic, the exact follow-up questions Copilot asks will vary. In fact, it might not ask any questions! This is perfectly normal. + +7. Once completed, Copilot will offer a plan summary. Review the plan. You should see it propose building queries, adding filter controls, and of course tests. Provide feedback to refine it if you'd like — the agent will incorporate your suggestions into a new version. + +## Build it with Autopilot + +With the plan created, let's let Copilot build the implementation! + +1. In the list of options in the **Plan summary** dialog, select the option closest to **Approve and implement with autopilot**. + +Copilot will begin work on the implementation! + +> [!NOTE] +> If Copilot doesn't automatically start creating the necessary code, you can prompt it to do so by using a prompt like "Go ahead and start building out the plan!". +> +> Creating the necessary updates will take several minutes. The agent edits and creates files, writes and runs tests, and iterates. Now's a good time to reflect on what you've explored so far, or to enjoy a beverage. + +## Review the changes + +All AI-generated code needs review before it's merged. Let's both review the code and run the site to ensure everything looks good. + +1. Select **Changes** in the upper right to open the code changes. + + ![The session panel tabs in the GitHub Copilot app with an arrow pointing to the Changes tab](/images/learning-hub/copilot-workshops/app-select-changes.png) + +2. Review the changes. You should see new TypeScript and Astro files, and test files. Notice the new helper functions include TSDoc doc comments and a file header comment — the documentation standard you merged in Lesson 3, applied automatically without being asked. +3. In the review panel on the right side of Copilot app, select **Terminal**. If there is no **Terminal** button, select the **+** (labeled as **Open in panel**), then select **Terminal**. + + ![The Terminal button in the review panel of the GitHub Copilot app](/images/learning-hub/copilot-workshops/app-terminal-screenshot.png) + +4. Enter the following command in the terminal window to start the web app's dev server: + + ```shell + npm run dev + ``` + +5. Once the server starts (this will just take a moment), open a browser window. +6. Navigate to http://localhost:4321. +7. You should now see filters available on the landing page! +8. If anything doesn't look right, you can ask Copilot to make the updates! +9. Once satisfied, return to the terminal window. +10. Select Ctrl+C to stop the dev server. + +## Verify your work with the quality-checks skill + +You could eyeball the diff and call it done, but the team has a defined quality bar — and a repeatable way to check it. + +**Agent skills** let you give Copilot guidance on how to perform repeatable tasks like running tests, generating builds, or creating pull requests. A skill is a folder of instructions, scripts, and resources that the agent can load on demand. [Agent Skills is an open standard][agent-skills-repo] used by a range of agents, so the same skill works across Copilot Chat in agent mode, Copilot cloud agent, Copilot CLI, and the GitHub Copilot app. + +Skills live in the `.github/skills` folder of a project, or globally in `~/.copilot/skills`. Each skill is a folder containing a `SKILL.md` file with YAML frontmatter (a `name` and a `description`) followed by the markdown instructions: + +```yaml +--- +name: quality-checks +description: Run the project's test suites and linter to verify code changes are ready to commit, push, or merge. +--- +``` + +Skills can also include subfolders with scripts, assets, and reference material. The full structure is covered in the [agent skills specification][agent-skills-spec]. + +> [!TIP] +> Skills are loaded dynamically. The agent decides which skill applies based on the `description` field — a clear, scenario-specific description is the difference between a skill that gets used and one that gets ignored. + +## Explore the quality-checks skill + +Let's explore the skill to see what it does. + +1. If the review panel is not already visible, open it by selecting **Toggle review panel** in the upper right. + + ![The GitHub Copilot app top toolbar with an arrow pointing to the Toggle review panel button to the right of Create PR](/images/learning-hub/copilot-workshops/app-2-review-panel.png) + +2. Select the **+** to add a new item to the review panel. +3. Select **File**. +4. Search for `SKILL.md`. +5. Select `SKILL.md .github/skills/quality-checks` from the list of files to open it. +6. Note the `name` and `description`. The description tells the agent *when* to use it — whenever code changes need to be tested, linted, or verified before a commit, push, or merge. +7. Read through the skill. Notice it documents which script runs which suite (unit tests, Playwright end-to-end tests, ESLint), in what order, and how to debug common failures — so the agent runs the checks the team's way instead of guessing. + +## Run the checks + +In the same filtering session, ask the agent to verify the work. You won't name the skill — the agent will match it from your request. + +1. Return to Copilot app. +2. Directly call the skill by using the slash command `/quality-checks` and select Enter. +3. Following the skill, the agent runs the unit tests, the linter, and the end-to-end tests, and reports the results. If anything fails, ask it to fix the issue and run the checks again until everything is green. +4. **Keep this session open.** In the next lesson you'll add the Playwright MCP server and use it to see the filtering feature working in a real browser. + +## Summary and next steps + +You built a real feature end to end and verified it against the team's bar! Specifically, you: + +- started a fresh session from the filtering issue on an up-to-date project. +- used Plan mode to plan the feature and Autopilot to build it. +- confirmed the generated helper followed the documentation standard you merged in Lesson 3. +- verified your work with the `quality-checks` skill. + +Next, you'll connect the Playwright MCP server and ask the agent to explore your filtering feature in a real browser. Continue to [Lesson 5 - Testing with the Playwright MCP server][next-lesson]. + +## Resources + +- [Working with agent sessions in the GitHub Copilot app][agent-sessions] +- [About Agent Skills][about-agent-skills] +- [Customizing the GitHub Copilot app][customize-app] +- [About cloud and local sandboxes for GitHub Copilot][sandboxes] + +[ex0]: /learning-hub/copilot-workshops/app/0-prerequisites/ +[ex2]: /learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /learning-hub/copilot-workshops/app/3-custom-instructions/ +[next-lesson]: /learning-hub/copilot-workshops/app/5-mcp-playwright/ +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[agent-skills-repo]: https://github.com/agentskills/agentskills +[agent-skills-spec]: https://agentskills.io/specification diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/5-mcp-playwright.md b/website/src/content/docs/learning-hub/copilot-workshops/app/5-mcp-playwright.md new file mode 100644 index 00000000..34ce935c --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "Lesson 5 - Testing with the Playwright MCP server" +description: "Add the Playwright MCP server to the GitHub Copilot app and ask the agent to manually test your filtering feature in a real browser." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +In the previous lesson you created and verified the filtering feature with the project's automated test suite. Tests automate validation of code, but allowing the agent to confirm behavior is powerful. It allows an agent to respond to issues it sees in the actual UI it's creating. Let's explore how MCP allows access to external capabilities to AI agents, and add the Playwright MCP server to allow Copilot to interact with the site you're building directly. + +In this lesson, you will: + +- understand what Model Context Protocol (MCP) is and how the GitHub Copilot app uses it. +- add the Playwright MCP server from the app settings. +- ask the agent to drive a browser and explore your filtering feature. + +## Scenario + +While unit and end-to-end tests are important, validating updates to the UI requires actually interacting with the UI. You want to allow Copilot to use the website you're working on as a user would to further automate how changes are made, providing more confidence the updates perform as expected. + +## What is Model Context Protocol (MCP)? + +[Model Context Protocol (MCP)][mcp-blog-post] provides AI agents with a way to communicate with external tools and services. By using MCP, AI agents can communicate with external tools and services in real-time. This allows them to access up-to-date information (using resources) and perform actions on your behalf (using tools). + +These tools and resources are accessed through an MCP server, which acts as a bridge between the AI agent and the external tools and services. The MCP server is responsible for managing the communication between the AI agent and the external tools (such as existing APIs or local tools like NPM packages). Each MCP server represents a different set of tools and resources that the AI agent can access. + +A couple of popular existing MCP servers are: + +- **[GitHub MCP Server](https://github.com/github/github-mcp-server)**: This server provides access to a set of APIs for managing your GitHub repositories. It allows the AI agent to perform actions such as creating new repositories, updating existing ones, and managing issues and pull requests. +- **[Playwright MCP Server][playwright-mcp-server]**: This server provides browser automation capabilities using Playwright. It allows the AI agent to perform actions such as navigating to web pages, filling out forms, and clicking buttons. + +There are many other MCP servers available that provide access to different tools and resources. GitHub hosts an [MCP registry](https://github.com/mcp) to enhance discoverability and contributions to the ecosystem. + +> [!CAUTION] +> Treat MCP servers as you would any other dependency in your project. Before using an MCP server, carefully review its source code, verify the publisher, and consider the security implications. Only use MCP servers that you trust and be cautious about granting access to sensitive resources or operations. + +## Add the Playwright MCP server + +You add and manage MCP servers from the app settings. The app includes a catalog of popular servers, so the [Playwright MCP server][playwright-mcp-server] is just a couple of clicks away. + +1. Select Ctrl+, to open the Copilot app settings page. +2. Select **MCP servers**. +3. In the search dialog, type `Playwright`. +4. Select **Playwright** from the list of **Popular MCP servers**. +5. Select **Add server** to add it to the list of available MCP servers. +6. Select Esc to close the settings dialog. + +You've now added the Playwright MCP server! + +## Ask Copilot to explore the feature via Playwright + +Let's ask Copilot to test the feature manually by using the Playwright MCP server. + +1. Use the following prompt to ask Copilot to validate the new functionality: + + ```plaintext + Start the dev server then use the Playwright MCP server to validate the functionality you just added exists. Use the details in the issue to ensure the newly added behavior matches the specs. + ``` + +Copilot will launch a browser through the Playwright MCP server, walk through each step, and report back what it found. You'll actually see it open a browser on your system to perform the tasks! + +2. Read its summary against the acceptance criteria in the issue. If something looks off, ask follow-up questions or send it back to fix the code before you open a pull request. +3. Leave this session open as we're going to close it out in the next lesson! + +Copilot has now also validated the functionality in the browser by exploring the feature like a user would. + +## Summary and next steps + +Congratulations, you used the Playwright MCP server to explore your feature in a real browser from the GitHub Copilot app! To recap, you: + +- learned what Model Context Protocol (MCP) is and how the app makes MCP tools available. +- added the Playwright MCP server from the app settings. +- asked the agent to drive a browser and explore your filtering feature. + +Your feature is built, verified, and seen working. Now it's time to ship it — using **Agent Merge** to open and merge the pull request for you. Continue to [Lesson 6 - Merging with Agent Merge][next-lesson]. + +## Resources + +- [What the heck is MCP and why is everyone talking about it?][mcp-blog-post] +- [Microsoft Playwright MCP Server][playwright-mcp-server] +- [Configuring MCP servers in the GitHub Copilot app][customize-app] + +[next-lesson]: /learning-hub/copilot-workshops/app/6-agent-merge/ +[mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/ +[playwright-mcp-server]: https://github.com/microsoft/playwright-mcp +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/6-agent-merge.md b/website/src/content/docs/learning-hub/copilot-workshops/app/6-agent-merge.md new file mode 100644 index 00000000..25ef0c19 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "Lesson 6 - Merging with Agent Merge" +description: "Open the filtering pull request, review it in My work, and let Agent Merge fix what's blocking it and merge it for you — the top rung of the merge-automation ladder." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Your filtering feature is built, verified, and seen working in a browser. The last step is to merge it. You've merged twice already in this harness — both times you opened the pull request and merged it yourself on github.com. This time you'll let the app do the heavy lifting with **Agent Merge**, which shepherds a pull request through its whole lifecycle from inside the app. + +In this lesson, you will: + +- learn what Agent Merge is and how it automates the merge lifecycle. +- enable Agent Merge on your filtering session. +- watch it create the pull request, run CI, and merge when everything is green. + +## Scenario + +Over the last few modules you've explored various levels of automation, from creating code to allowing Copilot to validate a UI directly. To further speed development, Tailspin Toys would like to see if there's a way pull requests that have been vetted and validated can automatically be merged. + +## Introducing Agent Merge + +**Agent Merge** allows automation of the last mile of landing a pull request via Copilot app. When you enable it, the app's session reads your pull request, addresses what's blocking it — fixing failing CI checks, responding to review comments, rebasing when needed — and merges it as soon as GitHub allows. It runs in the background, survives app restarts, and turns itself off once your pull request is merged. + +Up to this point you've been the one clicking **Merge pull request** on github.com. Agent Merge shifts that responsibility to the agent so you can move on to the next task while it shepherds the PR through to completion. You still review and approve the work — the agent just handles the mechanical finish line. + +## Use Agent Merge to manage the PR + +You've reviewed the code manually, run tests, and even allowed Copilot to validate the UI. Now it's time to merge the new code into the codebase! Let's allow agent merge to shepherd the PR through continuous integration (CI) and to merge. + +1. Return to the session you had open from the previous module where you were adding filtering functionality. +2. In the upper right-hand corner, select the dropdown next to **Create PR**. +3. Select **Agent merge** to enable agent merge. + + ![The Create PR dropdown in the GitHub Copilot app expanded, with an arrow pointing to the Agent merge option](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. The button text now changes to **Agent merge**. +5. Select the **Agent merge** button to start the agent merge process. + +Copilot app then begins the process of creating and managing the PR! It starts by exploring the project to determine how best to create a PR, followed by creating the new PR. + +After a few moments, you'll notice Copilot starts work again, looking at the PR conditions - the CI process of running all the tests on your repository. It will report back status on any reviews left by other team members, any checks that need to run (the CI process), and if the PR is mergeable. + +6. Allow agent merge to merge the pull request by selecting the dropdown next to **Agent merge** then **Merge pull request**. + + ![The Agent merge dropdown showing the agent's allowed actions — Address reviews, Fix CI failures, Resolve conflicts — with an arrow pointing to Merge pull request](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. Once all CI processes are green (meaning the tests passed), Copilot will merge the pull request! + +## Summary and next steps + +You've automated several parts of the development process, including generating code, testing and validating code, and now the pull request process. You: + +- learned what Agent Merge is and how it automates the merge lifecycle. +- enabled Agent Merge on your filtering session. +- watched it create the pull request, run CI, and merge when everything was green. + +Next, you'll explore **canvases** — a richer way to plan and visualize work with the agent. Continue to [Lesson 7 - Planning with canvases][next-lesson]. + +## Resources + +- [Managing issues and pull requests with the GitHub Copilot app][managing-issues-prs] +- [About the GitHub Copilot app][about-copilot-app] + +[next-lesson]: /learning-hub/copilot-workshops/app/7-canvases/ +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/7-canvases.md b/website/src/content/docs/learning-hub/copilot-workshops/app/7-canvases.md new file mode 100644 index 00000000..89da8951 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "Lesson 7 - Planning with canvases" +description: "Create a shared, agent-driven canvas in the GitHub Copilot app to plan and track your work alongside the agent." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +So far you've directed agents through chat. But a lot of work doesn't live in a conversation — it lives on a board, in a document, or on a checklist. **Canvases** give you and the agent a shared surface for exactly that kind of work, right inside the app. In this lesson you'll create a simple canvas to plan and track the backlog you've been working through. + +In this lesson, you will: + +- understand what a canvas is and when to use one. +- create a shared Kanban board canvas to triage your backlog. +- save the canvas to your repository and merge it for the team. +- open the canvas in a new session and start work from it. + +## Scenario + +Looking at a list of issues can be rather daunting, even in the best of times. Tailspin Toys' developers have been looking for a tool that would allow them to quickly triage issues, and begin work on them in Copilot app. + +## What is a canvas? + +A [canvas][canvas-docs] is a shared, interactive surface for a work artifact — a plan, a triage board, a release checklist, a dashboard, or a document. While chat is great for describing intent and reasoning through ambiguity, most work happens on a *surface*. Canvases let you collaborate with the agent directly on that surface. + +Canvases are **bidirectional**: the agent can update the canvas while it works, and you can edit the same surface yourself. When you create a canvas, the agent builds it based on your prompt and workflow, and you can ask it to add, remove, or revise capabilities as you go. Once created, a canvas opens in the app's right side panel. + +Some common examples include: + +- **Markdown canvases** for planning your day and prioritizing issues and pull requests. +- **Agentic kanban boards** where people and agents add cards and move work across columns. +- **Issue triage boards** that summarize top issues and recurring themes for a repository. + +## Why use a canvas? + +Reach for a canvas when a task needs structure, iteration, and verification, and a chat alone isn't enough. A canvas lets you: + +- ground the agent's work in an actual artifact that fits your workflow. +- steer or correct work directly on the shared surface, then let the agent continue from your changes. +- inspect progress as visible changes to an artifact, not just chat responses. + +## Create a canvas to track your work + +You've shipped a lot: the star rating, the documentation standard, and the filtering feature are all merged. But there's still items on the backlog. Let's create the canvas to help quickly triage the work. + +1. Return to (or open) the GitHub Copilot app. +2. Select the **Home screen**. +3. Ensure `tailspin-toys` is selected for the repo. +4. In the prompt box, use the following prompt to create our canvas that meets our needs: + + ```plaintext + Create a basic Kanban board canvas that allows me to quickly triage work. Highlight the three issues which are most likely to need attention right now, with the remainder in a second section down below. The top three cards should include a description of the issue's content and a justification of why they're at the top of the list. Each issue should have a button that allows me to add it to the current context for the current session so I can get to work on it straightaway. + ``` + +Copilot will get to work on creating the canvas! + +> [!NOTE] +> This will take a few minutes for it to do so. Because this is a complicated task, you might not be satisfied with the first version. You can continue to prompt to build the tool of your dreams! + +## Save the canvas and merge it to the repository + +Canvases can become assets in the repository, just like instructions files and skills. Let's ask Copilot to add it to our repository and merge it so the whole team can use it. + +1. In the same session, ask Copilot to save the canvas to the repository by using the following prompt: + + ```plaintext + Let's save this canvas definition to the repository so I can share it with my development team + ``` + +2. Once Copilot has saved the canvas files, select the dropdown next to **Create PR** in the upper right-hand corner. +3. Select **Agent merge** to enable agent merge. + + ![The Create PR dropdown in the GitHub Copilot app expanded, with an arrow pointing to the Agent merge option](/images/learning-hub/copilot-workshops/app-enable-agent-merge.png) + +4. The button text now changes to **Agent merge**. +5. Select the **Agent merge** button to start the agent merge process. + +Copilot app begins the process of creating and managing the PR. It starts by exploring the project to determine how best to create a PR, then creates it. + +After a few moments, you'll notice Copilot starts work again, looking at the PR conditions — the CI process of running all the tests on your repository. It will report back status on any reviews left by other team members, any checks that need to run (the CI process), and if the PR is mergeable. + +6. Allow agent merge to merge the pull request by selecting the dropdown next to **Agent merge** then **Merge pull request**. + + ![The Agent merge dropdown showing the agent's allowed actions — Address reviews, Fix CI failures, Resolve conflicts — with an arrow pointing to Merge pull request](/images/learning-hub/copilot-workshops/app-agent-merge-merge.png) + +7. Wait for all CI processes to pass (go green). Once they do, Copilot will merge the pull request automatically! + +You've now created a new shared canvas for your team! + +## Work in the canvas + +With the canvas created, let's start a new session and put it to work! + +1. Inside the Copilot app, start a new session by selecting **New session** next to **tailspin-toys**. +2. Ask Copilot to open the triage canvas by using the following prompt: + + ```plaintext + Open the triage issues canvas + ``` + +3. You should notice the canvas you built is now open in this new session! +4. Select **Add to current context** on one of the issues that's of most interest to you. +5. Copilot gets to work on the issue! + +You've now used a canvas you created to streamline the development process. + +## Summary and next steps + +You created a shared surface where you and the agent can collaborate! You: + +- learned what canvases are and when to use them. +- created a shared Kanban triage board canvas with the agent. +- saved and merged the canvas to your repository with Agent Merge. +- opened the canvas in a new session and used it to start work. + +With your backlog tracked, take a step back to review everything you've built and where to go next. Continue to [Lesson 8 - Review and next steps][next-lesson]. + +## Resources + +- [Working with canvas extensions in the GitHub Copilot app][canvas-docs] +- [Canvases on Awesome Copilot][awesome-copilot-canvases] +- [About the GitHub Copilot app][about-copilot-app] + +[next-lesson]: /learning-hub/copilot-workshops/app/8-review/ +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/8-review.md b/website/src/content/docs/learning-hub/copilot-workshops/app/8-review.md new file mode 100644 index 00000000..0bcd88bf --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "Lesson 8 - Review and next steps" +description: "Recap the GitHub Copilot app harness, automate recurring work, and explore where to go next." +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Over the last several lessons, you took a feature from idea to merge with the GitHub Copilot app, including: + +- connecting a repository and orienting to the app's workspace and your seeded backlog. +- starting sessions from a direct task and from issues, and using Plan and Autopilot modes to control how the agent works. +- guiding the agent with custom instructions and a reusable skill. +- testing your work with the Playwright MCP server in a real browser. +- collaborating with the agent on a shared canvas. +- shipping changes up a ladder of merge automation — from merging on github.com yourself to letting **Agent Merge** land a pull request. + +Let's automate some recurring work, talk through best practices, and look at where to go next. + +## Automate recurring work + +The app can run agents for you on a schedule or on demand through **automations** — great for routine tasks like triaging new issues or recapping recent activity. Let's create a simple, non-destructive one. + +1. Select **Automations** in the sidebar, then select **New automation**. +2. Give it a name, such as `Recap my recent work`. +3. Choose a trigger. **Manual** lets you run it on demand; **On a schedule** runs it automatically; **When an issue is created** reacts to new issues. Choose **Manual** for this lesson. +4. Enter a read-only prompt so the automation can't change anything, for example: + + ```plaintext + Summarize the pull requests merged in this repository over the last week, and list any issues still open in the backlog. + ``` + +5. Pick the project (your Tailspin Toys repository) and create the automation. +6. Run it on demand to see the result. + +> [!TIP] +> Automations can run locally or in the cloud. Enable **Run in the cloud** and pick the **Tools** an automation may use when you want it to run unattended on a schedule. Keep scheduled automations scoped and non-destructive until you trust their output. + +## Best practices + +When using any AI tool, the infrastructure around it drives the quality of what you get out. Instructions files, skills, and custom agents all played a part in this workshop — invest in them and reuse them across sessions. + +Match the **mode and model** to the task. Use **Plan** to think through an approach before building, **Interactive** to stay in the loop on focused changes, and **Autopilot** only for well-scoped, isolated tasks. Choose a faster model for routine edits and a more capable model with higher reasoning effort for complex work. + +Context still matters as much as infrastructure. Clearly describing *what* you want built, *why*, and *how* meaningfully changes the output. Quick chats are a great place to scope an idea before you commit it to a full session. + +## More to explore + +You've covered the core workflow. A few more features worth a look: + +- **Quick chats** for fast, throwaway questions that don't need a full session. +- **Rubber duck** to talk through a problem and get high-signal feedback before you build. +- [**Custom agents**][custom-agents] to package a role, its tools, and its instructions for repeatable, specialized work. +- [`/chronicle`][chronicle] to generate a narrative of what happened in a session. +- [Bring your own key (BYOK)][byok] to use models from your own provider, including local models via Ollama, Foundry Local, or LM Studio. +- [Cloud sandboxes][sandboxes] to run sessions in a GitHub-hosted isolated environment. +- [Deep links][deep-links] to open the app straight into a repository, session, or prompt. + +## Next steps + +The best way to improve with any tool is to keep using it! Use it for production code, for hobby code, for the little app you've had in mind for years but never got around to building. Share your learnings with your team, and learn from theirs. And, as always, explore the documentation. + +If you'd like to explore more of the GitHub Copilot ecosystem, check out the [VS Code harness](/learning-hub/copilot-workshops/vscode/), the [Copilot CLI harness](/learning-hub/copilot-workshops/cli/), or the [Cloud agent harness](/learning-hub/copilot-workshops/cloud/). + +## Resources + +- [About the GitHub Copilot app][about-copilot-app] +- [Getting started with the GitHub Copilot app][getting-started] +- [Customize the GitHub Copilot app][customize] +- [Using automations][using-automations] +- [Working with canvas extensions][canvas-docs] +- [About cloud and local sandboxes][sandboxes] + +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[customize]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[using-automations]: https://docs.github.com/copilot/how-tos/github-copilot-app/using-automations +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links diff --git a/website/src/content/docs/learning-hub/copilot-workshops/app/index.md b/website/src/content/docs/learning-hub/copilot-workshops/app/index.md new file mode 100644 index 00000000..4ba528d6 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/app/index.md @@ -0,0 +1,57 @@ +--- +title: "GitHub Copilot app" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +The **[GitHub Copilot app](https://docs.github.com/copilot/concepts/agents/github-copilot-app)** is a desktop application built on Copilot CLI that brings agent-driven development into a single, focused workspace. It adds parallel agent sessions, switchable session modes, shared canvases, and native GitHub issue and pull request management — including **Agent Merge**, which shepherds a pull request through rebases, review feedback, CI fixes, and merge. + +Across these lessons you'll install the app and set up your project, then get oriented in the app's workspace and the backlog the template seeded for you. You'll start with a small change — adding a star rating — then add a custom instructions standard from an issue, build a filtering feature in an isolated agent session, and verify it with a reusable skill. You'll add the Playwright MCP server to explore the feature in a real browser, then climb a ladder of merge automation that ends with **Agent Merge** landing your pull request. Finally you'll collaborate on a shared canvas and automate recurring work — a complete loop from idea to merged feature. + +## Lessons + +| Lesson | Topic | Description | +|--------|-------|-------------| +| [0. Prerequisites][ex0] | Setup | Install Node.js and create your copy of the Tailspin Toys project | +| [1. Install the Copilot app][ex1] | Setup | Install the app, connect your project, and get oriented in the workspace | +| [2. Running your first agent session][ex2] | First change | Start a session and ship a small change as your first pull request | +| [3. Guiding Copilot with custom instructions][ex3] | Context | Add a documentation standard from an issue and merge it | +| [4. Building a feature with Autopilot][ex4] | Core Feature | Use Plan and Autopilot to build filtering, then verify it with a skill | +| [5. Testing with Playwright MCP][ex5] | External Tools | Add the Playwright MCP server and explore your feature in a browser | +| [6. Merging with Agent Merge][ex6] | Merge | Let Agent Merge fix and land your filtering pull request | +| [7. Planning with canvases][ex7] | Collaboration | Create a shared canvas to plan and track your work | +| [8. Review and next steps][ex8] | Summary | Automate recurring tasks and explore what's next | + +## Prerequisites + +Before attending this workshop, please ensure you have: + +- [ ] A GitHub account with an active **Copilot Student, Pro, Pro+, Business, or Enterprise** plan +- [ ] A computer running **macOS, Linux, or Windows** +- [ ] [Git installed][install-git] on your computer + +> [!TIP] +> No paid plan? Verified students can get GitHub Copilot for free through [GitHub Education][callout-student-plan-education]. The **Copilot Student** plan includes the agent, MCP, code review, and Copilot CLI features this workshop uses — so you can complete every harness with it. + +> [!NOTE] +> Because the Copilot app runs on your own machine rather than in a codespace, [Lesson 0][ex0] walks you through installing Node.js and creating your copy of the project before you install the app. + +> [!NOTE] +> If you are using Copilot Business or Copilot Enterprise, your administrator must enable the **Copilot CLI** policy before you can use the app. + +## Get Started + +**[Start with Lesson 0: Prerequisites →][ex0]** + +[ex0]: /learning-hub/copilot-workshops/app/0-prerequisites/ +[ex1]: /learning-hub/copilot-workshops/app/1-install-copilot-app/ +[ex2]: /learning-hub/copilot-workshops/app/2-add-star-rating/ +[ex3]: /learning-hub/copilot-workshops/app/3-custom-instructions/ +[ex4]: /learning-hub/copilot-workshops/app/4-build-filtering/ +[ex5]: /learning-hub/copilot-workshops/app/5-mcp-playwright/ +[ex6]: /learning-hub/copilot-workshops/app/6-agent-merge/ +[ex7]: /learning-hub/copilot-workshops/app/7-canvases/ +[ex8]: /learning-hub/copilot-workshops/app/8-review/ +[install-git]: https://github.com/git-guides/install-git +[callout-student-plan-education]: https://github.com/education/students diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/0-prerequisites.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/0-prerequisites.md new file mode 100644 index 00000000..1d7479ef --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/0-prerequisites.md @@ -0,0 +1,70 @@ +--- +title: "Exercise 0: Prerequisites" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Before you start the Copilot CLI exercises, you need to get everything ready. You'll create your own copy of the Tailspin Toys repository and spin up a [codespace][codespaces], whose integrated terminal you'll use to install and run Copilot CLI in the next exercise. + +## Setting up the lab repository + +To create a copy of the repository for the code you'll create, you'll make an instance from the [template][template-repository]. The new instance will contain all of the necessary files for the lab, and you'll use it as you work through the exercises. + +1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/tailspin-toys`. +2. Create your own copy of the repository by selecting the **Use this template** button on the lab repository page. Then select **Create a new repository**. + + ![Use this template button](/images/learning-hub/copilot-workshops/ex0-use-template.png) + +3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to GitHub Copilot. + + ![Input the repository template settings](/images/learning-hub/copilot-workshops/ex0-repository-settings.png) + +4. Make a note of the repository path you created (**organization-or-user-name/repository-name**), as you will be referring to this later in the lab. + +> [!NOTE] +> **Your backlog is ready** +> +> When you create your repository from the template, a backlog of GitHub issues is created for you automatically. You'll work from these issues throughout the workshop — there's nothing to file yourself. +## Creating a codespace + +Next up, you'll use a codespace to complete the lab exercises. + +[GitHub Codespaces][codespaces] are a cloud-based development environment that allows you to write, run, and debug code directly in your browser. It provides a fully-featured IDE with support for multiple programming languages, extensions, and tools. + +1. Navigate to your newly created repository. +2. Select the green **Code** button. + + ![Select the Code button](/images/learning-hub/copilot-workshops/ex0-code-button.png) + +3. Select the **Codespaces** tab and select the **+** button to create a new Codespace. + + ![Create a new codespace](/images/learning-hub/copilot-workshops/ex0-create-codespace.png) + +The creation of the codespace will take several minutes, although it's still far quicker than having to manually install all the services! That said, you can use this time to explore other features of GitHub Copilot, which we'll turn your attention to next. + +> [!CAUTION] +> You'll return to the codespace in a future exercise. For the time being, leave it open in a tab in your browser. + +> [!NOTE] +> This workshop is built to run inside a codespace or local [dev container][dev-containers]. Both ensure the environment has all the necessary prerequisites installed for a smooth experience. If you'd prefer to run it locally, open the cloned repository in VS Code and select **Reopen in Container** when prompted — VS Code will build the same dev container the codespace uses. + +## Summary + +Congratulations, you have created a copy of the lab repository! You also began the creation process of your codespace, which you'll use when you begin working with Copilot CLI. + +## Next step + +Let's install Copilot CLI and authenticate it with your GitHub account. Continue to [Exercise 1 - Installing GitHub Copilot CLI][next-lesson]. + +## Resources + +- [GitHub Codespaces overview][codespaces] +- [Creating a repository from a template][template-repository] +- [Getting started with Codespaces][codespaces-quickstart] + +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[codespaces-quickstart]: https://docs.github.com/codespaces/getting-started/quickstart +[next-lesson]: /learning-hub/copilot-workshops/cli/1-install-copilot-cli/ +[codespaces]: https://github.com/features/codespaces +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/1-install-copilot-cli.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/1-install-copilot-cli.md new file mode 100644 index 00000000..14651698 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/1-install-copilot-cli.md @@ -0,0 +1,129 @@ +--- +title: "Exercise 1 - Installing GitHub Copilot CLI" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[GitHub Copilot CLI][about-copilot-cli] is a powerful agentic coding assistant that runs in your terminal, enabling you to explore codebases, generate code, run commands, and interact with external tools - all from the command line. It allows you to offload tasks, request changes, and stay in the zone. The first step, as you might imagine, is to install the tool! Fortunately this can be done using tools you're already familiar with. + +In this exercise, you will learn how to: + +- install GitHub Copilot CLI using npm. +- authenticate with your GitHub account. +- verify the installation. + +## Scenario + +Your team is starting to use AI agents to work through a growing backlog. Copilot CLI brings that capability into the terminal, where many developers already live. This exercise gets you installed, authenticated, and ready to use it for the rest of the workshop. + +## Open a terminal in your codespace + +Before installing Copilot CLI, you need to open a terminal window in your codespace. + +1. Return to your codespace if you're not already there. +2. Open a terminal window by pressing Ctrl+\`. +3. You should see a terminal panel appear at the bottom of your VS Code window. + +## Install Copilot CLI + +You can install Copilot CLI through [npm][install-npm], [WinGet][install-winget], and [Homebrew][install-homebrew]. Since GitHub Codespaces come with Node.js pre-installed you'll use npm to install Copilot CLI. + +1. In the terminal, verify Node.js is installed and meets the version requirement: + + ```bash + node --version + ``` + + You should see version 22 or higher (e.g., `v22.x.x`). + +2. Install Copilot CLI globally in the codespace using npm: + + ```bash + npm install -g @github/copilot + ``` + +3. Verify the installation by checking the version: + + ```bash + copilot --version + ``` + + You should see the version number displayed (e.g., `v1.0.XX`). + +> [!TIP] +> If you encounter permission errors, you may need to use `sudo npm install -g @github/copilot` on some systems. However, this shouldn't be necessary in GitHub Codespaces. + +## Authenticate with GitHub + +On first launch, Copilot CLI will prompt you to authenticate with your GitHub account. + +1. Start Copilot CLI: + + ```bash + copilot + ``` + +2. If you're not currently logged in, you'll see a prompt to authenticate. Copilot CLI will display a device code and ask you to visit a URL. +3. Follow the on-screen instructions: + - Open the provided URL in your browser + - Enter the device code when prompted + - Authorize Copilot CLI to access your GitHub account +4. Once authenticated, you'll see the Copilot CLI prompt, ready to accept your questions and commands. + +> [!NOTE] +> In a codespace, you may already be authenticated through your GitHub session. If Copilot CLI starts without prompting for authentication, you're good to go! + +## Trust the directory and verify everything is working + +Now that you're at the Copilot CLI prompt for the first time, let's trust this workshop repository and make sure Copilot CLI is properly installed and connected. + +1. When Copilot CLI asks you to confirm that you trust the files in this folder, you'll see three options: + - **Yes, proceed**: Trust for this session only + - **Yes, and remember this folder for future sessions**: Trust permanently + - **No, exit (Esc)**: Don't allow file access +2. For this workshop, select **Yes, and remember this folder for future sessions** since you'll be working in this repository throughout. +3. Ask Copilot a simple question to verify it's working: + + ``` + What files are in this project? + ``` + +4. Copilot should explore the repository and provide a summary of the project structure. +5. Try the `/help` command to see available slash commands: + + ``` + /help + ``` + +6. Exit Copilot CLI by entering the following command in the terminal. We will return back to Copilot CLI in a future exercise! + + ``` + exit + ``` + +## Summary and next steps + +Congratulations! You've successfully installed and authenticated GitHub Copilot CLI. You learned how to: + +- install Copilot CLI using npm. +- authenticate with your GitHub account. +- trust a directory for Copilot CLI to work with. +- verify the installation is working correctly. + +Now that Copilot CLI is installed, let's give Copilot some project context. Continue to [Exercise 2 - Custom instructions with CLI][next-lesson]. + +## Resources + +- [Installing GitHub Copilot CLI][install-copilot-cli] +- [About Copilot CLI][about-copilot-cli] +- [Using Copilot CLI][using-copilot-cli] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/0-prerequisites/ +[next-lesson]: /learning-hub/copilot-workshops/cli/2-custom-instructions/ +[install-copilot-cli]: https://docs.github.com/copilot/how-tos/set-up/install-copilot-cli +[install-npm]: https://docs.github.com/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli#installing-with-npm-all-platforms +[install-winget]: https://docs.github.com/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli#installing-with-winget-windows +[install-homebrew]: https://docs.github.com/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli#installing-with-homebrew-macos-and-linux +[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli +[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/2-custom-instructions.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/2-custom-instructions.md new file mode 100644 index 00000000..2a11c317 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/2-custom-instructions.md @@ -0,0 +1,229 @@ +--- +title: "Exercise 2 - Custom instructions (Copilot CLI)" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[← Previous lesson: Installing Copilot CLI][previous-lesson] · [Next lesson: Generating code with CLI →][next-lesson] + +Context is key when working with generative AI. If a task needs to be done a particular way — or there's background information Copilot should know — you want to make sure that context is available. There are several tools available to you to help Copilot, which we'll explore throughout this workshop. We're going to start with [instruction files][instruction-files], which are typically focused on how the code itself should be structured. This helps Copilot understand not just *what* code you want but *how* it should be structured. + +In this exercise, you will: + +- explore how project-specific context, coding guidelines, and documentation standards reach Copilot through repository custom instructions and path-scoped instruction files, +- generate the first data slice for filtering (a publishers helper) with the *current* instructions in place, +- add a new repository-wide standard to `.github/copilot-instructions.md`, +- run a follow-up prompt and watch the regenerated code adopt the new standard, +- commit the instruction updates and helper so the next exercise can build on them. + +> [!CAUTION] +> Generated code may diverge from some of the standards you set. Copilot is non-deterministic. The goal is to see the *trend* in behavior change after updating the instructions, not to match output character-for-character. + +## Instruction files + +### Scenario + +As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include: + +- The data layer always needs unit tests. +- UI should be in dark mode and have a modern feel. +- Documentation should be added to code in the form of TSDoc doc comments. +- A block of comments should be added to the head of each file describing what the file does. + +Through the use of instruction files you'll ensure Copilot has the right information to perform the tasks in alignment with the practices highlighted. + +### Custom instructions + +Custom instructions allow you to provide context and preferences to Copilot, so that it can better understand your coding style and requirements. This is a powerful feature that can help you steer Copilot to get more relevant suggestions and code snippets. You can specify your preferred coding conventions, libraries, and even the types of comments you like to include in your code. You can create instructions for your entire repository, or for specific types of files for task-level context. + +There are two types of instructions files: + +- `.github/copilot-instructions.md`, a single instruction file sent to Copilot for **every** request for the repository. This file should contain project-level information — context relevant for most chat or CLI requests sent to Copilot. This could include the tech stack being used, an overview of what's being built, best practices, and other global guidance. +- `.github/instructions/*.instructions.md` files can be created for specific tasks or file types. You can use them to provide guidelines for particular languages (like TypeScript or Astro), or for tasks like creating a UI component or a new set of unit tests. + +> [!NOTE] +> When working in your IDE, instructions files are only used for code generation in Copilot Chat — not for code completions or next-edit suggestions. +> +> Copilot Chat, Copilot CLI and Copilot cloud agent use both repository-level and `*.instructions.md` files (with `applyTo` front matter) when generating code. +> +> Finally, Copilot [supports instructions files using other standards][custom-instructions-support], including AGENTS.md and CLAUDE.md files. + +### Best practices for managing instructions files + +A full conversation about creating instructions files is beyond the scope of the workshop. However, the examples provided in the sample project show a representative approach. At a high level: + +- Keep instructions in `copilot-instructions.md` focused on project-level guidance, such as a description of what's being built, the structure of the project, and global coding standards. +- Use `*.instructions.md` files to provide specific instructions for file types (unit tests, Astro components, the data layer), or for specific tasks. +- Use natural language. Keep guidance clear. Provide examples of how code should (and shouldn't) look. + +There isn't one specific way to create instructions files, just as there isn't one specific way to use AI. You will find through experimentation what works best for your project. + +> [!TIP] +> Every project using GitHub Copilot should have a robust collection of instruction files. As you explore the ones in this project, you may notice there are files for numerous types of tasks, including [UI updates][ui-instructions] and [Astro][astro-instructions]. +> +> Copilot can also help generate instruction files for you. Each surface exposes this differently (for example, **Configure Chat → Generate Agent Instructions** in VS Code, or `/init` in Copilot CLI) — the lesson for the surface you're on will call it out where it's relevant. +> +> Looking for templates or a starting point? Explore [awesome-copilot][awesome-copilot], a repository full of instruction files, custom agents, and other resources. + +## Explore the custom instructions files in this project + +Take a moment to read the instruction files this repository ships with — there's one core `copilot-instructions.md` and a collection of `*.instructions.md` files for various tasks. Open these in your editor or the GitHub web UI. + +1. Open `.github/copilot-instructions.md`. +2. Explore the file, noting the brief description of the project plus sections such as **Agent notes**, **Code standards**, **Scripts**, and **Repository Structure**. Under **Code standards**, note the nested **GitHub Actions Workflows** guidance. These are applicable to any interactions you'd have with Copilot. +3. Open the `.github/instructions` folder and look around. Note there are instructions for Astro files, the Drizzle data layer, tests, and more. +4. Open `.github/instructions/unit-tests.instructions.md`. Note the `applyTo` field at the top — this sets a glob (relative to the repo root) that determines which files the instructions apply to. Here, any TypeScript test file (for example, one matching `**/*.test.ts`) will match. +5. Note the instructions specific to creating unit tests for this project. +6. Finally, open `.github/instructions/drizzle.instructions.md` and scroll to the bottom. Note the links to other instruction files (like `unit-tests.instructions.md`) and existing files in the project. This lets you break larger instruction sets into smaller, reusable files, and point Copilot at examples to follow when generating code. (Paths there are relative to the instruction file rather than the repo root.) + +> [!NOTE] +> The **Code formatting requirements** section in `copilot-instructions.md` documents the project's coding standards, but it doesn't yet require in-code documentation. In the next steps, you'll add rules for TSDoc doc comments and file comment headers. +## Create a branch + +You'll be making code changes, so create a branch to work in. + +1. From your codespace terminal, create and switch to a new branch: + + ```bash + git checkout -b update-custom-instructions + ``` + +2. Confirm Copilot CLI is installed and authenticated: + + ```bash + copilot --version + ``` + + If the command isn't found or you haven't logged in, return to [Exercise 1 - Installing GitHub Copilot CLI](/learning-hub/copilot-workshops/cli/1-install-copilot-cli/). + +## Use Copilot CLI *before* updating the instructions + +To see the impact of custom instructions, start by generating code with the current instructions in place. Later, you'll update the file and run a follow-up prompt. + +> [!CAUTION] +> `--yolo` enables full automatic permissions (`--allow-all-tools`, `--allow-all-paths`, and `--allow-all-urls`). Use it only in an isolated environment like a Codespace or VM, and never alias it as your default for day-to-day development. See [Allowing and denying tool use][allow-all-warning] for details. + +Running Copilot CLI from the **repository root** ensures it picks up `.github/copilot-instructions.md` automatically. `--enable-all-github-mcp-tools` turns on the read/write GitHub MCP tools so Copilot can read your backlog and open pull requests later in the workshop. + +1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. +2. Return to your open Copilot CLI session. If the terminal is closed or you exited Copilot CLI, open a terminal by selecting Ctrl+\`, then start it from the repository root by running `copilot --yolo --enable-all-github-mcp-tools`. Trust the project folder if prompted, then run `/models` and select **Auto**. +3. At the Copilot CLI prompt, ask it to generate the publishers helper that the filtering UI will use: + + ```plaintext + Create a new data-access helper at src/lib/publishers.ts to return a list of all publishers. It should return the name and id for all publishers. Do not run the tests yet. + ``` + +4. Copilot CLI will explore the project, propose a plan, and write the file in this `--yolo` session. Monitor the changes in your terminal output, then review in your editor. +5. Open the generated `src/lib/publishers.ts` in your editor. +6. Notice the helper is a typed function that takes a `db` client as its first argument and returns a typed array of publishers — that's coming from the data-layer conventions in `.github/instructions/drizzle.instructions.md` (which applies to `src/lib/*.ts`). +7. Notice the generated code **is missing** TSDoc doc comments and a file-level comment header. + +> [!CAUTION] +> Copilot is probabilistic — there's a chance it'll add doc comments even without being told. If that happens, that's fine; the *consistency* improvement after the instruction update is still the takeaway. + +## Add a new repository standard + +As highlighted previously, `.github/copilot-instructions.md` is designed to provide project-level information to Copilot. Let's ensure repository coding standards are documented to improve code suggestions. + +1. Re-open `.github/copilot-instructions.md`. +2. Locate the **Code formatting requirements** section, which should be near line 27. Note how it documents the project's coding standards — but it has no rule yet for in-code documentation, which is why the generated helper had no doc comments. +3. Add the following lines of markdown right below the existing standards to instruct Copilot to add file comment headers and TSDoc doc comments: + + ```markdown + - Every exported function should have a TSDoc comment describing its purpose, parameters, and return value. + - Before imports or any code, add a comment block to the file that explains its purpose. + ``` + +4. Save `copilot-instructions.md`. + +> [!TIP] +> As you saw in the previous lesson, instruction files can be created at the repository level (`.github/copilot-instructions.md`) for global guidance, or as `*.instructions.md` files for specific languages, file types, or tasks. The repository-level file is the right home for project-wide standards like the doc comment rule you just added. +## Re-run the prompt and observe the change + +Now that the instructions have a doc comment rule, ask Copilot CLI to update the publishers file you just generated. The same standards directive will steer the rewrite. + +1. Send `/clear` in your Copilot CLI session to start with a clean conversation. +2. Send the following prompt: + + ```plaintext + Update src/lib/publishers.ts to follow the latest documentation conventions in .github/copilot-instructions.md. + ``` + +3. Let the edit complete, then reopen `src/lib/publishers.ts`. +4. Notice that the file now opens with a comment block similar to: + + ```typescript + /** + * Publisher data-access helpers for the Tailspin Toys Crowd Funding platform. + * Provides functions to retrieve publisher information from the database. + */ + ``` + +5. Notice that the generated function now includes a TSDoc comment similar to: + + ```typescript + /** + * Returns a list of all publishers with their id and name. + * + * @param db - The Drizzle database client. + * @returns A promise that resolves to an array of publisher objects. + */ + ``` + +6. Keep this updated file in place. It's the first data slice you'll build on in the next exercise. + +## Commit and push this first filtering slice + +1. In your terminal, verify the changed files: + + ```bash + git status + ``` + +2. Stage the instruction update and the helper: + + ```bash + git add .github/copilot-instructions.md src/lib/publishers.ts + ``` + +3. Commit the changes: + + ```bash + git commit -m "Add doc comment standards and publishers helper foundation" + ``` + +4. Push the branch: + + ```bash + git push -u origin update-custom-instructions + ``` + +## Summary and next steps + +You explored how Copilot picks up context from instruction files in this project, then used Copilot CLI to: + +- generate a publishers data-access helper foundation for filtering with the *existing* instructions, +- add a new repository-wide standard to `.github/copilot-instructions.md`, +- run a follow-up prompt and watch the regenerated code adopt the new standard, +- commit and push both the instructions update and the helper foundation. + +Next, you'll apply these instructions while implementing backlog work in [the generating-code exercise][next-lesson]. + +## Resources + +- [Instruction files for GitHub Copilot customization][instruction-files] +- [Best practices for creating custom instructions][instructions-best-practices] +- [5 tips for writing better custom instructions for Copilot][copilot-instructions-five-tips] +- [Awesome Copilot — a collection of instruction files and other resources][awesome-copilot] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/1-install-copilot-cli/ +[next-lesson]: /learning-hub/copilot-workshops/cli/3-generating-code/ +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[copilot-instructions-five-tips]: https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/ +[allow-all-warning]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[awesome-copilot]: https://github.com/github/awesome-copilot +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/3-generating-code.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/3-generating-code.md new file mode 100644 index 00000000..6e5dfc69 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/3-generating-code.md @@ -0,0 +1,83 @@ +--- +title: "Exercise 3 - Adding project features with GitHub Copilot CLI" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +As you might expect, the core tasks you'll perform with GitHub Copilot CLI is to add features, functionality, and code to a project. Let's take one of the issues from your backlog and ask Copilot to help us implement it. + +## Scenario + +The time has come to complete filtering in the project. You already have the filtering issue in your backlog and a foundation helper from the previous exercise. Let's have Copilot retrieve the issue details, account for existing work, and build the remaining functionality. + +In this exercise, you will: + +- utilize plan mode to generate a plan for implementing the filtering functionality. +- generate the code necessary to add filtering to the website with Copilot. + +By the end of this exercise, you will have added new functionality to the project. + +## Utilize plan mode + +One of the best uses of AI is planning. Oftentimes you'll have a good concept of what you want to build, but just need to bounce some ideas off of something. AI tools can help you crystalize your thoughts by asking you follow up questions and working through different pitfalls or missing components. To support this process, Copilot CLI offers a plan mode. Additionally, that time you spend planning will help Copilot generate code that best matches the requirements set forth. + +You'll start the process of creating the new functionality by utilizing plan mode in Copilot CLI. + +1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. +2. Return to your open Copilot CLI session. If the terminal is closed or you exited Copilot CLI, open a terminal by selecting Ctrl+\`, then start it from the repository root by running `copilot --yolo --enable-all-github-mcp-tools`. Trust the project folder if prompted, then run `/models` and select **Auto**. +3. Enter the following prompt into Copilot CLI to create a plan based on the filtering issue: + + ``` + /plan Retrieve the issue on the repository related to adding filtering. We already added a publishers helper in src/lib/publishers.ts, so treat that as existing work and plan the remaining updates (games filtering logic, UI, and tests). + ``` + +4. Copilot may ask follow-up questions as it builds out its plan. As those arise, answer them based on how you'd build out the functionality. +5. Once the plan is generated, review the blueprint. You should notice it recommends remaining changes across the data layer and UI, as well as generating tests. +6. Copilot CLI will offer you the ability to provide additional feedback to the plan. You can cursor down to the indicated section, then type your suggestions. Copilot will incorporate your suggestions into a new version of the plan. +7. Once you're satisfied, select the option provided by Copilot to begin work building the new feature! + +> [!NOTE] +> Because Copilot is probabilistic, the exact text and options provided will vary. But you will notice an option to begin building that will read something similar to: +> +> `Yes, and switch to autopilot mode`. +> +> Copilot may offer you the option to enable [autopilot mode](https://docs.github.com/copilot/concepts/agents/copilot-cli/autopilot), as shown in the example above. Autopilot mode allows Copilot CLI to work through a task without waiting for your input after each step. Once you give the initial instruction, Copilot CLI works through each step autonomously until it determines the task is complete. As we are running in a contained environment, we're OK running autopilot and allowing all tools. + +8. Copilot will get to work generating the files! + +> [!NOTE] +> This operation will likely take several minutes. You will see Copilot edit and create files, update and generate tests, and run all of the tests to ensure everything succeeds. Now's a good time to reflect on what you've explored thus far, or to enjoy a beverage. + +## Review the code + +All AI code needs to be reviewed before being merged into production. Let's take the time now to explore the files Copilot created and modified in implementing the new feature. + +1. Use Copilot CLI to display the "diff" or code changes by using the following command in Copilot CLI: + + ``` + /diff + ``` + +2. Note the files changed. Use your arrow keys to switch left and right to view the different files. You should see updates to files such as the games listing page (where the new filter controls and client-side filtering live) and `src/lib/games.ts`, plus tests like `games.test.ts`. You may also see updates to `publishers.ts` if Copilot refines your existing helper to align with the full implementation. + +## Summary and next steps + +You've now added filtering functionality to the website with the help of Copilot CLI! Specifically, you: + +- utilized plan mode to generate a plan for implementing the filtering functionality. +- generated the code necessary to add filtering to the website with Copilot. + +Of course, the next step from here is to make sure it works. Let's [test your feature with the Playwright MCP server][next-lesson] before we open a pull request. + +## Resources + +- [Using Copilot CLI][using-copilot-cli] +- [About Copilot CLI][about-copilot-cli] +- [Context management in Copilot CLI][context-management] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/2-custom-instructions/ +[next-lesson]: /learning-hub/copilot-workshops/cli/4-mcp/ +[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli +[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli +[context-management]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#context-management diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/4-mcp.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/4-mcp.md new file mode 100644 index 00000000..ce3d56c1 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/4-mcp.md @@ -0,0 +1,143 @@ +--- +title: "Exercise 4 - Testing your feature with the Playwright MCP server" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +You just generated the filtering feature with Copilot CLI. Before you open a pull request, you should confirm it works in the browser. Rather than click through the app yourself, you'll connect the **Playwright MCP server** and let Copilot drive a real browser to test the feature for you. + +In this exercise, you will: + +- understand what Model Context Protocol (MCP) is and how MCP servers extend Copilot CLI. +- add the Playwright MCP server to Copilot CLI. +- ask Copilot to use it to manually test your filtering feature in a browser. + +## What is Model Context Protocol (MCP)? + +[Model Context Protocol (MCP)](https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/) provides AI agents with a way to communicate with external tools and services. By using MCP, AI agents can communicate with external tools and services in real-time. This allows them to access up-to-date information (using resources) and perform actions on your behalf (using tools). + +These tools and resources are accessed through an MCP server, which acts as a bridge between the AI agent and the external tools and services. The MCP server is responsible for managing the communication between the AI agent and the external tools (such as existing APIs or local tools like NPM packages). Each MCP server represents a different set of tools and resources that the AI agent can access. + +A couple of popular existing MCP servers are: + +- **[GitHub MCP Server](https://github.com/github/github-mcp-server)**: This server provides access to a set of APIs for managing your GitHub repositories. It allows the AI agent to perform actions such as creating new repositories, updating existing ones, and managing issues and pull requests. +- **[Playwright MCP Server](https://github.com/microsoft/playwright-mcp)**: This server provides browser automation capabilities using Playwright. It allows the AI agent to perform actions such as navigating to web pages, filling out forms, and clicking buttons. + +There are many other MCP servers available that provide access to different tools and resources. GitHub hosts an [MCP registry](https://github.com/mcp) to enhance discoverability and contributions to the ecosystem. + +> [!CAUTION] +> With regard to security, treat MCP servers as you would any other dependency in your project. Before using an MCP server, carefully review its source code, verify the publisher, and consider the security implications. Only use MCP servers that you trust and be cautious about granting access to sensitive resources or operations. + +> [!NOTE] +> The [GitHub MCP server][github-mcp-server] is **built in** to Copilot CLI — it's already available without any setup, which is how Copilot has been reading and writing to your repository throughout the workshop. In this exercise you'll add a *second* server, Playwright, to give Copilot a browser. + +## Add the Playwright MCP server + +The quickest way to add a server is the interactive `/mcp add` command. You'll register the [Playwright MCP server][playwright-mcp-server], which gives Copilot a browser it can control. + +1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. +2. Return to your open Copilot CLI session. If the terminal is closed or you exited Copilot CLI, open a terminal by selecting Ctrl+\`, then start it from the repository root by running `copilot --yolo --enable-all-github-mcp-tools`. Trust the project folder if prompted, then run `/models` and select **Auto**. +3. In your Copilot CLI session, enter: + + ```text + /mcp add + ``` + +4. A configuration form appears. Use Tab to move between fields and fill it in as follows: + + - **Server Name**: `playwright` + - **Server Type**: select **Local** (also labelled **STDIO**) + - **Command**: `npx @playwright/mcp@latest --headless` + - **Tools**: leave as `*` to allow all of the server's tools + +5. Press Ctrl+S to save. The server is added and available immediately — no restart required. + +The `--headless` flag tells Playwright to run the browser without a visible window, which is required inside a codespace where there's no desktop to display it. Behind the scenes, this writes the server to your `~/.copilot/mcp-config.json` file: + +```json +{ + "mcpServers": { + "playwright": { + "type": "local", + "command": "npx", + "args": ["@playwright/mcp@latest", "--headless"], + "tools": ["*"] + } + } +} +``` + +6. Confirm the server is registered and active by listing your MCP servers: + + ```text + /mcp show + ``` + +7. You should see `playwright` listed alongside the built-in `github` server. + +> [!NOTE] +> The Tailspin Toys project already uses Playwright for its end-to-end tests, so the browser Playwright needs is typically already installed. If Copilot later reports that a browser is missing, have it run `npx playwright install chromium` and try again. + +## Start the website + +The Playwright MCP server needs a running app to test against. Start the Astro dev server in a **separate** terminal so it keeps running while you work in Copilot CLI. + +1. Open a new terminal in your codespace by selecting Ctrl+\`. +2. Start the website: + + ```bash + npm run dev + ``` + +3. Leave this terminal running. Once you see the `Astro server: http://localhost:4321` banner, the app is ready. + +## Test the filtering feature + +Return to your Copilot CLI session and ask Copilot to test the feature. + +The [Playwright MCP server][playwright-mcp-server] gives Copilot a real browser to drive. Instead of you clicking through the app to check your work, the agent can open a page, navigate, apply filters, and read the result back to you — then summarize what it saw. It's the fastest way to confirm a feature behaves the way you expect without leaving the conversation. + +Under the hood, the Playwright MCP server works from the page's [accessibility tree][playwright-mcp-server] rather than screenshots. That means the agent reasons over structured, labelled elements (buttons, links, list items) the same way assistive technology does — so a quick functional check doubles as a light accessibility sanity check. + +With the server connected and the app running, ask Copilot to exercise the filtering feature you just built: + +```text +Using the Playwright MCP server, open a browser to the running app at http://localhost:4321 and verify the new game filtering feature: + +1. Go to the games page and note how many games are listed. +2. Apply a category filter and confirm the list updates to only show games in that category. +3. Clear it, then apply a publisher filter and confirm the list updates to that publisher. +4. Combine a category and a publisher filter and confirm the results respect both. + +Report what you observe at each step, and call out anything that does not behave as expected. +``` + +Copilot will launch a browser through the Playwright MCP server, walk through each step, and report back what it found. Read its summary against the acceptance criteria in the issue — if something looks off, ask follow-up questions or send it back to fix the code before you open a pull request. + +> [!NOTE] +> The app needs to be running at `http://localhost:4321` for this test. If you stopped the dev server, start it again before sending the prompt. The first time Copilot uses the Playwright MCP server it may need to download a browser — if it reports a missing browser, have it run `npx playwright install chromium` and try again. + +## Summary and next steps + +Congratulations, you used the Playwright MCP server to manually test your feature with Copilot CLI! To recap, you: + +- learned what Model Context Protocol (MCP) is and how MCP servers extend Copilot CLI. +- added the Playwright MCP server with `/mcp add`. +- asked Copilot to drive a browser and verify your filtering feature before shipping it. + +Now that you've confirmed the feature works, you can continue to the next exercise, where you'll [open a pull request with the help of an agent skill][next-lesson]. + +## Resources + +- [What the heck is MCP and why is everyone talking about it?][mcp-blog-post] +- [Microsoft Playwright MCP Server][playwright-mcp-server] +- [Adding MCP servers for Copilot CLI][cli-add-mcp] +- [GitHub MCP Server][github-mcp-server] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/3-generating-code/ +[next-lesson]: /learning-hub/copilot-workshops/cli/5-agent-skills/ +[mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/ +[github-mcp-server]: https://github.com/github/github-mcp-server +[cli-add-mcp]: https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers +[playwright-mcp-server]: https://github.com/microsoft/playwright-mcp diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/5-agent-skills.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/5-agent-skills.md new file mode 100644 index 00000000..3b565a23 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/5-agent-skills.md @@ -0,0 +1,105 @@ +--- +title: "Exercise 5 - Using agent skills" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Doing app development often involves repeatable tasks like generating builds, running tests, or creating pull requests. **Agent skills** let you give Copilot — and other AI agents — guidance on how to perform those tasks. A skill is a folder of instructions, scripts, and resources that the agent can load on demand. [Agent Skills is an open standard][agent-skills-repo] used by a range of agents, so the same skill can work across Copilot Chat in agent mode, Copilot cloud agent, Copilot CLI, and the GitHub Copilot app. + +Let's explore how a skill can ensure pull requests follow the specifications set forth by our team. + +## Scenario + +The team has a set of requirements for pull requests (PR): + +- clear commit messages, with files grouped logically. +- all tests must pass before a PR is created. +- each PR must contain the following sections: + - a description of why the changes were made. + - an overview of the files changed. + - snippets of important code blocks. + - details of the changes made grouped together. + +As the team is using Copilot to generate code and PRs, it wants to ensure the AI tools follow these requirements. + +In this exercise you will: + +- explore an existing skill for creating pull requests. +- learn how skills are utilized by the AI agent. +- create a PR which matches the guidelines with the help of the skill. + +## Creating agent skills + +Skills live in the `.github/skills` folder of a project, or globally in `~/.copilot/skills`. Each skill is a folder containing a `SKILL.md` file with YAML frontmatter (a `name` and a `description`) followed by the markdown instructions: + +```yaml +--- +name: make-contribution +description: All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly. +--- +``` + +Skills can also include subfolders with scripts, assets, and reference material. The full structure is covered in the [agent skills specification][agent-skills-spec]. + +> [!TIP] +> Skills are loaded dynamically. The agent decides which skill applies based on the `description` field — a clear, scenario-specific description is the difference between a skill that gets used and one that gets ignored. + +## Executing skills + +Skills are loaded dynamically when the agent determines they're necessary. The decision of what skills to use is driven by the description in the `SKILL.md` file. As such, it's important to have clear descriptions which define the use case for the skill. + +## Exploring the PR skill + +Because Tailspin Toys has a set of requirements for creating PRs, they created a skill to help AI tools be able to generate PRs which follow these guidelines. Let's explore the skill to understand what it'll do. + +1. Open `.github/skills/make-contribution/SKILL.md`. +2. Note the name and description. Notice how the description highlights the scenario in which it should be used, which is whenever a request is made to create a pull request or committing code. +3. Read through the skill. Notice the rules are defined about how branches should be created, commits generated, and the contents of the pull request. + +## Using the skill + +As highlighted previously, skills are automatically invoked by Copilot CLI. As a result, all we need to do is ask Copilot to create a PR! + +1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. +2. Return to your open Copilot CLI session. If the terminal is closed or you exited Copilot CLI, open a terminal by selecting Ctrl+\`, then start it from the repository root by running `copilot --yolo --enable-all-github-mcp-tools`. Trust the project folder if prompted, then run `/models` and select **Auto**. +3. Ask Copilot to create a PR by using the following prompt: + + ``` + Can you please create a pull request for me! + ``` + +4. Copilot will acknowledge the request. After a few moments, you'll notice Copilot will indicate it's utilizing the **make-contribution** skill. +5. Copilot will then follow the instructions in the skill. It will start by running the tests, then create a branch, commits, and eventually the PR. +6. Once the PR is created, return to your repository and open the PR. Note the sections follow the guidelines set forth in the skill, matching the requirements the team put forth. +7. Before moving to the next exercise, reset your local workspace to a fresh branch from `main` so your accessibility work stays separate from this filtering PR: + + ```bash + git checkout main + git pull + git checkout -b accessibility-cli + ``` + +## Summary and next steps + +With the help of an agent skill, you created a new PR which matches documented requirements! You: + +- explored an existing skill for creating pull requests. +- learned how skills are utilized by the AI agent. +- created a PR which matches the guidelines with the help of the skill. + +Skills are perfect for tasks, but for more robust operations we want to take advantage of [custom agents][next-lesson], which we'll explore next! + +## Resources + +- [About Agent Skills][about-agent-skills] +- [Agent Skills Specification][agent-skills-spec] +- [Agent Skills Repository][agent-skills-repo] +- [Agent Skills on awesome-copilot][awesome-copilot-skills] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/4-mcp/ +[next-lesson]: /learning-hub/copilot-workshops/cli/6-custom-agents/ +[about-agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[awesome-copilot-skills]: https://github.com/github/awesome-copilot/tree/main/skills +[agent-skills-repo]: https://github.com/agentskills/agentskills +[agent-skills-spec]: https://agentskills.io/specification diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/6-custom-agents.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/6-custom-agents.md new file mode 100644 index 00000000..9ebe9687 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/6-custom-agents.md @@ -0,0 +1,97 @@ +--- +title: "Exercise 6 - Custom agents with GitHub Copilot CLI" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +## What are custom agents? + +[Custom agents][custom-agents-concept] in GitHub Copilot allow you to create specialized AI assistants tailored to specific tasks or domains within your development workflow. By defining agents through markdown files in the `.github/agents` folder of your repository, you can provide Copilot with focused instructions, best practices, coding patterns, and domain-specific knowledge that guide it to perform particular types of work more effectively. Teams can codify their expertise into reusable agents — an accessibility agent that enforces [WCAG][wcag] compliance, a security agent that follows secure coding practices, or a testing agent that maintains consistent test patterns. + +Custom agents are defined by markdown files in the `.github/agents` folder of your project, or globally in `~/.copilot/agents`. Each file has YAML frontmatter with at least a `name` and `description`, followed by a markdown prompt that defines the agent's behavior, expertise, and instructions. + +### Custom agents compared with agent skills + +There's some logical overlap between custom agents and [agent skills][agent-skills-concept]. Both are primarily defined with markdown files and tell an AI how to perform operations. The cleanest way to separate them: a **custom agent** is the worker, and **skills** are tools. + +Custom agents have their own context window and are built to orchestrate skills (and even other agents) as part of doing their work. In this lab, the accessibility custom agent reviews and updates the site against accessibility guidelines; as part of that work it could call skills such as a pull-request workflow skill or one that runs and manages tests. + +> [!NOTE] +> There's no single "right" way to author a custom agent. As with anything in AI, test and iterate to find what works for your environments and scenarios. + +## Scenario + +Many web applications fall short of being accessible to all users, and the website you're working in is no exception. You'll use a custom agent to identify and resolve accessibility shortcomings. + +Tailspin Toys is committed to ensuring their crowdfunding platform is accessible to all users, regardless of their visual abilities or preferences. Recent user feedback has highlighted that some users find the current dark theme difficult to read due to insufficient contrast between text and background colors. To address this accessibility concern, the design team has requested the implementation of a high-contrast mode that users can toggle on and off. + +Because accessibility is critical, you want to ensure this is implemented as quickly as possible. You're going to utilize a custom agent to generate the functionality. +In this exercise, you will: + +- explore custom agents. +- enable a custom agent and assign it a task using Copilot CLI. + +## Reviewing the accessibility custom agent + +A custom agent has already been created for you for accessibility. Let's review the contents to understand how it will guide Copilot. + +1. Open `.github/agents/accessibility.md`. +2. Note the YAML frontmatter with the `name` and `description` fields. + +> [!CAUTION] +> The frontmatter with `name` and `description` is required for custom agents. + +3. From there, scan and review the next sections which highlight: + - Core responsibilities when generating code for an accessible website. + - Best practices for accessibility. + - Code examples for HTML, CSS, and JavaScript. + - A list of common pitfalls and mistakes. +## Using a custom agent in Copilot CLI + +You can start a custom agent in Copilot CLI by using the `/agent` command. Let's perform an accessibility pass on our website. + +1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. +2. Return to your open Copilot CLI session. If the terminal is closed or you exited Copilot CLI, open a terminal by selecting Ctrl+\`, then start it from the repository root by running `copilot --yolo --enable-all-github-mcp-tools`. Trust the project folder if prompted, then run `/models` and select **Auto**. +3. Bring up the list of agents by typing `/agent` in the prompt window in Copilot CLI and selecting Enter. +4. Select the **Accessibility agent** from the list of available agents. +5. Use the following prompt to ask the accessibility agent to perform a review and generate fixes for the accessibility backlog item: + + ``` + Perform an accessibility review of the site. Pull the related issue down from the repository for details. Implement a high-contrast mode toggle that persists the user's preference across page reloads. Ensure there are e2e tests for any updates made to the project. Then create a PR with the updates. + ``` + +6. Copilot gets to work on the task! It will start by retrieving the issue, then performing the review, generating updates, and finally creating the PR. You should also notice when it creates the PR it utilizes the skill focused on PRs for the project. + +> [!NOTE] +> This process will likely take a few minutes. It's a good time to reflect on everything you've learned, enjoy a beverage, or sneak ahead to the next module which talks about some additional commands available to you in Copilot CLI. + +## Summary and next steps + +This lesson explored [custom agents][custom-agents] in GitHub Copilot, specialized AI assistants tailored to specific tasks and domains. With custom agents you can codify your team's expertise and standards into reusable agents that guide Copilot to perform particular types of work more effectively. + +You explored these concepts: + +- how custom agents are defined. +- using a custom agent in Copilot CLI. + +Next up, let's explore [some slash commands][next-lesson] to learn some additional tricks with Copilot CLI. + +## Resources + +- [Custom agents][custom-agents] +- [Creating custom agents for a repository][creating-custom-agents] +- [Custom agents on awesome-copilot][awesome-copilot-agents] +- [Preparing to use custom agents in your organization][org-custom-agents] +- [Preparing to use custom agents in your enterprise][enterprise-custom-agents] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/5-agent-skills/ +[next-lesson]: /learning-hub/copilot-workshops/cli/7-slash-commands/ +[custom-agents]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents +[creating-custom-agents]: https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/create-custom-agents +[awesome-copilot-agents]: https://github.com/github/awesome-copilot/tree/main/agents +[org-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents +[enterprise-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents +[custom-agents-concept]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[agent-skills-concept]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/7-slash-commands.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/7-slash-commands.md new file mode 100644 index 00000000..57e1b3a1 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/7-slash-commands.md @@ -0,0 +1,161 @@ +--- +title: "Exercise 7 - Slash commands in GitHub Copilot CLI" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Like any good CLI tool, GitHub Copilot CLI includes many slash commands to interact with it. These commands expose advanced functionality, "behind-the-scenes" information, or additional configuration options. You've already explored a couple with `/clear` to clear context and `/mcp` to inspect MCP servers. Let's explore a couple of other powerful ones, including `/context`, `/model`, `/share`, and `/delegate`. + +## Scenario + +You've wrapped the core CLI flows. Now let's look at a few additional capabilities — sharing sessions, switching models, and delegating tasks to [Copilot cloud agent][about-cloud-agent]. + +In this exercise you will use: + +- `/share` to create a GitHub gist to share your session with the team. +- `/context` to see the context Copilot CLI is currently using. +- `/model` to explore the list of available models and select a new one if you so desire. +- `/delegate` to optionally hand off a task to cloud agent. This requires cloud agent, available on Copilot Student, Pro, Pro+, Business, or Enterprise — every plan except Copilot Free. + +## Sharing a session + +Using any tool, including an AI tool, is a skill. Working together as a team, sharing learnings with each other, is the best way to help improve everyone's experience and generate higher quality code. To support this, Copilot CLI provides a `/share` command. The `/share` command can generate a markdown file or GitHub gist with the details of the session, including the prompts used and logic Copilot followed. + +Let's create a GitHub gist we could share with our team. + +1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. +2. Return to your open Copilot CLI session. If the terminal is closed or you exited Copilot CLI, open a terminal by selecting Ctrl+\`, then start it from the repository root by running `copilot --yolo --enable-all-github-mcp-tools`. Trust the project folder if prompted, then run `/model` and select **Auto**. +3. In the prompt window for Copilot CLI, send the following command: + + ``` + /share gist + ``` + +4. In just a couple of moments, Copilot will create a gist and display the link. +5. Copy the link text. +6. In a new browser tab, paste the link to explore the gist. Note how the gist highlights the prompts sent, skills and agents used, Copilot's thought process, and even the code and results from locally run commands. + +The gists and markdown files generated by `/share` can be used for documentation purposes of how code was generated, or to share with your team about how certain actions were performed that generated the desired results from Copilot. + +## Exploring Copilot CLI's context + +When working on larger or more complex tasks you may bump into the maximum context window for the model. The exact size of the window will vary based on the model being used and the version of Copilot CLI. When the context window is maxed out, Copilot CLI will automatically compact it, summarizing information and removing anything it deems isn't relevant to the current task. You can both see the current state of the context and manually compact the context by using slash commands. Let's explore the context window. + +1. In the prompt window for Copilot CLI, send the following command: + + ``` + /context + ``` + +2. In just a couple of moments, Copilot CLI will generate a visual representation of its current context: + + ![Screenshot of context window from Copilot CLI](/images/learning-hub/copilot-workshops/cli-7-context-window.png) + +3. Note the model displayed (which may be different than the one in the image), and the current percentage of tokens used. The rest of the information highlights: + + | Title | Description | + | ------------ | ------------------------------------------------------ | + | System/Tools | Instructions files, file contents and tool definitions | + | Messages | Conversation history between you and Copilot | + | Buffer | Reserved space by Copilot CLI for generating responses | + | Free space | Remaining free space | + +4. Compact the conversation history by sending the following slash command to Copilot CLI: + + ``` + /compact + ``` + +5. Once completed, send the following command to display the current context stats again: + + ``` + /context + ``` + +6. Note the change in context. There might not be a drastic change as the context window is likely relatively small at the moment. + +> [!NOTE] +> Copilot CLI will automatically compact when it becomes full. As it approaches 100% capacity it will display the percentage just above the prompt window. Normally it will compact asynchronously, allowing you to continue interacting with Copilot while it does its work. It may however block a running operation for several seconds while performing its work. + +### Best practices with context + +In most sessions with Copilot context will be managed efficiently by Copilot itself without any specific guidance. However, there may be instances when you decide to manually instruct Copilot to either clear or compact its history: + +- If you are changing to a different part of the application, or to an unrelated task, you can use `/clear` to start new to avoid confusing Copilot with older, unrelated context. +- If you are approaching the maximum context window, you can manually `/compact` your context to control when it happens. + +> [!CAUTION] +> Again, the majority of the time, Copilot will manage its context without direct interaction from you. If you notice Copilot is a bit confused by older information, or are about to switch to an unrelated task, then you might consider using the manual commands. + +## Choosing your model + +Different models have different strengths, and different developers have different preferences. Copilot CLI allows you to list and select the model you wish to use! + +1. Display the list of models by sending the following slash command to Copilot CLI: + + ``` + /model + ``` + +2. Note the list of models. Each model will have both its name and cost-per-request modifier listed next to it. +3. If you wish, select a new model! Or select Esc to exit the model list. + +> [!CAUTION] +> Model selection persists in Copilot CLI. + +## Delegating to cloud agent (optional) + +There are times when you want to keep working in your terminal but hand off a longer-running task to Copilot cloud agent. The `/delegate` command sends the current Copilot CLI session to GitHub.com, where cloud agent picks it up, works asynchronously, and opens a pull request when done. + +> [!NOTE] +> `/delegate` requires cloud agent, available on Copilot Student, Pro, Pro+, Business, or Enterprise — every plan except Copilot Free. If you don't have access, read through this section and skip the hands-on steps. + +1. Clear the current session first so accumulated workshop context isn't delegated: + + ``` + /clear + ``` + +2. Send a small, well-scoped prompt. For example, you could delegate the stretch-goal pagination from your backlog: + + ``` + Implement pagination on the game list page so it shows a fixed number of games per page with Previous and Next controls, and add tests. + ``` + +3. Send the following slash command to hand the session to cloud agent, and confirm the prompt you want to delegate: + + ``` + /delegate + ``` + +4. Open [Copilot agents](https://github.com/copilot/agents) in a browser to monitor progress. +5. You don't need to wait for the pull request to complete in this harness; you can return to it later. If you want to dig deeper into managing asynchronous agent work, continue with the [Cloud agent harness](/learning-hub/copilot-workshops/cloud/). + +## Summary and next steps + +Using slash commands in Copilot CLI allows you to configure it, share sessions, and get internal information about how Copilot's working. In this lesson you used or explored: + +- `/share` to create a GitHub gist to share your session with the team. +- `/context` to see the context Copilot CLI is currently using. +- `/model` to explore the list of available models and select a new one if you so desire. +- Learned about `/delegate` as an optional bridge to cloud agent. + +There are of course more slash commands available, and more to explore with Copilot CLI! Let's close out our journey by [reviewing what we've learned][next-lesson] and some next steps to continue learning. + +## Resources + +- [Using Copilot CLI][using-copilot-cli] +- [About Copilot CLI][about-copilot-cli] +- [Context Management in Copilot CLI][context-management] +- [Share Sessions with Copilot CLI][share-sessions] +- [Selecting Models in Copilot CLI][selecting-models] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/6-custom-agents/ +[next-lesson]: /learning-hub/copilot-workshops/cli/8-review/ +[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli +[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli +[about-cloud-agent]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[context-management]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#context-management +[share-sessions]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#share-sessions +[selecting-models]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#select-an-llm diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/8-review.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/8-review.md new file mode 100644 index 00000000..be763b73 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/8-review.md @@ -0,0 +1,70 @@ +--- +title: "Exercise 8 - Review and Next Steps" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Over the last several exercises, you explored some of the most common use cases for GitHub Copilot CLI, including: + +- interacting with GitHub and other MCP servers. +- using instructions files to guide code generation. +- implementing skills to add tools to the Copilot CLI toolbox. +- calling custom agents for advanced and more complex tasks. +- using slash commands to manage your session, and optionally bridging back to cloud agent via `/delegate`. + +Let's talk about some slash commands, best practices, and next steps. + +## Slash commands + +Copilot CLI has a series of slash commands available to interact with it, including ones which allow you to configure it or see what's going on behind the scenes. You've already used `/clear` to start a new chat which clears the current context, and `/mcp` to inspect and manage MCP servers. Some additional ones you might find helpful are: + +| Command | Description | +| ------------------ | ------------------------------------------------------------- | +| `/add-dir` | Add a directory to the trusted list for Copilot | +| `/clear`, `/new` | Clear the conversation history and start fresh | +| `/compact` | Summarize conversation history to reduce context window usage | +| `/context` | Show context window token usage and visualization | +| `/diff` | Review the changes made in the current directory | +| `/model` | Select AI model to use (Claude Sonnet, GPT-5, etc.) | +| `/plan ` | Create an implementation plan before coding | +| `/review ` | Run code review agent to analyze changes | +| `/delegate` | Delegate task to Copilot cloud agent for async processing | +| `/session` | Show session info and workspace summary | +| `/share` | Share session to markdown file or GitHub gist | +| `/skills` | Manage skills for enhanced capabilities | +| `/usage` | Display session usage metrics and statistics | + +> [!TIP] +> Use `/help` to see the full list of available commands and keyboard shortcuts. + +## Best practices + +When using any AI tool, the underlying infrastructure drives the quality of what you get out. Robust instructions files, custom agents, and agent skills all play a part — you explored each of them in this workshop. [awesome-copilot][awesome-copilot] is a good source of templates, and Copilot itself can scaffold these for you as a starting point. + +Context still matters as much as infrastructure. Clearly describing *what* you want built, *why*, and *how* meaningfully changes the output. If a piece of information would help Copilot, pass it along. + +## Next steps + +The best way to improve your skills with any tool is to keep using the tool! Use it for production code, for hobby code, for the little app you've had in your mind for years but never got around to building. Share your learnings with your team, and learn from your team. And, as always, explore the documentation. + +If you'd like to explore more of the GitHub Copilot ecosystem, check out the [VS Code harness](/learning-hub/copilot-workshops/vscode/) or the [Cloud agent harness](/learning-hub/copilot-workshops/cloud/). + +## Resources + +- [About Copilot CLI][about-copilot-cli] +- [Using Copilot CLI][using-copilot-cli] +- [Awesome Copilot Repository][awesome-copilot] +- [Custom Instructions Guide][repo-instructions] +- [Agent Skills Documentation][agent-skills] +- [Custom Agents Documentation][custom-agents] +- [MCP Specification][mcp-spec] + +[previous-lesson]: /learning-hub/copilot-workshops/cli/7-slash-commands/ +[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli +[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli +[awesome-copilot]: https://github.com/github/awesome-copilot +[repo-instructions]: https://docs.github.com/copilot/how-tos/configure-custom-instructions/add-repository-instructions +[agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[custom-agents]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents +[mcp-spec]: https://modelcontextprotocol.io/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cli/index.md b/website/src/content/docs/learning-hub/copilot-workshops/cli/index.md new file mode 100644 index 00000000..fc874c89 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cli/index.md @@ -0,0 +1,53 @@ +--- +title: "GitHub Copilot CLI" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +**[GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)** puts GitHub Copilot in your terminal as an agentic coding assistant. It explores codebases, generates code, runs commands, and connects to external tools — all from the command line, so you can stay in the flow without switching to a graphical editor. + +Across these exercises you'll install and authenticate Copilot CLI, then give it project context with custom instructions before using plan mode to generate a feature deliberately. You'll connect the Playwright MCP server to test that feature in a real browser, then extend Copilot with reusable agent skills and custom agents. Finally, you'll explore slash commands for managing context, models, and sharing, and wrap up with a review of what you've built. + +## Exercises + +| Exercise | Topic | Description | +|----------|-------|-------------| +| [0. Prerequisites][ex0] | Setup | Create your repository and codespace | +| [1. Installing Copilot CLI][ex1] | Installation | Install and authenticate Copilot CLI | +| [2. Custom instructions][ex2] | Context | Add an instruction and see how Copilot CLI follows it | +| [3. Generating Code][ex3] | Code Generation | Use plan mode and generate features | +| [4. Testing with Playwright MCP][ex4] | External Tools | Add the Playwright MCP server and test your feature in a browser | +| [5. Agent Skills][ex5] | Skills | Enhance Copilot with specialized skills | +| [6. Custom Agents][ex6] | Agents | Review and use custom agents | +| [7. Slash Commands][ex7] | CLI Features | Explore context, models, sharing, and optional delegation to cloud agent | +| [8. Review][ex8] | Summary | Review key concepts and next steps | + +## Prerequisites + +Before attending this workshop, please ensure you have: + +- [ ] A GitHub account with an active **Copilot Student, Pro, Pro+, Business, or Enterprise** plan +- [ ] Basic familiarity with terminal/command line operations +- [ ] Git installed and configured + +> [!TIP] +> No paid plan? Verified students can get GitHub Copilot for free through [GitHub Education][callout-student-plan-education]. The **Copilot Student** plan includes the agent, MCP, code review, and Copilot CLI features this workshop uses — so you can complete every harness with it. + +> [!NOTE] +> If you are using Copilot Business or Copilot Enterprise, ensure your admin has enabled Copilot CLI for use. + +## Get Started + +**[Start with Exercise 0: Prerequisites →][ex0]** + +[ex0]: /learning-hub/copilot-workshops/cli/0-prerequisites/ +[ex1]: /learning-hub/copilot-workshops/cli/1-install-copilot-cli/ +[ex2]: /learning-hub/copilot-workshops/cli/2-custom-instructions/ +[ex3]: /learning-hub/copilot-workshops/cli/3-generating-code/ +[ex4]: /learning-hub/copilot-workshops/cli/4-mcp/ +[ex5]: /learning-hub/copilot-workshops/cli/5-agent-skills/ +[ex6]: /learning-hub/copilot-workshops/cli/6-custom-agents/ +[ex7]: /learning-hub/copilot-workshops/cli/7-slash-commands/ +[ex8]: /learning-hub/copilot-workshops/cli/8-review/ +[callout-student-plan-education]: https://github.com/education/students diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cloud/0-prerequisites.md b/website/src/content/docs/learning-hub/copilot-workshops/cloud/0-prerequisites.md new file mode 100644 index 00000000..20d37b30 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cloud/0-prerequisites.md @@ -0,0 +1,65 @@ +--- +title: "Exercise 0: Prerequisites" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Before you start the Copilot cloud agent exercises, you need to get everything ready. You'll create your own copy of the Tailspin Toys repository and spin up a [codespace][codespaces] you can use to edit instruction files and review the work the cloud agent produces. + +## Setting up the lab repository + +To create a copy of the repository for the code you'll create, you'll make an instance from the [template][template-repository]. The new instance will contain all of the necessary files for the lab, and you'll use it as you work through the exercises. + +1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/tailspin-toys`. +2. Create your own copy of the repository by selecting the **Use this template** button on the lab repository page. Then select **Create a new repository**. + + ![Use this template button](/images/learning-hub/copilot-workshops/ex0-use-template.png) + +3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to GitHub Copilot. + + ![Input the repository template settings](/images/learning-hub/copilot-workshops/ex0-repository-settings.png) + +4. Make a note of the repository path you created (**organization-or-user-name/repository-name**), as you will be referring to this later in the lab. +## Creating a codespace + +Next up, you'll use a codespace to complete the lab exercises. + +[GitHub Codespaces][codespaces] are a cloud-based development environment that allows you to write, run, and debug code directly in your browser. It provides a fully-featured IDE with support for multiple programming languages, extensions, and tools. + +1. Navigate to your newly created repository. +2. Select the green **Code** button. + + ![Select the Code button](/images/learning-hub/copilot-workshops/ex0-code-button.png) + +3. Select the **Codespaces** tab and select the **+** button to create a new Codespace. + + ![Create a new codespace](/images/learning-hub/copilot-workshops/ex0-create-codespace.png) + +The creation of the codespace will take several minutes, although it's still far quicker than having to manually install all the services! That said, you can use this time to explore other features of GitHub Copilot, which we'll turn your attention to next. + +> [!CAUTION] +> You'll return to the codespace in a future exercise. For the time being, leave it open in a tab in your browser. + +> [!NOTE] +> This workshop is built to run inside a codespace or local [dev container][dev-containers]. Both ensure the environment has all the necessary prerequisites installed for a smooth experience. If you'd prefer to run it locally, open the cloned repository in VS Code and select **Reopen in Container** when prompted — VS Code will build the same dev container the codespace uses. + +[codespaces]: https://github.com/features/codespaces +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers +## Summary + +Congratulations, you have created a copy of the lab repository! You also began the creation process of your codespace, which you'll use as you work alongside the Copilot cloud agent. + +## Next step + +Let's add custom instructions the cloud agent will follow. Continue to [Exercise 1 - Custom instructions][next-lesson]. + +## Resources + +- [GitHub Codespaces overview][codespaces] +- [Creating a repository from a template][template-repository] +- [Getting started with Codespaces][codespaces-quickstart] + +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[codespaces-quickstart]: https://docs.github.com/codespaces/getting-started/quickstart +[next-lesson]: /learning-hub/copilot-workshops/cloud/1-custom-instructions/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cloud/1-custom-instructions.md b/website/src/content/docs/learning-hub/copilot-workshops/cloud/1-custom-instructions.md new file mode 100644 index 00000000..d03d96c2 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cloud/1-custom-instructions.md @@ -0,0 +1,149 @@ +--- +title: "Exercise 1 - Custom instructions (Cloud agent)" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[← Previous lesson: Prerequisites][previous-lesson] · [Next lesson: Copilot cloud agent →][next-lesson] + +Context is key when working with generative AI. If a task needs to be done a particular way — or there's background information Copilot should know — you want to make sure that context is reachable. [Instruction files][instruction-files] are how you provide that guidance, so Copilot understands not just *what* you want it to do but *how* you want it done. + +In this exercise, you will: + +- explore how project-specific context, coding guidelines, and documentation standards reach Copilot through repository custom instructions and path-scoped instruction files, +- add a new repository-wide standard to `.github/copilot-instructions.md`. + +> [!NOTE] +> Unlike the VS Code and CLI harnesses, you won't run a *before/after* prompt here — Copilot cloud agent works asynchronously on GitHub issues, so the impact is harder to demonstrate side-by-side in real time. You'll see your instruction file's influence later in this harness when you review the pull requests cloud agent produces. + +## Instruction files + +### Scenario + +As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include: + +- The data layer always needs unit tests. +- UI should be in dark mode and have a modern feel. +- Documentation should be added to code in the form of TSDoc doc comments. +- A block of comments should be added to the head of each file describing what the file does. + +Through the use of instruction files you'll ensure Copilot has the right information to perform the tasks in alignment with the practices highlighted. + +### Custom instructions + +Custom instructions allow you to provide context and preferences to Copilot, so that it can better understand your coding style and requirements. This is a powerful feature that can help you steer Copilot to get more relevant suggestions and code snippets. You can specify your preferred coding conventions, libraries, and even the types of comments you like to include in your code. You can create instructions for your entire repository, or for specific types of files for task-level context. + +There are two types of instructions files: + +- `.github/copilot-instructions.md`, a single instruction file sent to Copilot for **every** request for the repository. This file should contain project-level information — context relevant for most chat or CLI requests sent to Copilot. This could include the tech stack being used, an overview of what's being built, best practices, and other global guidance. +- `.github/instructions/*.instructions.md` files can be created for specific tasks or file types. You can use them to provide guidelines for particular languages (like TypeScript or Astro), or for tasks like creating a UI component or a new set of unit tests. + +> [!NOTE] +> When working in your IDE, instructions files are only used for code generation in Copilot Chat — not for code completions or next-edit suggestions. +> +> Copilot Chat, Copilot CLI and Copilot cloud agent use both repository-level and `*.instructions.md` files (with `applyTo` front matter) when generating code. +> +> Finally, Copilot [supports instructions files using other standards][custom-instructions-support], including AGENTS.md and CLAUDE.md files. + +### Best practices for managing instructions files + +A full conversation about creating instructions files is beyond the scope of the workshop. However, the examples provided in the sample project show a representative approach. At a high level: + +- Keep instructions in `copilot-instructions.md` focused on project-level guidance, such as a description of what's being built, the structure of the project, and global coding standards. +- Use `*.instructions.md` files to provide specific instructions for file types (unit tests, Astro components, the data layer), or for specific tasks. +- Use natural language. Keep guidance clear. Provide examples of how code should (and shouldn't) look. + +There isn't one specific way to create instructions files, just as there isn't one specific way to use AI. You will find through experimentation what works best for your project. + +> [!TIP] +> Every project using GitHub Copilot should have a robust collection of instruction files. As you explore the ones in this project, you may notice there are files for numerous types of tasks, including [UI updates][ui-instructions] and [Astro][astro-instructions]. +> +> Copilot can also help generate instruction files for you. Each surface exposes this differently (for example, **Configure Chat → Generate Agent Instructions** in VS Code, or `/init` in Copilot CLI) — the lesson for the surface you're on will call it out where it's relevant. +> +> Looking for templates or a starting point? Explore [awesome-copilot][awesome-copilot], a repository full of instruction files, custom agents, and other resources. + +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[awesome-copilot]: https://github.com/github/awesome-copilot +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +## Explore the custom instructions files in this project + +Take a moment to read the instruction files this repository ships with — there's one core `copilot-instructions.md` and a collection of `*.instructions.md` files for various tasks. Open these in your editor or the GitHub web UI. + +1. Open `.github/copilot-instructions.md`. +2. Explore the file, noting the brief description of the project plus sections such as **Agent notes**, **Code standards**, **Scripts**, and **Repository Structure**. Under **Code standards**, note the nested **GitHub Actions Workflows** guidance. These are applicable to any interactions you'd have with Copilot. +3. Open the `.github/instructions` folder and look around. Note there are instructions for Astro files, the Drizzle data layer, tests, and more. +4. Open `.github/instructions/unit-tests.instructions.md`. Note the `applyTo` field at the top — this sets a glob (relative to the repo root) that determines which files the instructions apply to. Here, any TypeScript test file (for example, one matching `**/*.test.ts`) will match. +5. Note the instructions specific to creating unit tests for this project. +6. Finally, open `.github/instructions/drizzle.instructions.md` and scroll to the bottom. Note the links to other instruction files (like `unit-tests.instructions.md`) and existing files in the project. This lets you break larger instruction sets into smaller, reusable files, and point Copilot at examples to follow when generating code. (Paths there are relative to the instruction file rather than the repo root.) + +> [!NOTE] +> The **Code formatting requirements** section in `copilot-instructions.md` documents the project's coding standards, but it doesn't yet require in-code documentation. In the next steps, you'll add rules for TSDoc doc comments and file comment headers. +## Add a new repository standard + +The next step is the one bit of editing you'll do here: add a project-wide rule that documentation should live in code as TSDoc doc comments and a file-level comment header. Cloud agent will pick this up when it works on issues you assign to it later in this harness. + +Before you edit, set up a branch to work on (cloud agent will read your instructions from whatever branch the issue targets, but you'll commit your edits cleanly anyway): + +1. From your codespace terminal, create and switch to a new branch: + + ```bash + git checkout -b custom-instructions-cloud + ``` + +As highlighted previously, `.github/copilot-instructions.md` is designed to provide project-level information to Copilot. Let's ensure repository coding standards are documented to improve code suggestions. + +1. Re-open `.github/copilot-instructions.md`. +2. Locate the **Code formatting requirements** section, which should be near line 27. Note how it documents the project's coding standards — but it has no rule yet for in-code documentation, which is why the generated helper had no doc comments. +3. Add the following lines of markdown right below the existing standards to instruct Copilot to add file comment headers and TSDoc doc comments: + + ```markdown + - Every exported function should have a TSDoc comment describing its purpose, parameters, and return value. + - Before imports or any code, add a comment block to the file that explains its purpose. + ``` + +4. Save `copilot-instructions.md`. + +> [!TIP] +> As you saw in the previous lesson, instruction files can be created at the repository level (`.github/copilot-instructions.md`) for global guidance, or as `*.instructions.md` files for specific languages, file types, or tasks. The repository-level file is the right home for project-wide standards like the doc comment rule you just added. +## Commit, push, and merge your instruction update + +Cloud agent reads instruction files from the branch the issue targets. When you assign an issue to Copilot in the next exercise, Copilot will branch from `main` — so your instruction changes must land on `main` for cloud agent to pick them up. + +1. Stage and commit: + + ```bash + git add .github/copilot-instructions.md + git commit -m "Add doc comment and file-header standards to copilot instructions" + ``` + +2. Push the branch: + + ```bash + git push -u origin custom-instructions-cloud + ``` + +3. Open a pull request from `custom-instructions-cloud` into `main` on github.com and merge it. Cloud agent will then read these instructions when it works on issues assigned in the next exercise. + +> [!TIP] +> If you'd rather work on `main` directly for this workshop, you can skip the branch and commit straight to `main`. The branch step is here so the workshop mirrors the way you'd handle this on a real project. + +## Summary and next steps + +You explored how Copilot picks up context from instruction files in this project and added a new repository-wide standard to `.github/copilot-instructions.md`. You'll see that standard exercised in the pull requests cloud agent generates over the rest of this harness. + +Next, you'll [assign your first issue to Copilot cloud agent][next-lesson]. + +## Resources + +- [Instruction files for GitHub Copilot customization][instruction-files] +- [Best practices for creating custom instructions][instructions-best-practices] +- [5 tips for writing better custom instructions for Copilot][copilot-instructions-five-tips] +- [Awesome Copilot — a collection of instruction files and other resources][awesome-copilot] + +[previous-lesson]: /learning-hub/copilot-workshops/cloud/0-prerequisites/ +[next-lesson]: /learning-hub/copilot-workshops/cloud/2-cloud-agent/ +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[copilot-instructions-five-tips]: https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cloud/2-cloud-agent.md b/website/src/content/docs/learning-hub/copilot-workshops/cloud/2-cloud-agent.md new file mode 100644 index 00000000..58d85797 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cloud/2-cloud-agent.md @@ -0,0 +1,202 @@ +--- +title: "Exercise 2 - GitHub Copilot cloud agent" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +| [← Previous lesson: Custom instructions][previous-lesson] | +|:--| + +There are likely very few, if any, organizations who don't struggle with tech debt. This could be unresolved security issues, legacy code requiring updates, or feature requests which have languished on the backlog because there just wasn't the time to implement them. GitHub Copilot's cloud agent is built to perform tasks such as updating code and adding functionality, all in an autonomous fashion. Once the agent completes its work, it generates a draft PR ready for a human developer to review. This allows offloading of tedious tasks and an acceleration of the development process, and frees developers to focus on larger picture items. + +You'll explore the following with Copilot cloud agent: + +- customizing the environment for generating code. +- ensuring operations are performed securely. +- the importance of clearly scoped issues. +- assigning issues to Copilot. + +## Scenarios + +Tailspin Toys has some tech debt they'd like to address. The contractors initially hired to create the first version of the site left the documentation in an unideal state - and by that you'll notice it's completely lacking. As a first step, they'd like to see TSDoc doc comments added to all exported functions in the application. + +Additionally, the design team is ready to improve game discovery. They'd like each game's details page to show related games — other titles in the same category — so people can keep browsing. They don't need a polished implementation yet; they just want something they can use for acceptance testing of the UX. This is currently a blocker, but there are other issues which are of higher priority at the moment. + +These are both examples of tasks which can quickly find themselves deprioritized, and are great to assign to Copilot cloud agent. Copilot cloud agent can then work on them asynchronously, allowing the developer to focus on other tasks, then return to review Copilot's work and ensure everything is as expected. +## Introducing GitHub Copilot cloud agent + +[GitHub Copilot cloud agent](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent#overview-of-copilot-cloud-agent-formerly-copilot-coding-agent) can perform tasks in the background, much in the same way a human developer would. And, just like with working with a human developer, this can be done in multiple ways, including [assigning a GitHub issue to Copilot](https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions). Once assigned, Copilot will create a draft pull request to track its progress, setup an environment, and begin working on the task. You can dig into Copilot's session while it's still in flight or after its completed. Once its ready for you to review the proposed solution, it'll tag you in the pull request! +## The importance of well-scoped instructions + +There's no magic in GitHub Copilot — you don't get to skip the thinking. Even seemingly straightforward operations carry complexity once you peel back the layers, so [be mindful about how you scope tasks for Copilot cloud agent][cloud-agent-best-practices]. Treat it like an AI pair programmer: work in stages, learn, experiment, and adapt as you go. The fundamentals of software development don't change with the addition of generative AI. + +## Custom instructions in this repository + +Earlier exercises introduced custom instructions and how they guide Copilot. If you've already worked through a custom-instructions hands-on you've seen `.github/copilot-instructions.md` in action; if not, this is a good moment to take a quick look. Before assigning work to Copilot cloud agent, take a read-only look at the instruction files already included in this repository so you can spot their effect later. + +Open the following files in the GitHub web UI for your repository, or in a codespace if you already have one running: + +- `.github/copilot-instructions.md` - Review the **Code standards** section, especially the expectations for TypeScript conventions and TSDoc doc comments. +- `.github/instructions/unit-tests.instructions.md` - Notice the `applyTo` frontmatter, which scopes these instructions to `**/*.test.ts` files. + +When you assign the `Code lacks documentation` issue to cloud agent in the next section, watch the resulting pull request for TSDoc doc comments, TypeScript conventions, and comment headers - these come from these instruction files. We'll call this out again when reviewing PRs in a later exercise. + +## Setting up the dev environment for the Copilot cloud agent + +Creating code, regardless of who's involved, typically requires a specific environment and some setup scripts to be run to ensure everything is in a good state. This holds true when assigning tasks to Copilot, which is performing tasks in a similar fashion to a SWE. + +Cloud agent uses [GitHub Actions][github-actions] for its environment when doing its work. You can customize this environment by creating a [special setup workflow][setup-workflow], configured in the `.github/workflows/copilot-setup-steps.yml` file, to run before it gets to work. This enables it to have access to the required development tools and dependencies. This has been pre-configured ahead of the lab to help the lab flow and allow this learning opportunity. It makes sure that Copilot has access to Node.js, project dependencies, browser binaries for end-to-end tests, and the migrated and seeded SQLite database for the single Astro app: + +```yaml +name: "Copilot Setup Steps" + +# Allows you to test the setup steps from your repository's "Actions" tab +on: workflow_dispatch + +env: + ASTRO_TELEMETRY_DISABLED: "1" + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + # Set the permissions to the lowest permissions possible needed for *your steps*. Copilot will be given its own token for its operations. + permissions: + # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete. + contents: read + steps: + - name: Checkout code + uses: actions/checkout@v5 + + # Frontend / app setup - Node.js (the whole app is now Astro + Drizzle/libSQL) + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: "lts/*" + cache: "npm" + cache-dependency-path: "./package-lock.json" + + - name: Install JavaScript dependencies + run: npm ci + + - name: Install Playwright browsers + run: npx playwright install --with-deps chromium + + # Migrate + seed the local SQLite database so builds and tests have data. + - name: Set up the database + run: npm run db:setup +``` + +It looks like any other GitHub workflow file, but it has a few key points: + +- It contains a single job called `copilot-setup-steps`. This job is executed in GitHub Actions before Copilot starts working on the pull request. +- Notice the `workflow_dispatch` trigger, which allows you to run the workflow manually from the **Actions** tab of your repository. This is useful for testing that the workflow runs successfully instead of waiting for Copilot to run it. + +## Adding documentation + +While everyone understands the importance of documentation, most projects have either outdated information or lack it altogether. This is the type of tech debt which often goes unaddressed, slowing productivity and making it more difficult to maintain the codebase or bring new developers into the team. Fortunately, Copilot shines at creating documentation, and this is a perfect issue to assign to Copilot cloud agent. It'll work in the background to generate the necessary documentation. In a future exercise you'll return to review its work. + +1. Navigate to your repository on github.com in a new browser tab. +2. Select the **Issues** tab. +3. Select **New issue** to open the new issue dialog. +4. Select **Blank issue** to create the new issue. +5. Set the **Title** to `Code lacks documentation`. +6. Set the **Description** to: + + ```plaintext + Our organization has a requirement that functions and methods include TSDoc doc comments where helpful. Unfortunately, recent updates haven't followed this standard. We need to update the existing code to ensure doc comments are included where they clarify behavior. + ``` + +7. Select **Create** to create the issue. +8. On the right side, select **Assign to Copilot** to open the assignment dialog. + + ![Assigning Copilot to an issue](/images/learning-hub/copilot-workshops/shared-assign-copilot.png) + +9. Select **Assign**. + + ![Copilot assignment details](/images/learning-hub/copilot-workshops/ex4-assign-copilot-details.png) + +10. Select the **Pull Requests** tab. +11. Open the newly generated pull request (PR), which will be titled something similar to `[WIP]: Code lacks documentation`. If a new PR doesn't appear on the list, wait for a moment or two and refresh the browser window. +12. After a few minutes, you should see that Copilot has created a todo list. + +> [!NOTE] +> It may take several minutes for the todo list from Copilot to appear in the PR. Copilot is creating its environment (running the workflow highlighted previously), analyzing the project, and determining the best approach to tackling the problem. + +13. Review the list and the tasks it's going to complete. +14. Scroll down the pull request timeline, and you should see an update that Copilot has started working on the issue. +15. Select the **View session** button. + + ![Copilot session view](/images/learning-hub/copilot-workshops/ex4-view-session.png) + +> [!CAUTION] +> You may need to refresh the window to see the updated indicator. + +16. Notice that you can scroll through the live session, and how Copilot is solving the problem. That includes exploring the code and understanding the state, how Copilot pauses to think and decide on the appropriate plan and also creating code. + +This will likely take several minutes. One of the primary goals of Copilot cloud agent is to allow it to perform tasks asynchronously, freeing us to focus on other tasks. We're going to take advantage of that very feature by both assigning another task to Copilot cloud agent, then turning our attention to writing some code to add features to our application. + +## Add a related games section to the game details page + +As has been highlighted, one of the great advantages of GitHub Copilot cloud agent is the ability to divide work, where you can focus on one set of tasks while it focuses on another. While adding a related games section for the design team might not necessarily take a long time, it's still time which could be used for other tasks. Let's assign it to Copilot cloud agent! + +1. Return to your repository on github.com. +2. Select the **Issues** tab. +3. Select **New issue** to open the new issue dialog. +4. Select **Blank issue** to use the blank template. +5. Set the **Title** to: `Show related games on the game details page` +6. Set the **Description** to: + + ```markdown + We want to help people discover more games by showing related games on each game's details page. The design team wants to explore the UX and do some acceptance testing. Our requirements are: + + - Add a data-access helper in `src/lib/` that returns other games in the same category as a given game, excluding that game + - Show a "Related games" section on the game details page that uses the helper + - Handle the case where a game has no related games + - There should be unit tests created for the new helper + - Before creating the PR, ensure all tests pass + ``` + +7. Select **Create** to create the issue. +8. On the right side, select **Assign to Copilot** to open the assignment dialog. + + ![Assigning Copilot to an issue](/images/learning-hub/copilot-workshops/shared-assign-copilot.png) + +9. Select **Assign**. + +Shortly after, you should see a set of 👀 on the first comment in the issue, indicating Copilot is on the job! + +![Copilot uses the eyes emoji to indicate it's working on the issue](/images/learning-hub/copilot-workshops/ex4-issue-eyes-emoji.png) + +Copilot is now diligently working on your second request! Copilot cloud agent works in a similar fashion to a SWE, so you don't need to actively monitor it, but instead review once it's completed. Let's turn your attention to creating and using custom agents. + +## Summary and next steps + +This lesson explored [GitHub Copilot cloud agent][copilot-agents]. With cloud agent you can assign issues to Copilot to perform asynchronously. You can use Copilot to address tech debt, create new features, or aid in migrating code from one framework to another. + +You explored these concepts: + +- customizing the environment for generating code. +- ensuring operations are performed securely. +- the importance of clearly scoped issues. +- assigning issues to Copilot. + +With cloud agent working diligently in the background, we can now turn our attention to creating and using custom agents. [Copilot cloud agent can also use MCP servers][cloud-agent-mcp], and has custom instructions available to it, which we explored in earlier modules. + +## Resources + +- [About Copilot cloud agent][copilot-agents] +- [Assigning GitHub issues to Copilot][assign-issue] +- [Copilot cloud agent setup workflow best practices][cloud-agent-best-practices] + +| [Next lesson: Custom agents →][next-lesson] | +|--:| + +[previous-lesson]: /learning-hub/copilot-workshops/cloud/1-custom-instructions/ +[next-lesson]: /learning-hub/copilot-workshops/cloud/3-custom-agents/ +[cloud-agent-mcp]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/extend-cloud-agent-with-mcp +[assign-issue]: https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions +[setup-workflow]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[copilot-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[cloud-agent-best-practices]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[github-actions]: https://docs.github.com/actions diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cloud/3-custom-agents.md b/website/src/content/docs/learning-hub/copilot-workshops/cloud/3-custom-agents.md new file mode 100644 index 00000000..554c63f5 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cloud/3-custom-agents.md @@ -0,0 +1,103 @@ +--- +title: "Exercise 3 - Custom agents" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +## What are custom agents? + +[Custom agents][custom-agents-concept] in GitHub Copilot allow you to create specialized AI assistants tailored to specific tasks or domains within your development workflow. By defining agents through markdown files in the `.github/agents` folder of your repository, you can provide Copilot with focused instructions, best practices, coding patterns, and domain-specific knowledge that guide it to perform particular types of work more effectively. Teams can codify their expertise into reusable agents — an accessibility agent that enforces [WCAG][wcag] compliance, a security agent that follows secure coding practices, or a testing agent that maintains consistent test patterns. + +Custom agents are defined by markdown files in the `.github/agents` folder of your project, or globally in `~/.copilot/agents`. Each file has YAML frontmatter with at least a `name` and `description`, followed by a markdown prompt that defines the agent's behavior, expertise, and instructions. + +### Custom agents compared with agent skills + +There's some logical overlap between custom agents and [agent skills][agent-skills-concept]. Both are primarily defined with markdown files and tell an AI how to perform operations. The cleanest way to separate them: a **custom agent** is the worker, and **skills** are tools. + +Custom agents have their own context window and are built to orchestrate skills (and even other agents) as part of doing their work. In this lab, the accessibility custom agent reviews and updates the site against accessibility guidelines; as part of that work it could call skills such as a pull-request workflow skill or one that runs and manages tests. + +> [!NOTE] +> There's no single "right" way to author a custom agent. As with anything in AI, test and iterate to find what works for your environments and scenarios. + +[custom-agents-concept]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[agent-skills-concept]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/ +You'll explore the following with custom agents: + +- how custom agents are defined. +- assigning a task to a custom agent. + +## Scenario + +Tailspin Toys is committed to ensuring their crowdfunding platform is accessible to all users, regardless of their visual abilities or preferences. Recent user feedback has highlighted that some users find the current dark theme difficult to read due to insufficient contrast between text and background colors. To address this accessibility concern, the design team has requested the implementation of a high-contrast mode that users can toggle on and off. + +Because accessibility is critical, you want to ensure this is implemented as quickly as possible. You're going to utilize a custom agent to generate the functionality. +## Reviewing the accessibility custom agent + +A custom agent has already been created for you for accessibility. Let's review the contents to understand how it will guide Copilot. + +Return to your codespace, then review the accessibility custom agent file: + +1. Open `.github/agents/accessibility.md`. +2. Note the YAML frontmatter with the `name` and `description` fields. + +> [!CAUTION] +> The frontmatter with `name` and `description` is required for custom agents. + +3. From there, scan and review the next sections which highlight: + - Core responsibilities when generating code for an accessible website. + - Best practices for accessibility. + - Code examples for HTML, CSS, and JavaScript. + - A list of common pitfalls and mistakes. +## Create and assign an issue + +Mission control is the central location for working with all agents for your environment. You can assign tasks to Copilot cloud agent, monitor tasks, and even redirect and provide additional guidance. Let's start by assigning a task to create the high contrast mode to Copilot. + +1. Navigate to your repository. +2. Select the issues tab. +3. Select **New issue** to open the new issue dialog. +4. Select **Blank issue** to create the new issue. +5. Set the **Title** to `Add high contrast mode to website`. +6. Set the **Description** to: + + ```plaintext + We need a high contrast mode for the site. There should be a toggle for high contrast which the user can set. It should store the setting in local storage on the browser. + ``` + +7. Select **Create** to create the issue. +8. On the right side, select **Assign to Copilot** to open the assignment dialog. +9. Select **Accessibility agent** from the list of custom agents. + + ![Screenshot of cloud agent assignment, with custom agent and accessibility highlighted](/images/learning-hub/copilot-workshops/ex5-select-custom-agent.png) + +10. Select **Assign**. +11. Copilot gets to work on the task in the background! + +## Summary and next steps + +This lesson explored [custom agents][custom-agents] in GitHub Copilot, specialized AI assistants tailored to specific tasks and domains. With custom agents you can codify your team's expertise and standards into reusable agents that guide Copilot to perform particular types of work more effectively. + +You explored these concepts: + +- how custom agents are defined. +- assigning a task to a custom agent. + +With Copilot working on implementing the high contrast mode, we can now turn our attention to [monitoring and steering the agent session][next-lesson] from mission control. + +## Resources + +- [About custom agents][custom-agents] +- [Preparing to use custom agents in your organization][org-custom-agents] +- [Preparing to use custom agents in your enterprise][enterprise-custom-agents] + +--- + +| [← Previous lesson: GitHub Copilot cloud agent][previous-lesson] | [Next lesson: Monitoring and managing agents →][next-lesson] | +|:--|--:| + +[previous-lesson]: /learning-hub/copilot-workshops/cloud/2-cloud-agent/ +[next-lesson]: /learning-hub/copilot-workshops/cloud/4-managing-agents/ +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[org-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents +[enterprise-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cloud/4-managing-agents.md b/website/src/content/docs/learning-hub/copilot-workshops/cloud/4-managing-agents.md new file mode 100644 index 00000000..cd5c88b3 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cloud/4-managing-agents.md @@ -0,0 +1,91 @@ +--- +title: "Exercise 4 - Monitoring and managing agents" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +In the last couple of exercises you asked Copilot cloud agent to take on three separate tasks focused on improving the user experience and adding functionality. While cloud agent is built to operate asynchronously and autonomously, the ability to monitor these tasks is still important. + +There are numerous tools available to you to manage tasks assigned to cloud agent, including [the agents page][agents-page] on GitHub.com. From this mission control you can see all agent tasks with open pull requests (PRs). You can explore the operations performed, and even steer an in-progress session to help guide it. + +In this lesson you will: + +- explore the agents page to monitor cloud agent tasks. +- steer an in-flight session to request additional functionality. + +## Scenario + +After assigning the agent to create a high-contrast mode, the team realized it would be a good time to add a light mode as well. Since work was already being done to update the style of the site and add toggle functionality, it seemed logical to include this functionality. You want to steer the agent's work to ensure it adds a light mode as well as high contrast. + +## Review Copilot cloud agent tasks + +Let's see the current status of all tasks assigned to Copilot cloud agent. + +1. Navigate to the agents page at [https://github.com/copilot/agents](https://github.com/copilot/agents). +2. Note the list of tasks, both on the main pane and on the left pane. You should see the list of the tasks you've assigned to Copilot, including: + - Updating documentation for your codebase. + - Generating APIs for modifying games. + - Adding a high contrast mode for the website. +3. Select one of the running tasks. Review the tasks which have been performed by Copilot. These can include: + - Checking out the code from the repository. + - Creating the environment for Copilot to work. + - Setting up MCP servers. + - Performing various steps to complete the assigned task. + +> [!NOTE] +> The exact steps listed will vary depending on the state of Copilot's work and the approach it took. + +4. Also note the pull request (PR) pane which appears on the right side. This allows you to see the PR and files changed for additional monitoring. + +## Steering cloud agent + +Now that you've seen the tasks which are active, let's request Copilot include the light mode toggle while it works on the high-contrast mode. + +1. Select the session which refers to adding a high contrast mode. The exact title will vary depending on the name Copilot uses and the current state of work. + + ![Accessibility session in mission control](/images/learning-hub/copilot-workshops/ex6-accessibility-session.png) + +2. Watch the session for a few minutes, until it indicates it's completed the setup and begun its work. You'll know this has happened when you start seeing messages similar to the ones below. +3. In the **Steer active session while Copilot is working** dialog, add the following prompt: + + ``` + While we are working on a high contrast mode, let's also add a light mode. There should be a switch for this mode as well where users can select their desired display mode. + ``` + + ![Screenshot of the cloud agent task in the agents page with the steer active session while copilot is working dialog highlighted](/images/learning-hub/copilot-workshops/ex6-steer-cloud-agent-task.png) + +4. Press Enter to send the prompt. +5. Notice how Copilot acknowledges the prompt and includes it in its flow. + +## Let Copilot do its work + +Just like before, Copilot will get to work on the updated task! It will incorporate the new request into its flow after it completes the particular step it's working on when you sent the message. + +As before, this will take several minutes, so it's a good time to pause and reflect on everything you've learned and explored thus far. + +## Summary and next steps + +This lesson explored the Copilot agents page, your central hub for monitoring and guiding GitHub Copilot cloud agent tasks. With this mission control you can track all active and completed tasks, review the work being performed, and even redirect in-flight tasks to adjust scope or provide additional guidance. + +You explored these concepts: + +- explored mission control and the agents page to monitor cloud agent tasks. +- redirected an in-flight session to request additional functionality. + +With Copilot completing its work on the accessibility features, we can now turn our attention to [iterating on the pull requests Copilot created][next-lesson]. + +## Resources + +- [Copilot agents page][agents-page] +- [About custom agents][custom-agents] + +--- + +| [← Previous lesson: Custom agents][previous-lesson] | [Next lesson: Iterating on Copilot's work →][next-lesson] | +|:--|--:| + +[previous-lesson]: /learning-hub/copilot-workshops/cloud/3-custom-agents/ +[next-lesson]: /learning-hub/copilot-workshops/cloud/5-iterating/ +[agents-page]: https://github.blog/changelog/2025-07-03-agents-page-for-copilot-coding-agent-in-public-preview +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cloud/5-iterating.md b/website/src/content/docs/learning-hub/copilot-workshops/cloud/5-iterating.md new file mode 100644 index 00000000..0d8ee0b9 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cloud/5-iterating.md @@ -0,0 +1,187 @@ +--- +title: "Exercise 5: Iterating on GitHub Copilot's work" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +| [← Previous lesson: Managing agents][previous-lesson] | +|:--| + +## Reviewing the work + +Throughout this lab you've worked with GitHub Copilot on several tasks focused on improving the user experience and adding functionality. You asked Copilot to add documentation to your code, build a related games feature for the design team to iterate on, and implement accessibility features including high-contrast and light mode toggles. Let's explore the code changes and, if necessary, provide feedback to Copilot to improve its work. + +### Scenario + +As has been highlighted numerous times, the fundamentals of software design and DevOps do not change with the addition of generative AI. We always want to review the code generated, and work through our normal DevOps process. With that in mind, let's review the suggestions from GitHub Copilot for creating the documentation, the related games feature, and accessibility features before we turn on review for the rest of our team. +## Security and GitHub Copilot cloud agent + +Because Copilot cloud agent performs its tasks asynchronously and without supervision, certain security constraints have been put in place to ensure everything remains safe. These include: + +- Copilot only has read access to your repository and write access **only** to the branch it will use for its code. +- Cloud agent runs inside of GitHub Actions, where it will create a separate, ephemeral environment in which to work. +- Any GitHub Actions workflows require approval from a human before they can be run. +- [Access to external resources is limited by default](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-firewall), including MCP servers. +## Reviewing the generated documentation + +Let's start by exploring the first pull request (PR) generated by GitHub Copilot cloud agent - adding documentation to your code. You'll perform this task by utilizing the standard PR interface in GitHub.com. + +> [!NOTE] +> When you explore the PR you may notice a warning about GitHub Copilot being blocked by a firewall. This **is expected**, as Copilot has limited access to external resources by default, including calls to external MCP servers. If you wish, you can [customize or disable the firewall for Copilot cloud agent][agent-firewall]. + +1. Return to your repository on github.com. +2. Select **Pull Requests** to open the list of pull requests. +3. Open the pull request titled something similar to **Add missing documentation** or something more robust. + +> [!NOTE] +> If Copilot is still working on the task, the pull request will contain the **[WIP]** flag. If so, wait for Copilot to complete the work. This may take a few minutes, so feel free to take a break, or reflect on everything you've learned so far. + +4. Once the pull request is ready, select the **Files changed** tab and review the changes. + + ![Files changed tab](/images/learning-hub/copilot-workshops/shared-pr-files-changed.png) + +5. Explore the newly updated code, which includes the newly created TSDoc doc comments and other documentation. The exact changes will vary. + + As you scan the changes, look for TSDoc doc comments, TypeScript conventions, and comment headers. These come from the custom instruction files you reviewed at the start of Exercise 2. + +6. Once you've reviewed the updates and everything looks good, navigate back to the **Conversation** tab and scroll down. +7. You should see an indicator that some workflows are waiting for approval. +8. If workflows are waiting for approval, select **Approve and run workflows**. + + ![Approve and run workflows](/images/learning-hub/copilot-workshops/shared-approve-workflows.png) +9. You should see the workflows get queued in the checks section of the pull request. All being well, you should see that the project checks pass for the single Astro app. This may take a few minutes to complete. + +## Requesting changes from GitHub Copilot + +Working with Copilot on a pull request is not just a one-way street. You can also tag Copilot in comments - like you would other members of your team - in the pull request, or inline comments of the code. Copilot will see these comments, and trigger another session to address them. Due to the non-deterministic results, we can't give prescriptive text of what to ask for. Some ideas of what to ask Copilot to update include: + +- Add comment headers to the top of each code file with a brief description of what they do. +- Add TSDoc doc comments to TypeScript and Astro files. +- Create a README with a description of the Astro app structure. + +1. Add a comment requesting a change to the generated documentation, tagging **@copilot** like you would any user. Use one of the ideas above, or another suggestion for Copilot around documentation you'd like to see in the codebase. +2. Select **View Session** to watch Copilot perform its work. Notice how Copilot starts a new session to make the updates. +3. You can select **Back to pull request** to return to the pull request. + + ![Back to pull request](/images/learning-hub/copilot-workshops/ex7-back-to-pr.png) + +4. Once Copilot has completed the changes, you should see a new commit in the pull request. +5. Select the **Files changed** tab to review the changes. + +Feel free to continue iterating until you are happy. Once happy, you can convert the PR to ready from a draft, and merge it into the main branch. + +![Convert PR to ready](/images/learning-hub/copilot-workshops/ex7-ready-for-review.png) + +## Review the related games feature + +Let's return to the PR Copilot generated for resolving our issue about showing related games on the game details page. + +1. Return to your repository in GitHub.com. +2. Select the **Pull Requests** tab. +3. Select the PR which has a title similar to **Show related games on the game details page** or something more robust. +4. Select the **Files changed** tab to review the code it generated. +5. Once you've reviewed the updates and everything looks good, navigate back to the **Conversation** tab and scroll down. +6. You should see an indicator that some workflows are waiting for approval. +7. If workflows are waiting for approval, select **Approve and run workflows**. + + ![Approve and run workflows](/images/learning-hub/copilot-workshops/shared-approve-workflows.png) +8. You should see the workflows get queued in the checks section of the pull request. All being well, you should see that the project checks pass for the single Astro app. This may take a few minutes to complete. +9. **Optional:** You could even switch to this branch in your Codespace to perform a manual test of the related games feature. Navigate to your Codespace, open the terminal, and run the following commands (replace `` with the name of the branch Copilot created, e.g. **copilot/fix-8**.): + + ```bash + git fetch origin + git checkout + ``` + +Copilot has built the related games feature! Just as before, you can work iteratively with Copilot cloud agent to request updates. For example, you might want to request Copilot tweak how many related games are shown, or ensuring comment headers and TSDoc doc comments are added (remember - this was assigned **before** you made the updates to your custom instructions!) Just like before, you can make these requests by adding a new comment on the **Conversation** tab, which Copilot will see and kickoff a new session. + +## Review the accessibility features + +Finally, let's review the accessibility features that were implemented using the custom accessibility agent. This PR should include both the high-contrast mode you assigned in Exercise 3, and the light mode that was requested in mission control in Exercise 4. + +1. Return to your repository in GitHub.com. +2. Select the **Pull Requests** tab. +3. Select the PR which has a title similar to **Add high contrast mode to website** or something more robust. + +> [!NOTE] +> If Copilot is still working on the task, the pull request will contain the **[WIP]** flag. If so, wait for Copilot to complete the work. This may take a few minutes. + +4. Select the **Files changed** tab to review the code it generated. +5. Review the implementation, paying particular attention to: + - The toggle UI components for switching between modes + - The use of local storage to persist user preferences + - The CSS or styling changes for high-contrast and light modes + - The accessibility attributes (ARIA labels, keyboard navigation, etc.) + - Any JavaScript/TypeScript code that manages the mode switching + +6. Once you've reviewed the updates and everything looks good, navigate back to the **Conversation** tab and scroll down. +7. You should see an indicator that some workflows are waiting for approval. +8. If workflows are waiting for approval, select **Approve and run workflows**. + + ![Approve and run workflows](/images/learning-hub/copilot-workshops/shared-approve-workflows.png) +9. You should see the workflows get queued in the checks section of the pull request. All being well, you should see that the project checks pass for the single Astro app. This may take a few minutes to complete. +10. **Optional:** You could switch to this branch in your Codespace to manually test the accessibility features. Navigate to your Codespace, open the terminal, and run the following commands (replace `` with the name of the branch Copilot created): + + ```bash + git fetch origin + git checkout + ``` + + Then start the application and test the high-contrast and light mode toggles in your browser to ensure they work as expected and persist across page reloads. + +Notice how the custom accessibility agent helped guide Copilot to implement these features following accessibility best practices. If you see any accessibility concerns or improvements, you can tag **@copilot** in a comment to request updates, just like you did with the previous PRs. + +## Optional exercise — keep delegating + +Cloud agent works best when you can hand it real backlog items and turn your attention elsewhere. To build the habit, file a few more issues against your repository and assign them to Copilot. Some ideas: + +- Create a backer interest form on the game details page. +- Implement pagination on the game list page. +- Add input validation and error handling to the data-access helpers. + +## Summary + +You completed the Cloud agent harness. Across these lessons you: + +- **Inspected the custom instruction files this repo ships with** so you could see their effect in cloud agent's output later. +- **Assigned issues to Copilot cloud agent** and watched it set up its environment, plan, and execute asynchronously. +- **Created and used a custom agent** for accessibility, adding high-contrast and light-mode toggles. +- **Used the Copilot agents page as mission control** to monitor and steer the accessibility session mid-flight. +- **Reviewed and iterated on cloud agent's pull requests**, tagging `@copilot` to request changes and approving workflows. + +## Review and next steps + +You've completed the Cloud agent harness. If you'd like to keep exploring, the other harnesses complement what you practiced here: + +- 🖥️ **[VS Code harness](/learning-hub/copilot-workshops/vscode/)** — explore Copilot Chat agent mode and MCP integration directly from your IDE. +- 💻 **[CLI harness](/learning-hub/copilot-workshops/cli/)** — work the same flows from your terminal with Copilot CLI: plan mode, agent skills, custom agents, and slash commands like `/delegate` to bridge back to the cloud agent you used here. + +In your own repository, try these follow-up ideas: + +- Assign a refactoring or test-coverage issue to cloud agent. +- Create a custom agent for another domain. +- Set up `copilot-setup-steps.yml` for a different stack. + +## Resources + +- [GitHub Copilot][github-copilot] +- [About Copilot agents][copilot-agents] +- [Assigning GitHub issues to Copilot][assign-issue] +- [Copilot cloud agent setup workflow best practices][cloud-agent-best-practices] +- [Configuring Copilot cloud agent firewall][agent-firewall] + +--- + +| [← Previous lesson: Managing agents][previous-lesson] | +|:--| + +[github-copilot]: https://github.com/features/copilot +[cloud-agent-overview]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[assign-issue]: https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions +[setup-workflow]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[copilot-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[cloud-agent-best-practices]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[agent-firewall]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-firewall + +[previous-lesson]: /learning-hub/copilot-workshops/cloud/4-managing-agents/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/cloud/index.md b/website/src/content/docs/learning-hub/copilot-workshops/cloud/index.md new file mode 100644 index 00000000..4cbe43ee --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/cloud/index.md @@ -0,0 +1,50 @@ +--- +title: "Copilot cloud agent" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +**[GitHub Copilot cloud agent](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent)** lets GitHub Copilot work asynchronously in the cloud. You assign work on GitHub, and the cloud agent picks it up in the background — exploring the repository, making changes, and opening a pull request — while you stay free to do other things. + +Across these exercises you'll add custom instructions the cloud agent will follow, then assign a GitHub issue and let it implement the work. You'll review and use custom agents to shape its approach, monitor and steer sessions from the agents dashboard, and finish by reviewing its pull requests and iterating on the results. + +## Exercises + +| Exercise | Topic | Description | +|----------|-------|-------------| +| [0. Prerequisites][ex0] | Setup | Create your repository and codespace | +| [1. Custom instructions][ex1] | Context | Add custom instructions cloud agent will follow | +| [2. Cloud Agent][ex2] | Async Agent | Assign issues to Copilot cloud agent | +| [3. Custom Agents][ex3] | Specialized Agents | Review and use custom agents | +| [4. Managing Agents][ex4] | Monitoring | Monitor and steer agent sessions | +| [5. Iterating][ex5] | Review | Review PRs, iterate on Copilot's work, and choose next steps | + +## Prerequisites + +Before attending this workshop, please ensure you have: + +- [ ] A GitHub account with an active **Copilot Student, Pro, Pro+, Business, or Enterprise** plan +- [ ] Copilot cloud agent enabled for your account or organization + +> [!TIP] +> No paid plan? Verified students can get GitHub Copilot for free through [GitHub Education][callout-student-plan-education]. The **Copilot Student** plan includes the agent, MCP, code review, and Copilot CLI features this workshop uses — so you can complete every harness with it. + +[callout-student-plan-education]: https://github.com/education/students + +> [!NOTE] +> Cloud agent is available on **Copilot Student, Pro, Pro+, Business, and Enterprise** — every plan except Copilot Free. On Copilot Business or Enterprise, an administrator must enable it for your organization. + +> [!NOTE] +> MCP isn't covered in this harness. To explore using MCP servers with Copilot, see the [CLI harness](/learning-hub/copilot-workshops/cli/) or the [VS Code harness](/learning-hub/copilot-workshops/vscode/). + +## Get Started + +**[Start with Exercise 0: Prerequisites →][ex0]** + +[ex0]: /learning-hub/copilot-workshops/cloud/0-prerequisites/ +[ex1]: /learning-hub/copilot-workshops/cloud/1-custom-instructions/ +[ex2]: /learning-hub/copilot-workshops/cloud/2-cloud-agent/ +[ex3]: /learning-hub/copilot-workshops/cloud/3-custom-agents/ +[ex4]: /learning-hub/copilot-workshops/cloud/4-managing-agents/ +[ex5]: /learning-hub/copilot-workshops/cloud/5-iterating/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/index.md b/website/src/content/docs/learning-hub/copilot-workshops/index.md new file mode 100644 index 00000000..8715796a --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/index.md @@ -0,0 +1,41 @@ +--- +title: "Hands-on with GitHub Copilot's agents" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +The recent additions to the capabilities of GitHub Copilot provide powerful tools to the developer across the entire software development lifecycle (SDLC). This includes working with issues and pull requests on GitHub, interacting with external services, and of course code creation. This lab explores the functionality, providing real-world use cases and tips on how to get the most out of the tools. + +> [!CAUTION] +> Because GitHub Copilot is probabilistic rather than deterministic, the exact code, files changed, etc., may vary. As a result, you may notice slight differences between screenshots and code snippets in the lab and your experience. This is to be expected, and is just the nature of working with this class of tools. +> +> If something appears broken or isn't running correctly, please ask a mentor! + +## Choose your harness + +GitHub Copilot meets you wherever you work. Pick the harness that matches how you want to build, and work through its exercises against a shared Tailspin Toys backlog. Each harness starts with its own setup, so you can dive straight into the one you choose. + +### 🖥️ [VS Code](/learning-hub/copilot-workshops/vscode/) + +GitHub Copilot inside **Visual Studio Code** and GitHub Codespaces. Work with Copilot Chat agent mode, MCP servers, and custom agents without leaving the editor you already use — ideal when you want AI assistance woven directly into your IDE. + +### 💻 [Copilot CLI](/learning-hub/copilot-workshops/cli/) + +**GitHub Copilot CLI** — an agentic assistant that runs in your terminal. Install it, connect MCP servers, generate code with plan mode, and build your own skills, custom agents, and slash commands, all from the command line. + +### 🤖 [Copilot App](/learning-hub/copilot-workshops/app/) + +The **GitHub Copilot app** — a desktop application built on Copilot CLI. Run parallel agent sessions, switch session modes, collaborate on canvases, and manage GitHub issues and pull requests natively — including **Agent Merge**, which shepherds a pull request through rebases, review feedback, CI fixes, and merge. + +### ☁️ [Copilot Cloud Agent](/learning-hub/copilot-workshops/cloud/) + +**Copilot cloud agent** — an asynchronous peer programmer that works on GitHub issues in the background. Assign work, guide it with custom agents, monitor progress from the agents dashboard, and review the pull requests it opens. + +## Scenario + +You are a new developer for Tailspin Toys, a fictional company who provides crowdfunding for board games with a developer theme - a huge market! Your team's backlog is already filed as GitHub issues, ready for you to pick up — feature work (like filtering and pagination) alongside quality improvements (like accessibility and coding standards). You'll work iteratively, exploring both the site and Copilot's capabilities, to complete the tasks. + +## Get started + +Choose your harness above to begin — each one opens with the setup it needs to get you building. diff --git a/website/src/content/docs/learning-hub/copilot-workshops/vscode/0-prerequisites.md b/website/src/content/docs/learning-hub/copilot-workshops/vscode/0-prerequisites.md new file mode 100644 index 00000000..aa86dfef --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/vscode/0-prerequisites.md @@ -0,0 +1,89 @@ +--- +title: "Exercise 0: Prerequisites" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Before you start the VS Code exercises, you need to get everything ready. You'll create your own copy of the Tailspin Toys repository, spin up a [codespace][codespaces] to work in, and confirm GitHub Copilot Chat is up and running in your editor. + +## Setting up the lab repository + +To create a copy of the repository for the code you'll create, you'll make an instance from the [template][template-repository]. The new instance will contain all of the necessary files for the lab, and you'll use it as you work through the exercises. + +1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/tailspin-toys`. +2. Create your own copy of the repository by selecting the **Use this template** button on the lab repository page. Then select **Create a new repository**. + + ![Use this template button](/images/learning-hub/copilot-workshops/ex0-use-template.png) + +3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to GitHub Copilot. + + ![Input the repository template settings](/images/learning-hub/copilot-workshops/ex0-repository-settings.png) + +4. Make a note of the repository path you created (**organization-or-user-name/repository-name**), as you will be referring to this later in the lab. + +> [!NOTE] +> **Your backlog is ready** +> +> When you create your repository from the template, a backlog of GitHub issues is created for you automatically. You'll work from these issues throughout the workshop — there's nothing to file yourself. +## Creating a codespace + +Next up, you'll use a codespace to complete the lab exercises. + +[GitHub Codespaces][codespaces] are a cloud-based development environment that allows you to write, run, and debug code directly in your browser. It provides a fully-featured IDE with support for multiple programming languages, extensions, and tools. + +1. Navigate to your newly created repository. +2. Select the green **Code** button. + + ![Select the Code button](/images/learning-hub/copilot-workshops/ex0-code-button.png) + +3. Select the **Codespaces** tab and select the **+** button to create a new Codespace. + + ![Create a new codespace](/images/learning-hub/copilot-workshops/ex0-create-codespace.png) + +The creation of the codespace will take several minutes, although it's still far quicker than having to manually install all the services! That said, you can use this time to explore other features of GitHub Copilot, which we'll turn your attention to next. + +> [!CAUTION] +> You'll return to the codespace in a future exercise. For the time being, leave it open in a tab in your browser. + +> [!NOTE] +> This workshop is built to run inside a codespace or local [dev container][dev-containers]. Both ensure the environment has all the necessary prerequisites installed for a smooth experience. If you'd prefer to run it locally, open the cloned repository in VS Code and select **Reopen in Container** when prompted — VS Code will build the same dev container the codespace uses. + +[codespaces]: https://github.com/features/codespaces +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers +## Using GitHub Copilot Chat and agent mode + +To access GitHub Copilot Chat agent mode, you need to have the GitHub Copilot Chat extension installed in your IDE, which should already be the case if you are using a GitHub Codespace. + +> [!TIP] +> If you do not have the GitHub Copilot Chat extension installed, you can [install it from the Visual Studio Code Marketplace][copilot-chat-extension]. Or open the Extensions view in Visual Studio Code, search for **GitHub Copilot Chat**, and select **Install**. + +Once you have the extension installed, you may need to authenticate with your GitHub account to enable it. + +1. Return to your codespace. +2. If you don't already see Copilot Chat on the right side of your editor, select the **Copilot Chat** icon at the top of your codespace. +3. Type a message like "Hello world" in the Copilot Chat window and press enter. This should activate Copilot Chat. +4. Alternatively, if you are not authenticated you will be prompted to sign in to your GitHub account. Follow the instructions to authenticate. + + ![Example of Copilot Chat authentication prompt](/images/learning-hub/copilot-workshops/ex1-copilot-authentication.png) + +5. After authentication, you should see the Copilot Chat window appear. + +## Summary + +Congratulations, you have created a copy of the lab repository! You also began the creation process of your codespace, which you'll use when you begin writing code. + +## Next step + +Let's start putting Copilot to work. Continue to [Exercise 1 - Custom instructions][next-lesson], where you'll teach Copilot your project's conventions. + +## Resources + +- [GitHub Codespaces overview][codespaces] +- [Creating a repository from a template][template-repository] +- [Getting started with Codespaces][codespaces-quickstart] + +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[codespaces-quickstart]: https://docs.github.com/codespaces/getting-started/quickstart +[copilot-chat-extension]: https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat +[next-lesson]: /learning-hub/copilot-workshops/vscode/1-custom-instructions/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/vscode/1-custom-instructions.md b/website/src/content/docs/learning-hub/copilot-workshops/vscode/1-custom-instructions.md new file mode 100644 index 00000000..b098abff --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/vscode/1-custom-instructions.md @@ -0,0 +1,250 @@ +--- +title: "Exercise 1 - Custom instructions (VS Code)" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +[← Previous lesson: Prerequisites][previous-lesson] · [Next lesson: Agent mode →][next-lesson] + +Context is key when working with generative AI. If a task needs to be done a particular way — or there's background information Copilot should know — you want to make sure that context is reachable. There are several ways to share specific context with Copilot. Key among these is [instruction files][instruction-files], which are how you provide that guidance about code generation. + +In this exercise, you will: + +- explore how project-specific context, coding guidelines, and documentation standards reach Copilot through repository custom instructions and path-scoped instruction files, +- generate the first data slice for filtering (a publishers helper) with the *current* instructions in place, +- add a new repository-wide standard to `.github/copilot-instructions.md`, +- re-run the same prompt and watch the generated code adopt the new standard, +- commit the instructions update and filtering slice to `main` so Copilot can use the updated guidance in the next exercise. + +> [!CAUTION] +> Generated code may diverge from some of the standards you set. Copilot is non-deterministic. The point of this exercise is to see the *trend* in behavior change after updating the instructions, not to match output character-for-character. + +## Instruction files + +### Scenario + +As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include: + +- The data layer always needs unit tests. +- UI should be in dark mode and have a modern feel. +- Documentation should be added to code in the form of TSDoc doc comments. +- A block of comments should be added to the head of each file describing what the file does. + +Through the use of instruction files you'll ensure Copilot has the right information to perform the tasks in alignment with the practices highlighted. + +### Custom instructions + +Custom instructions allow you to provide context and preferences to Copilot, so that it can better understand your coding style and requirements. This is a powerful feature that can help you steer Copilot to get more relevant suggestions and code snippets. You can specify your preferred coding conventions, libraries, and even the types of comments you like to include in your code. You can create instructions for your entire repository, or for specific types of files for task-level context. + +There are two types of instructions files: + +- `.github/copilot-instructions.md`, a single instruction file sent to Copilot for **every** request for the repository. This file should contain project-level information — context relevant for most chat or CLI requests sent to Copilot. This could include the tech stack being used, an overview of what's being built, best practices, and other global guidance. +- `.github/instructions/*.instructions.md` files can be created for specific tasks or file types. You can use them to provide guidelines for particular languages (like TypeScript or Astro), or for tasks like creating a UI component or a new set of unit tests. + +> [!NOTE] +> When working in your IDE, instructions files are only used for code generation in Copilot Chat — not for code completions or next-edit suggestions. +> +> Copilot Chat, Copilot CLI and Copilot cloud agent use both repository-level and `*.instructions.md` files (with `applyTo` front matter) when generating code. +> +> Finally, Copilot [supports instructions files using other standards][custom-instructions-support], including AGENTS.md and CLAUDE.md files. + +### Best practices for managing instructions files + +A full conversation about creating instructions files is beyond the scope of the workshop. However, the examples provided in the sample project show a representative approach. At a high level: + +- Keep instructions in `copilot-instructions.md` focused on project-level guidance, such as a description of what's being built, the structure of the project, and global coding standards. +- Use `*.instructions.md` files to provide specific instructions for file types (unit tests, Astro components, the data layer), or for specific tasks. +- Use natural language. Keep guidance clear. Provide examples of how code should (and shouldn't) look. + +There isn't one specific way to create instructions files, just as there isn't one specific way to use AI. You will find through experimentation what works best for your project. + +> [!TIP] +> Every project using GitHub Copilot should have a robust collection of instruction files. As you explore the ones in this project, you may notice there are files for numerous types of tasks, including [UI updates][ui-instructions] and [Astro][astro-instructions]. +> +> Copilot can also help generate instruction files for you. Each surface exposes this differently (for example, **Configure Chat → Generate Agent Instructions** in VS Code, or `/init` in Copilot CLI) — the lesson for the surface you're on will call it out where it's relevant. +> +> Looking for templates or a starting point? Explore [awesome-copilot][awesome-copilot], a repository full of instruction files, custom agents, and other resources. + +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[awesome-copilot]: https://github.com/github/awesome-copilot +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +## Explore the custom instructions files in this project + +Take a moment to read the instruction files this repository ships with — there's one core `copilot-instructions.md` and a collection of `*.instructions.md` files for various tasks. Open these in your editor or the GitHub web UI. + +1. Open `.github/copilot-instructions.md`. +2. Explore the file, noting the brief description of the project plus sections such as **Agent notes**, **Code standards**, **Scripts**, and **Repository Structure**. Under **Code standards**, note the nested **GitHub Actions Workflows** guidance. These are applicable to any interactions you'd have with Copilot. +3. Open the `.github/instructions` folder and look around. Note there are instructions for Astro files, the Drizzle data layer, tests, and more. +4. Open `.github/instructions/unit-tests.instructions.md`. Note the `applyTo` field at the top — this sets a glob (relative to the repo root) that determines which files the instructions apply to. Here, any TypeScript test file (for example, one matching `**/*.test.ts`) will match. +5. Note the instructions specific to creating unit tests for this project. +6. Finally, open `.github/instructions/drizzle.instructions.md` and scroll to the bottom. Note the links to other instruction files (like `unit-tests.instructions.md`) and existing files in the project. This lets you break larger instruction sets into smaller, reusable files, and point Copilot at examples to follow when generating code. (Paths there are relative to the instruction file rather than the repo root.) + +> [!NOTE] +> The **Code formatting requirements** section in `copilot-instructions.md` documents the project's coding standards, but it doesn't yet require in-code documentation. In the next steps, you'll add rules for TSDoc doc comments and file comment headers. +## Create a branch for our changes + +Let's follow some best practices here and create a branch for our changes. + +1. Return to your codespace from the previous exercise. +2. Open a new terminal by selecting Ctrl+`. +3. Create and switch to a new branch: + + ```bash + git checkout -b custom-instructions + ``` + +## Use Copilot Chat *before* updating the instructions + +> [!TIP] +> **Open Copilot Chat** +> +> Before you start the exercises below, return to your codespace, open the Copilot Chat panel, and select **New Chat** to start a clean conversation. Mode and model selection vary per exercise — each step calls those out where it matters. +To see the impact of custom instructions, start by sending a prompt with the current instruction file in place. Later, you'll update it and re-send the same prompt to see the difference. + +1. Close any open editor tabs from previous exercises so Copilot picks up only the context you want. +2. Open `src/lib/publishers.ts` so Copilot knows where the helper should live. +3. Select **Agent** from the agents dropdown in the Chat view so Copilot can apply file changes. + + ![Screenshot showing the agent picker in the Chat view.](/images/learning-hub/copilot-workshops/shared-chat-mode-selector.png) + +4. Send the following prompt: + + ```plaintext + Create or update src/lib/publishers.ts with a data-access helper that returns a list of all publishers with the name and id for each. Apply the file changes. + ``` + +5. Copilot explores the project and applies code updates, often spanning the helper file and its tests. +6. Notice the proposed helper is a typed function that takes a `db` client as its first argument and returns a typed array of publishers — that's coming from the data-layer conventions in `.github/instructions/drizzle.instructions.md` (which applies to `src/lib/*.ts`). +7. Notice the proposed code **is missing** TSDoc doc comments and a file-level comment header. + +> [!CAUTION] +> Because Copilot is probabilistic, there's a chance it'll add doc comments even without being told to. If that happens, that's fine — the *consistency* improvement after the instruction update is still the point. + +## Add a new repository standard + +As highlighted previously, `.github/copilot-instructions.md` is designed to provide project-level information to Copilot. Let's ensure repository coding standards are documented to improve code suggestions. + +1. Re-open `.github/copilot-instructions.md`. +2. Locate the **Code formatting requirements** section, which should be near line 27. Note how it documents the project's coding standards — but it has no rule yet for in-code documentation, which is why the generated helper had no doc comments. +3. Add the following lines of markdown right below the existing standards to instruct Copilot to add file comment headers and TSDoc doc comments: + + ```markdown + - Every exported function should have a TSDoc comment describing its purpose, parameters, and return value. + - Before imports or any code, add a comment block to the file that explains its purpose. + ``` + +4. Save `copilot-instructions.md`. + +> [!TIP] +> As you saw in the previous lesson, instruction files can be created at the repository level (`.github/copilot-instructions.md`) for global guidance, or as `*.instructions.md` files for specific languages, file types, or tasks. The repository-level file is the right home for project-wide standards like the doc comment rule you just added. +## Re-run the prompt and observe the change + +1. Return to Copilot Chat and select **New Chat** to clear the buffer. +2. Click back into `src/lib/publishers.ts` so Copilot focuses on the right file. +3. Send the **same prompt** as before: + + ```plaintext + Create or update src/lib/publishers.ts with a data-access helper that returns a list of all publishers with the name and id for each. Apply the file changes. + ``` + +4. Notice that the proposed file now opens with a comment block similar to: + + ```typescript + /** + * Publisher data-access helpers for the Tailspin Toys Crowd Funding platform. + * Provides functions to retrieve publisher information from the database. + */ + ``` + +5. Notice that the proposed function now includes a TSDoc comment similar to: + + ```typescript + /** + * Returns a list of all publishers with their id and name. + * + * @param db - The Drizzle database client. + * @returns A promise that resolves to an array of publisher objects. + */ + ``` + +You just steered Copilot to follow a new project standard and apply it to real code that the next exercise will build on. + +## Commit the instructions and push the branch + +Instructions files are just like any asset in the repository, meaning they're managed using the same source control approach you'd take with any other item. So let's commit and push the branch to our repository. + +1. Open a new terminal window in your codespace by selecting Ctrl+\`. +2. From the terminal, confirm your instructions update and helper changes are present by running: + + ```bash + git status + ``` + +3. From the terminal, stage and commit the instructions update and every file Copilot changed for the helper foundation: + + ```bash + git add .github/copilot-instructions.md src/lib/publishers.ts + # If git status shows additional supporting updates (for example tests), add those files too. + git commit -m "Add doc comment standards and publishers helper foundation" + ``` + +4. From the terminal, push the branch to the repository: + + ```bash + git push -u origin custom-instructions + ``` + +## Create and merge a pull request + +With our branch pushed, we should create a pull request and tie it to the documentation-standard issue in your backlog. We could manually do that, but Copilot can do it on our behalf using the GitHub tools that are already connected to your project. Let's prompt Copilot to find the issue, create the PR to close the issue, and then merge it. + +> [!NOTE] +> This is the first exercise that has Copilot act on GitHub for you. The project template already wires GitHub's tools into your workspace, so there's nothing to set up — the first time Copilot uses one, VS Code may prompt you to sign in to GitHub. Follow the prompts to allow it. You'll learn how this connection works (Model Context Protocol) in a later exercise. + +1. Open Copilot Chat inside of your codespace. +2. Select Control+Command+I (Mac) or Ctrl+Alt+I (Windows/Linux) to open the Copilot Chat view, and ensure **Agent** is selected from the agent picker. +3. Ask Copilot to find the issue related to updating instructions files and create a PR from the current branch that describes both the instructions updates and the new publishers helper foundation: + + ``` + Find the issue related to updating the instructions file. Create a new PR from the current branch, highlight that the PR closes that issue, and include that we also added the publishers helper foundation for the upcoming filtering work. + ``` + +4. Copilot will begin work on finding the issue and creating the PR. +5. As prompted to **Allow** Copilot to perform GitHub actions on your behalf, review the command and select **Allow** as appropriate. +6. Once the PR is created, ask Copilot to merge the PR and to return your branch to main by using the following prompt: + + ``` + Merge the PR into main. Then return to main locally, and pull the latest code so we are up to date. + ``` + +7. As prompted to **Allow** Copilot to perform GitHub actions and run shell commands on your behalf, review the command and select **Allow** as appropriate. + +You have now created and merged a pull request with the help of GitHub Copilot! + +## Summary and next steps + +You explored how Copilot picks up context from instruction files in this project, then used Copilot Chat in VS Code to: + +- send a code-generation prompt and observe what Copilot produces with the *existing* instructions, +- add a new repository-wide standard to `.github/copilot-instructions.md`, +- re-run the same prompt and watch the proposed code adopt the new standard, +- commit the instructions update and helper foundation to `main` so the next exercise can build on them. + +Next, you'll put those instructions to work in [agent mode][next-lesson] as Copilot adds a new feature across the codebase. + +## Resources + +- [Instruction files for GitHub Copilot customization][instruction-files] +- [Best practices for creating custom instructions][instructions-best-practices] +- [5 tips for writing better custom instructions for Copilot][copilot-instructions-five-tips] +- [Personal custom instructions for GitHub Copilot][personal-instructions] +- [Awesome Copilot — a collection of instruction files and other resources][awesome-copilot] + +[previous-lesson]: /learning-hub/copilot-workshops/vscode/0-prerequisites/ +[next-lesson]: /learning-hub/copilot-workshops/vscode/2-agent-mode/ +[instruction-files]: https://code.visualstudio.com/docs/copilot/copilot-customization +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[personal-instructions]: https://docs.github.com/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot +[copilot-instructions-five-tips]: https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/ diff --git a/website/src/content/docs/learning-hub/copilot-workshops/vscode/2-agent-mode.md b/website/src/content/docs/learning-hub/copilot-workshops/vscode/2-agent-mode.md new file mode 100644 index 00000000..2e301737 --- /dev/null +++ b/website/src/content/docs/learning-hub/copilot-workshops/vscode/2-agent-mode.md @@ -0,0 +1,198 @@ +--- +title: "Exercise 2 - Adding new functionality with Copilot Agent Mode" +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: 2026-08-03 +--- + +Even the simplest of updates to an application typically require updates to multiple files and operations to be performed like running tests. As a developer your flow typically involves tracking down all the necessary files, making the changes, running the tests, debugging, figuring out which file was missed, making another update... The list goes on and on. + +This is where Copilot Agent Mode comes into play. + +Copilot Agent Mode is built to act more autonomously in your IDE. It behaves in a similar fashion to a developer, starting by exploring the existing project structure, performing the necessary updates, running tasks like tests, and automatically fixing any discovered mistakes. Let's explore how you can use Agent Mode to introduce new functionality to your site. + +> [!NOTE] +> While the names are similar, agent mode and cloud agent are built for two different types of experiences. Agent mode performs its tasks in your IDE, allowing for quick feedback cycles and interaction. Cloud agent is designed as a peer programmer, working asynchronously like a member of the team, interacting with you via issues and pull requests. + +In this exercise, you will learn how: + +- Copilot Agent Mode can explore your project, identify relevant files, and make coordinated changes. +- GitHub Copilot Agent Mode can implement new features across the UI and data layer. +- to review changes and tests generated by Copilot Agent Mode before merging into your codebase. + +## Scenario + +As the list of games grows, you want to allow users to filter by category and publisher. You already added a publishers helper in the previous exercise, and now you'll finish the remaining data-layer, UI, and test work with Copilot Agent Mode. + +## Running the Tailspin Toys website + +Before you make any changes, let's explore the Tailspin Toys website to understand its current functionality. + +The website is a crowdfunding platform for board games with a developer theme. It allows users to list games and display details about them. The website is a single Astro app that renders its pages as static HTML at build time. Pages query a local SQLite database directly in their frontmatter through Drizzle ORM — there's no separate backend API or client-side UI framework. Reusable data-access helpers live in `src/lib/`, and any interactivity is added with a small, scoped Astro `