diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7761a4f..7bec581 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,6 +10,7 @@ This repo hosts the **workshop content** for *Agents in SDLC*, published as an A - `src/content/docs/` — **Source Markdown for all lessons. Edit here.** - `index.md` — Workshop landing page. - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / Cloud agent / GitHub Copilot app). Each harness opens with its own `0-prerequisites.md` setup lesson; the CLI and VS Code harnesses set up a codespace, while the app and cloud harnesses cover the setup their flow needs (for the app, installing Node.js locally and creating the project from the template). + - `es-es/`, `ja-jp/`, `ko-kr/`, `pt-br/`, `zh-cn/` — Localized content at the locale-root paths required by Starlight. Translated pages mirror the English path beneath each locale directory; untranslated pages use Starlight's English fallback. - `_images/` — Screenshots and diagrams. - `astro.config.mjs` — Site config including the manually maintained sidebar. The legacy `/shared/0-prereqs/` → home (`/`) redirect is a full-HTML redirect page at `src/pages/shared/0-prereqs.astro` (not an `astro.config.mjs` `redirects` entry, which would emit a stub with no `` element that Pagefind can't index). Prerequisites are now per-harness (`//0-prerequisites/`), so the old shared-prereqs URL forwards to the home page. - `src/content.config.ts` — Custom content loader that excludes underscore-prefixed support directories so `_images/` is not routed as content. diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md index 46fc41f..b256183 100644 --- a/.github/instructions/astro.instructions.md +++ b/.github/instructions/astro.instructions.md @@ -20,4 +20,4 @@ This is a docs wrapper. Don't add interactive framework islands (Svelte, React, ## Building and verifying -After changing `astro.config.mjs` or anything under `docs/src/`, build and verify the site with the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill. Its page-count invariant is the tripwire for unexpected routed pages: if the build emits more pages than `36 routable Markdown pages + 1 legacy redirect` without a matching content change, check the underscore-directory exclude in `src/content.config.ts`. +After changing `astro.config.mjs` or anything under `docs/src/`, build and verify the site with the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill. Its page-count invariant is the tripwire for unexpected routed pages: Starlight emits each of the 36 workshop routes for the root language and five configured locales, then adds the legacy redirect, for 217 built `index.html` pages excluding the 404 page. If the count changes without a corresponding route or locale change, check the locale layout and the underscore-directory exclude in `src/content.config.ts`. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 08672d5..98b7e0f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -16,7 +16,7 @@ -- [ ] `cd docs && rm -rf dist && npm run build` succeeds (target: 36 routable pages + 1 redirect = 37 built pages excluding 404; build reports 38 HTML files including 404, or note any intentional change) +- [ ] `cd docs && rm -rf dist && npm run build` succeeds (target: 36 routes × 6 locales + 1 redirect = 217 built pages excluding 404; build reports 218 HTML files including 404, or note any intentional change) - [ ] Lychee link check passes: `mkdir -p /tmp/lychee-root && ln -sfn $PWD/docs/dist /tmp/lychee-root/agents-in-sdlc && lychee --offline --no-progress --root-dir /tmp/lychee-root 'docs/dist/**/*.html'` - [ ] External GitHub URLs that I changed have been clicked manually (lychee runs offline) diff --git a/.github/skills/build-and-verify-docs/SKILL.md b/.github/skills/build-and-verify-docs/SKILL.md index f6b2811..47cb2ca 100644 --- a/.github/skills/build-and-verify-docs/SKILL.md +++ b/.github/skills/build-and-verify-docs/SKILL.md @@ -43,16 +43,21 @@ cd docs && rm -rf dist && npm run build ### 2. Page-count invariant -The built page count should equal the 36 routable `.md` files under `docs/src/content/docs/` plus the one legacy redirect (`/shared/0-prereqs/`, authored as a full-HTML redirect page at `docs/src/pages/shared/0-prereqs.astro`). The expected count is 37 `index.html` files when excluding the 404 page. Astro reports 38 HTML files because it includes the 404 page. +The workshop has 36 distinct route slugs. Starlight emits each route for the English root locale and the five configured localized routes, using English fallback content when a translation is unavailable. The built site therefore contains $36 \times 6 = 216$ workshop routes plus the one legacy redirect (`/shared/0-prereqs/`, authored as a full-HTML redirect page at `docs/src/pages/shared/0-prereqs.astro`). The expected count is 217 `index.html` files when excluding the 404 page. Astro reports 218 HTML files because it includes the 404 page. ```bash -# routable Markdown pages (expected pages, minus the redirect) -find docs/src/content/docs -name '*.md' | wc -l +# distinct route slugs in the English root locale +find docs/src/content/docs -maxdepth 2 -name '*.md' \ + ! -path 'docs/src/content/docs/es-es/*' \ + ! -path 'docs/src/content/docs/ja-jp/*' \ + ! -path 'docs/src/content/docs/ko-kr/*' \ + ! -path 'docs/src/content/docs/pt-br/*' \ + ! -path 'docs/src/content/docs/zh-cn/*' | wc -l # built pages (excludes the 404) find docs/dist -name index.html | grep -v 404 | wc -l ``` -`built pages` should equal `routable Markdown pages + 1`. If the build emits **more** pages than that without a matching `.md` change, check the underscore-directory exclude in `docs/src/content.config.ts`; it is still needed so support directories such as `_images/` are not routed as pages. +`built pages` should equal `(distinct route slugs × configured locales) + 1`. If the build emits **more** pages than that without a matching route or locale change, confirm localized content is directly under `docs/src/content/docs//` rather than an extra parent directory, then check the underscore-directory exclude in `docs/src/content.config.ts`; it is still needed so support directories such as `_images/` are not routed as pages. ### 3. Link check (lychee, offline) diff --git a/.github/skills/localizations/SKILL.md b/.github/skills/localizations/SKILL.md new file mode 100644 index 0000000..1cf27f0 --- /dev/null +++ b/.github/skills/localizations/SKILL.md @@ -0,0 +1,101 @@ +--- +name: localizations +description: A skill that localizes contents into given locales. +--- + +# Localize contents into given locales + +A skill that localizes contents into given locales. + +## How it works + +The skill takes input content and a list of target locales. It then translates the content into each specified locale, providing localized versions for each. + +### Content structure + +```text +. +├── README.md +├── docs/ +│ ├── *.md +│ └── / +│ └── *.md +└── docs/ + └── src/content/docs/ + └── / + ├── index.md + └── / + └── *.md +``` + +### Input contents + +Here are the list of contents for localization: + +- `README.md`: The main documentation file for the project. +- All markdown files in the `docs` directory **and its subdirectories** (`docs/**/*.md`): The main content files for the project documentation. + +Both `README.md` and the `docs` tree are in scope. The **`docs`** directory is the default location for content files, but `README.md` at the project root is always included as well. + +Files already under `docs/src/content/docs//` are **outputs**, not inputs—never treat configured locale-root directories as source content to be localized again. + +### Target locales + +Target locales are defined in the `rules` directory as markdown files in this skill (`rules/ko-kr.md`, for example). **To determine which locales to process, list the files in `rules/`: each `.md` file corresponds to exactly one supported target locale.** Each locale has its own set of rules and guidelines for translation, ensuring that the localized content is appropriate for the target audience. + +Locale identifiers use lowercase with a hyphen (for example, `ko-kr`). This is the canonical casing for both the rules filename and the output directory in this skill; keep them consistent. + +### Output contents + +All localized workshop content is stored directly under the Starlight content root, with each locale having its own subdirectory. For example, Korean content is stored in `docs/src/content/docs/ko-kr/`. + +Locale directories must be direct children of `docs/src/content/docs/` so Starlight recognizes them and renders its language selector. Do not add an intermediate `localizations/` directory. + +## Localization process + +There are three cases for localization. To detect which case applies, compare the **source tree** against the existing `docs/src/content/docs//` tree, and use the **git history of the source files** to detect changes: + +- **Original exists, no localized version for the locale:** Create a new localized document. +- **Both original and localized versions exist:** Compare the source tree against `docs/src/content/docs//`, then run `git diff` (or `git log`) on the **source** file to find what changed since the localized version was last produced. Update only the affected sections of the localized document; do not re-translate unchanged sections unnecessarily. +- **Localized version exists, but the original has been deleted:** Delete the orphaned localized document (and prune now-empty locale subdirectories). + +The process runs in two passes. First, the content is analyzed to identify key phrases and context. Then the `translator` agent performs the initial localization, followed by a review-and-refinement pass by the `evaluator` agent to ensure quality and consistency. + +> The `translator` and `evaluator` "agents" are **roles/personas**, not external tools. If no dedicated sub-agents are available, perform them as sequential personas: first adopt the translator role to produce the draft, then adopt the evaluator role to critique and refine that draft against the locale rules. Repeat the refinement loop until the evaluator's criteria pass. + +### Markdown and formatting preservation + +Regardless of locale, the following must be preserved exactly and **not** translated: + +- YAML frontmatter **keys** (translate values only where appropriate, e.g. a `title`). +- Fenced and inline code, including variable, function, and command names. +- URLs and external link targets. +- HTML tags, Markdown structure, tables, and admonition markers. + +Translate human-language prose, including comments inside code blocks where they are explanatory (per the locale rules). Keep heading order and document structure stable. + +**Heading anchors follow the localized text.** When a heading is translated, its auto-generated anchor/slug changes with it—this is expected. The requirement is that **same-document anchor links keep resolving**: whenever you translate a heading, update every in-page link that targets it (`](#...)`) to the localized heading's new slug. Do not leave a link pointing at the original English slug once the heading is translated, and do not preserve an English anchor that no longer matches its heading. Anchors that point into **non-localized** files (or external URLs) keep their original target. + +**Image and asset paths point to the original assets unless a localized asset exists.** Because localized files live under `docs/src/content/docs//`, rewrite source-relative paths as needed so they still resolve to the shared asset (for example, an app lesson uses `../../_images/x.png`). Only point at a localized asset when a corresponding translated image actually exists under the locale tree. Either way, the link must resolve to a real file. + +### Translator agent + +Use the `translator` agent to perform the localization. It should follow the rules and guidelines defined for each target locale document in the `rules` directory. + +### Evaluator agent + +Use the `evaluator` agent to assess the quality of the localized content. The evaluator checks for accuracy, cultural relevance, and overall quality, following the rules and guidelines defined for the target locale in the `rules` directory. + +The evaluator scores the localized document against the locale's **Evaluator Scoring Rubric** (defined in the locale's `rules/.md`). The rubric uses two tiers: **Tier A** hard-fail criteria that must score 5, and **Tier B** graded criteria (1–5) that must score 4 or 5. A document passes only when **every applicable Tier A criterion scores 5 and every applicable Tier B criterion scores ≥ 4**. If anything falls short, return the document to the translator with specific notes and re-run the translate → evaluate loop until it passes, escalating to a human after the rubric's iteration cap. + +## DOs and DON'Ts + +- **Do** perform localization only for the target locales defined in the `rules` directory (one `.md` per supported locale). Do not localize into unsupported locales. +- **Do** preserve Markdown structure, code, external link/URL targets, and frontmatter keys exactly (see *Markdown and formatting preservation*). +- **Do** let heading anchors follow the localized heading text, and update same-document anchor links to match the new slugs so they keep resolving (see *Markdown and formatting preservation*). +- **Do** point image and asset paths at the original assets (rewriting the relative path as needed so it resolves from `docs/src/content/docs//`), unless a corresponding localized asset exists (see *Markdown and formatting preservation*). +- **Do** mirror the source directory layout under `docs/src/content/docs//`. +- **Don't** treat configured locale-root directories as source input. +- **Don't** reorder or restructure content; keep headings and their order stable. +- **Don't** translate code, commands, or identifiers; translate explanatory prose and code comments only. + diff --git a/.github/skills/localizations/rules/es-es.md b/.github/skills/localizations/rules/es-es.md new file mode 100644 index 0000000..a453dc5 --- /dev/null +++ b/.github/skills/localizations/rules/es-es.md @@ -0,0 +1,129 @@ +# es-es + +These rules apply to **both roles**: the `translator` agent uses them as generation directives (how to write the Spanish text), and the `evaluator` agent uses them as review criteria (what to check and flag). Wherever a rule says "flag" or "look for", the translator should read it as "produce text that satisfies this". + +In general, producing and evaluating translation quality requires both accuracy of meaning and natural flow. Verify that the text passes core tests for accuracy, fluency, consistency, and cultural appropriateness. + +The four core pillars are: + +- **Accuracy:** Preserve the source meaning exactly, without additions, distortions, or omissions. +- **Fluency:** Follow Spanish grammar, spelling, punctuation, and idiom so the text reads as native European Spanish. +- **Terminology & Consistency:** Use specialized terms, names, and recurring phrases uniformly. +- **Cultural Appropriateness:** Adapt idioms, examples, register, and regional vocabulary for readers in Spain. + +## English to Spanish (Spain) Localization Scenario + +English-to-Spanish translation quality is best evaluated by checking grammatical agreement, idiomatic sentence structure, consistent treatment of the reader, and terminology appropriate to Spain. Avoid both English calques and unintended Latin American or European Portuguese usage. + +### Key Evaluation Pillars for Spanish (Spain) + +- **Regional Standard:** Use `es-ES` vocabulary and conventions. Prefer forms understood naturally in Spain, such as **archivo**, **ordenador/equipo**, **hacer clic**, **iniciar sesión**, and **correo electrónico**, according to context. +- **Reader Address and Register:** For technical documentation, use a professional, direct style. Prefer impersonal constructions or a consistent second-person singular treatment. Do not alternate between **tú**, **usted**, and plural forms within a document. +- **Grammatical Agreement:** Verify gender, number, articles, contractions (`al`, `del`), clitic pronouns, and adjective agreement, especially around untranslated product names and code terms. +- **Natural Syntax:** Restructure dense English noun stacks and repeated possessives. Spanish generally needs prepositions or subordinate clauses rather than long sequences of nominal modifiers. +- **Punctuation:** Use opening and closing question/exclamation marks (`¿?`, `¡!`) and Spanish punctuation rules. Do not insert English-style capitalization after a colon unless the following text independently requires it. + +### Common Translation Mistakes to Flag + +- **English Calques:** Flag literal renderings such as *aplicar para* for "apply for", *correr un programa* for "run a program", or unnecessary passive constructions. Prefer **solicitar**, **ejecutar un programa**, and natural active or `se` constructions. +- **False Friends:** Check terms such as *actual*, *eventually*, *library*, and *support*. Depending on context, use **real/actual**, **finalmente**, **biblioteca**, and **compatibilidad/asistencia**, not misleading cognates. +- **Gerund Misuse:** Do not use the gerund to express a later result or as an English-style adjective. Use a finite verb or relative clause. +- **Possessive Overuse:** English repeats "your" and "its" more often than Spanish. Omit possessives when the referent is clear, but preserve ownership where it affects meaning. +- **Regional Mixing:** Flag unexplained switching between Spain-specific and other regional forms, such as **ordenador/computadora** or **vosotros/ustedes**, when it makes the voice inconsistent. + +### Practical Evaluation Framework + +| Evaluation Metric | What to Look For (English to Spanish Context) | +| :--- | :--- | +| **Accuracy (exactitud)** | Are every fact, condition, number, name, and logical relationship preserved? | +| **Fluency (fluidez)** | Would a reader in Spain understand each sentence immediately without detecting English syntax? | +| **Style Guide (estilo)** | Are agreement, accents, punctuation, capitalization, and regional conventions correct? | + +## Markdown Syntaxes + +Keep Markdown delimiters attached to the text they format, while placing Spanish punctuation outside or inside the formatted span according to what is semantically emphasized. Do not allow translated punctuation or articles to enter URLs, code spans, or link targets. + +- Correct: `Consulta la [**documentación de Node.js**](https://nodejs.org/).` +- Incorrect: `Consulta la **[documentación de Node.js](https://nodejs.org/).**` when the final period is not part of the link text. + +When a translated heading changes its generated slug, update every same-document link to the localized anchor. Preserve external URLs exactly. + +## Localization for Technical Documents for Developers + +Spanish developer documentation should be precise and concise. Translate established concepts when the Spanish term is conventional, but retain product names, API names, identifiers, commands, and widely recognized technology terms when translating them would reduce clarity. + +### Developer-Specific Evaluation Rules + +#### Terminology and English Terms + +- Use established equivalents such as **cadena** (String, when discussing the data type conceptually), **matriz/arreglo** according to the product glossary, **dependencia**, **subproceso/hilo**, **instancia**, and **repositorio**. Do not vary synonyms casually within one file. +- Keep recognized forms such as **API**, **SDK**, **framework**, **runtime**, product names, and protocol names when that is the normal developer usage or the product glossary requires it. +- For critical or unfamiliar jargon, the first occurrence in a file may include the English source term in parentheses when it improves lookup, for example, **entorno de ejecución (runtime)**. Apply this selectively. +- Keep variables, function names, APIs, CLI commands (`npm install`), file names, and code exactly as in the source. Translate only human-language comments and explanatory prose inside code blocks. + +#### Tone and Instructions + +- Use concise professional prose. Prefer direct instructions such as **Ejecuta el comando siguiente** or an impersonal pattern such as **Ejecute el comando siguiente**, but select one treatment and keep it consistent. +- Avoid unnecessary courtesy formulas and repeated reader pronouns. Do not make instructions less direct by padding them with **por favor**. +- Preserve distinctions among requirements (**debe**), recommendations (**se recomienda/debería**), and possibilities (**puede**). Never weaken or strengthen normative language. + +#### Syntactic Readability for Code Logic + +- Put prerequisites and conditions before outcomes when that improves comprehension: **Si falta la clave, se produce un error.** +- Treat variables as grammatical units without changing them: **Aquí, `userId` identifica al usuario.** +- Avoid ambiguous pronouns after sentences containing several possible antecedents; repeat the precise noun where needed. + +### Quick Quality Checklist for Developer Docs + +| What to Flag (Bad) | What to Approve (Good) | Why it Matters | +| :--- | :--- | :--- | +| **"corre `npm install`"** | **"ejecuta `npm install`"** | Avoids an English calque while preserving the command. | +| **"la librería carga sus dependencias"** when ownership is unclear | **"la biblioteca carga las dependencias"** | Uses conventional terminology and avoids an ambiguous possessive. | +| Switching between **tú** and **usted** | One consistent treatment | Keeps the documentation voice stable. | +| Translating `StringBuilder` | Keeping `StringBuilder` unchanged | Preserves the identifier exactly. | + +## Evaluator Scoring Rubric + +This is the **definitive pass/fail gate** for the `evaluator` role. Criteria are split into two tiers: + +- **Tier A — Hard-fail criteria:** any material defect makes the document unusable, so these **must score 5 to pass**. +- **Tier B — Graded criteria:** scored on the 1–5 scale below; these **pass at 4 or 5**. + +A document **PASSES only when every applicable Tier A criterion scores 5 and every applicable Tier B criterion scores 4 or 5.** Otherwise it FAILS and is returned to the translator with specific notes that cite the offending source/target snippets and criterion. If the same subjective criterion still fails after **3 iterations**, escalate to a human. + +Tier B scale: + +- **5 — Excellent:** Fully meets the criterion; no issues. +- **4 — Good (pass):** At most 1–2 trivial, non-blocking nits per ~1,000 words. +- **3 — Borderline (fail):** Several noticeable issues, or any issue that changes how a sentence reads. +- **2 — Poor (fail):** Frequent or significant violations. +- **1 — Unacceptable (fail):** The criterion is largely unmet. + +### Determining Content Type + +- **Technical documentation** is content for developers/operators or any document containing code, commands, or API identifiers. Criteria 7–8 apply. +- **Non-technical content** is UI, marketing, narrative, or conversational copy without code. Criteria 7–8 do not apply, and Criterion 4 uses the audience-appropriate register. + +If otherwise non-technical content contains occasional code or links, Criterion 2 and Criterion 7 still apply to those spans. + +### Tier A — Hard-Fail Criteria (Must Score 5) + +| # | Criterion | Passes (5) when… | Fails (<5) when… | +| :-- | :--- | :--- | :--- | +| 1 | **Accuracy (exactitud)** | Meaning matches the source exactly; all facts, numbers, names, conditions, and modality are preserved. | Any mistranslation, negation flip, fabricated/dropped fact, altered number/name, or changed requirement level occurs. | +| 2 | **Markdown & Structural Integrity** | Frontmatter keys, Markdown, tables, external URLs, and heading order are preserved; localized anchors resolve; image paths point to real assets. | Any link or asset path is broken, a frontmatter key is translated, an English anchor remains after its heading changes, or Markdown/table structure is corrupted. | + +### Tier B — Graded Criteria (Must Score at Least 4) + +| # | Criterion | Scores 5 when… | Pass floor — Score 4 | Fail ceiling — Score 3 | Scores 1 when… | +| :-- | :--- | :--- | :--- | :--- | :--- | +| 3 | **Fluency (fluidez)** | Reads as native `es-ES`; grammar, accents, agreement, syntax, and punctuation are correct; no calques or gerund misuse. | At most 2 minor slips that do not impede reading. | Any awkward calque requiring rereading, or 3+ language errors. | English-shaped or ungrammatical prose is pervasive. | +| 4 | **Register & Reader Address** | Professional register and treatment (`tú`, `usted`, or impersonal) fit the audience and remain uniform. | One isolated treatment slip that does not shift the perceived voice. | Two or more treatment shifts, or an audience-inappropriate tone. | Register and reader address are inconsistent throughout. | +| 5 | **Terminology & Consistency** | Terms follow `es-ES` conventions and the product glossary; each concept is rendered consistently. | One minor inconsistency remains understandable. | Two or more inconsistent renderings, a false friend, or one misleading term. | Terminology is unreliable throughout. | +| 6 | **Regional & Linguistic Naturalness** | Idioms, possessives, passives, and regional vocabulary are natural for Spain without unnecessary source-language interference. | One or two harmless regional or stylistic nits. | Several calques, ambiguous possessives, or inconsistent regional forms. | The text consistently sounds translated or targets the wrong locale. | +| 7 | **Code & Command Integrity** *(technical only — Tier A severity: any violation caps this at ≤2)* | Variables, identifiers, APIs, file names, and commands are unchanged; only human-language comments are translated. | — (no trivial tolerance) | A single identifier, file name, or command is altered. | Code and commands are repeatedly translated or corrupted. | +| 8 | **Developer Terminology Convention** *(technical only)* | Established Spanish and retained English terms match actual developer usage; over-translation is avoided. | One borderline but recognizable choice. | A forced translation or nonstandard term would confuse a developer. | Technical concepts are consistently rendered unnaturally. | + +> Criterion 7 has Tier A severity in practice: any altered command or identifier fails the document. + +**Overall result:** PASS only if Criteria 1–2 equal 5 and every applicable Criterion 3–8 is at least 4, with no Criterion 7 violation. Otherwise FAIL and iterate, up to the 3-iteration escalation cap. Score each defect under the most specific criterion and do not double-penalize it. \ No newline at end of file diff --git a/.github/skills/localizations/rules/ja-jp.md b/.github/skills/localizations/rules/ja-jp.md new file mode 100644 index 0000000..4068560 --- /dev/null +++ b/.github/skills/localizations/rules/ja-jp.md @@ -0,0 +1,129 @@ +# ja-jp + +These rules apply to **both roles**: the `translator` agent uses them as generation directives (how to write the Japanese text), and the `evaluator` agent uses them as review criteria (what to check and flag). Wherever a rule says "flag" or "look for", the translator should read it as "produce text that satisfies this". + +Translation quality requires both exact meaning and natural Japanese. Verify accuracy, fluency, consistency, and cultural appropriateness rather than preserving English word order. + +The four core pillars are: + +- **Accuracy:** Preserve every source fact, condition, number, name, and degree of obligation. +- **Fluency:** Use natural Japanese grammar, particles, punctuation, and sentence structure. +- **Terminology & Consistency:** Apply approved Japanese terminology and loanword forms uniformly. +- **Cultural Appropriateness:** Use a register and level of directness suitable for Japanese readers. + +## English to Japanese Localization Scenario + +English-to-Japanese quality is best evaluated by checking subject omission, topic flow, modifier length, particles, register, and the handling of technical loanwords. Japanese should communicate the same logic without imitating English sentence structure. + +### Key Evaluation Pillars for Japanese + +- **Register:** Technical documentation uses consistent polite **です・ます調**. Headings and short UI labels may use noun phrases, but body prose must not drift unpredictably into **だ・である調**. +- **Subject Omission:** Omit repeated subjects and reader pronouns when context is clear. Avoid mechanical repetition of **あなた**, **それ**, or **彼ら**. +- **Information Order:** Place context, prerequisites, and conditions before the action or result when natural. Split long English sentences and unwind nested pre-nominal modifiers. +- **Particles and Counters:** Check `は`, `が`, `を`, `に`, `で`, `の`, counters, and classifier choice around code spans and Latin-script terms. +- **Script Choice:** Use kanji, hiragana, katakana, and Latin script according to established Japanese usage and the product glossary. Do not transliterate identifiers or product names. + +### Common Translation Mistakes to Flag + +- **Literal Pronouns:** Flag unnecessary **あなたの**, **それは**, and gendered pronouns introduced from English. +- **Nominalization and Padding:** Avoid repeated **～することができます**, **～を行います**, and **～となります** when shorter **～できます**, **～します**, or **～です** preserves the meaning. +- **Passive Overuse:** English passive voice often becomes a natural active, intransitive, or subjectless Japanese sentence. Retain passive meaning only when the affected party or responsibility matters. +- **Long Modifiers:** Do not stack clauses before a noun until the referent is difficult to identify. Split or reorder the sentence. +- **Inconsistent Loanwords:** Flag inconsistent spelling or long-vowel treatment for the same term, such as mixing **ユーザー** and **ユーザ** without a glossary reason. + +### Practical Evaluation Framework + +| Evaluation Metric | What to Look For (English to Japanese Context) | +| :--- | :--- | +| **Accuracy (正確性)** | Are facts, logical relationships, names, numbers, and modality unchanged? | +| **Fluency (流暢さ)** | Can a native reader understand the sentence immediately without reconstructing English syntax? | +| **Style Guide (スタイル)** | Are register, particles, script choice, punctuation, and loanword spelling correct and consistent? | + +## Markdown Syntaxes + +Keep Markdown delimiters and code spans intact. Japanese particles and punctuation normally belong outside a link or code span unless they are part of the linked phrase. + +- Correct: `[**Node.js**](https://nodejs.org/)と npm パッケージをインストールします。` +- Incorrect: `[**Node.js と**](https://nodejs.org/) npm パッケージをインストールします。` + +Do not insert spaces merely because Markdown emphasis or a link touches Japanese text. Update same-document anchor links when headings are localized, and preserve external URL targets exactly. + +## Localization for Technical Documents for Developers + +Japanese developer documentation commonly combines translated concepts, katakana loanwords, acronyms, and unchanged English identifiers. The goal is recognizability and precision, not maximum translation. + +### Developer-Specific Evaluation Rules + +#### Terminology and Loanwords + +- Use established forms such as **文字列**, **配列**, **依存関係**, **インスタンス**, **スレッド**, **リポジトリ**, and **コールバック** when they match the product glossary. +- Keep **API**, **SDK**, protocol names, product names, and identifiers in their established Latin-script form. +- For an unfamiliar critical term, the first occurrence in a file may include the English form in parentheses, for example **依存関係 (dependency)**. Apply this only when it improves lookup or disambiguation. +- Keep variables, functions, APIs, CLI commands (`npm install`), file names, and code exactly as written. Translate human-language code comments and explanatory strings only when they are not programmatically significant. + +#### Tone and Instructions + +- Use concise **です・ます調**. Render instructions as polite guidance, commonly **～します** or **～してください**, and keep the selected pattern coherent. +- Avoid blunt imperatives such as **～しろ** and excessive honorific or humble language. Technical documentation should be polite, not ceremonial. +- Preserve distinctions among mandatory (**～する必要があります**), recommended (**～することをお勧めします**), and optional (**～できます**) behavior. + +#### Syntactic Readability for Code Logic + +- Prefer condition-first logic: **キーがない場合、エラーが発生します。** +- Isolate variables grammatically: **ここで、`userId` はユーザー ID を表します。** Do not alter the variable to make it fit Japanese morphology. +- Use Japanese punctuation in prose (`。`, `、`, `「」`) while preserving punctuation that is part of code, commands, paths, or exact UI strings. + +### Quick Quality Checklist for Developer Docs + +| What to Flag (Bad) | What to Approve (Good) | Why it Matters | +| :--- | :--- | :--- | +| Repeating **あなたは** in every instruction | Omitting the understood subject | Produces natural Japanese documentation. | +| **インストールすることができます** | **インストールできます** | Removes unnecessary nominalization. | +| Translating `getUserById` | Keeping `getUserById` unchanged | Preserves the identifier. | +| Mixing **サーバー** and **サーバ** | One glossary-approved form | Keeps loanword spelling consistent. | + +## Evaluator Scoring Rubric + +This is the **definitive pass/fail gate** for the `evaluator` role: + +- **Tier A — Hard-fail criteria** must score 5. +- **Tier B — Graded criteria** use a 1–5 scale and pass only at 4 or 5. + +A document **PASSES only when every applicable Tier A criterion scores 5 and every applicable Tier B criterion scores 4 or 5.** Otherwise return it with source/target snippets and the failed criterion. Escalate to a human when the same subjective criterion still fails after **3 iterations**. + +Tier B scale: + +- **5 — Excellent:** Fully meets the criterion. +- **4 — Good (pass):** At most 1–2 trivial, non-blocking nits per ~1,000 words. +- **3 — Borderline (fail):** Several noticeable issues or one issue that changes how a sentence reads. +- **2 — Poor (fail):** Frequent or significant violations. +- **1 — Unacceptable (fail):** The criterion is largely unmet. + +### Determining Content Type + +- **Technical documentation** targets developers/operators or contains code, commands, or API identifiers. Criteria 7–8 apply. +- **Non-technical content** includes UI, marketing, narrative, and conversational copy without code. Criteria 7–8 do not apply, and Criterion 4 uses its audience-appropriate register. + +Criterion 2 and Criterion 7 still apply to occasional code or links in otherwise non-technical content. + +### Tier A — Hard-Fail Criteria (Must Score 5) + +| # | Criterion | Passes (5) when… | Fails (<5) when… | +| :-- | :--- | :--- | :--- | +| 1 | **Accuracy (正確性)** | Meaning, facts, numbers, names, conditions, and modality exactly match the source. | Any mistranslation, omission, addition, negation flip, altered name/number, or changed requirement level occurs. | +| 2 | **Markdown & Structural Integrity** | Frontmatter keys, Markdown, tables, URLs, and heading order are preserved; localized anchors and asset paths resolve. | Any broken link/path, translated frontmatter key, stale English anchor, or corrupted Markdown/table occurs. | + +### Tier B — Graded Criteria (Must Score at Least 4) + +| # | Criterion | Scores 5 when… | Pass floor — Score 4 | Fail ceiling — Score 3 | Scores 1 when… | +| :-- | :--- | :--- | :--- | :--- | :--- | +| 3 | **Fluency (流暢さ)** | Particles, information order, punctuation, script choice, and sentence length are natural; no translationese or padding. | At most 2 minor slips that do not impede reading. | One sentence requires rereading, or 3+ language errors occur. | English-shaped or ungrammatical Japanese is pervasive. | +| 4 | **Register & Tone** | Body prose consistently uses audience-appropriate **です・ます調**; headings and labels follow coherent conventions. | One isolated ending slip without a perceived register shift. | Two or more style shifts, blunt imperatives, or unsuitable honorific language. | Register is mixed or inappropriate throughout. | +| 5 | **Terminology & Consistency** | Japanese equivalents, katakana forms, acronyms, and first-mention English references follow the glossary consistently. | One minor recognizable inconsistency. | Two or more inconsistent forms or one misleading term. | Terminology and script forms are unreliable throughout. | +| 6 | **Cultural & Linguistic Naturalness** | Subjects are omitted naturally; directness, passives, and modifier length suit Japanese documentation. | One or two harmless stylistic nits. | Several literal pronouns, padded constructions, or overlong modifiers occur. | Literal English discourse patterns dominate. | +| 7 | **Code & Command Integrity** *(technical only — Tier A severity: any violation caps this at ≤2)* | Identifiers, APIs, commands, paths, and file names are unchanged; only human-language comments are translated. | — (no trivial tolerance) | A single code element or command is altered. | Code and commands are repeatedly translated or corrupted. | +| 8 | **Developer Terminology Convention** *(technical only)* | Terms match Japanese developer usage and the product glossary without forced translation. | One borderline but recognizable choice. | A nonstandard translation or transliteration would confuse a developer. | Technical concepts are consistently unnatural or unrecognizable. | + +> Criterion 7 has Tier A severity in practice: any altered command or identifier fails the document. + +**Overall result:** PASS only if Criteria 1–2 equal 5 and every applicable Criterion 3–8 is at least 4, with no Criterion 7 violation. Otherwise FAIL and iterate, up to the 3-iteration escalation cap. Record a defect under its most specific criterion only. \ No newline at end of file diff --git a/.github/skills/localizations/rules/ko-kr.md b/.github/skills/localizations/rules/ko-kr.md new file mode 100644 index 0000000..80f9565 --- /dev/null +++ b/.github/skills/localizations/rules/ko-kr.md @@ -0,0 +1,129 @@ +# ko-kr + +These rules apply to **both roles**: the `translator` agent uses them as generation directives (how to write the Korean text), and the `evaluator` agent uses them as review criteria (what to check and flag). Wherever a rule says "flag" or "look for", the translator should read it as "produce text that satisfies this". + +In general, producing and evaluating translation quality requires both the accuracy of the meaning and the natural flow of the language. To do this, verify that the text passes core tests for accuracy, fluency, consistency, and cultural appropriateness. + +Here are the 4 core pillars: + +- **Accuracy:** Ensure the meaning matches the source text exactly, with no information added, distorted, or omitted. +- **Fluency:** Check that grammar, punctuation, and spelling adhere to the conventions of the target language so that the text reads naturally. +- **Terminology & Consistency:** Verify that specialized terms, names, and key phrases are used uniformly throughout the document. +- **Cultural Appropriateness:** Confirm that idioms, metaphors, and the overall tone are culturally sensitive and suited to the target audience. + +## English to Korean Localization Scenario + +English-to-Korean translation quality is best evaluated by checking for natural sentence structures, correct honorific levels, and accurate transformation of English idioms into natural Korean expressions. Korean has a drastically different grammar structure (Subject-Object-Verb) and deep cultural nuances that automated tools often miss. + +### Key Evaluation Pillars for Korean + +- **Honorifics and Tone:** Verify that the speech level—formal-polite (존댓말/jondaenmal) versus casual (반말/banmal)—is uniform and fits the target audience. For documentation, this means consistent 존댓말 throughout. +- **Natural Word Order:** Ensure the text does not read like a literal word-for-word translation (번역투/beonyeoktu), which results in long, awkward modifiers. +- **Subject Pronoun Omission:** Check that unnecessary pronouns like "그녀" (she) or "그들" (they) are removed, as natural Korean drops subjects when context is clear. +- **Terminology Adaptation:** Confirm whether technical words are accurately translated into localized Korean terms or appropriately transliterated into Hangul phonetic equivalents. + +### Common Translation Mistakes to Flag + +- **Passive Voice Overuse:** English frequently uses passive voice, but natural Korean heavily favors active verbs; overusing passive forms makes Korean text feel robotic. For example, "코드 작성이 포함됩니다" should be "코드 작성을 포함합니다". +- **Literal Phrase Translations:** Watch out for expressions like "in terms of" translated literally to "~의 관점에서" instead of natural Korean particles. +- **Plural Marker Overuse:** English strictly tracks plurals, but adding the Korean plural marker "~들" to every noun sounds highly unnatural. + +### Practical Evaluation Framework + +| Evaluation Metric | What to Look For (English to Korean Context) | +| :--- | :--- | +| **Accuracy (정확성)** | Are critical numbers, names, and core English meanings preserved without distortion? | +| **Fluency (유창성)** | Does a native Korean speaker understand the text instantly without re-reading sentences? | +| **Style Guide (스타일)** | Does the text follow Korean spelling, spacing (띄어쓰기), and punctuation rules? | + +## Markdown Syntaxes + +Here are some examples when using combination of markdown syntaxes: + +- English: Both `**[node.js](https://nodejs.org/)**` and `[**node.js**](https://nodejs.org/)` properly render **[node.js](https://nodejs.org/)** +- Korean: Only `[**node.js**](https://nodejs.org/)` properly renders [**node.js**](https://nodejs.org/) + +It's because Korean sentences and phrases mostly comes with a word with affixes. For example, this sentence "[**node.js**](https://nodejs.org/)와 npm 패키지를 설치해야 합니다" combines with the word of "node.js" and "와". Therefore, localization into Korean should consider the markdown syntax review as well. + +## Localization for Technical Documents for Developers + +When evaluating English-to-Korean technical documentation for developers, standard linguistic rules change. Korean developers heavily favor industry-standard English terminology over clunky, forced Korean translations. If a translation forces purely native Korean words for established coding concepts, it will look amateurish and confuse the reader. + +Evaluate your developer documentation by looking for specific markers across structural, lexical, and formatting levels. + +### The Developer-Specific Evaluation Rubric + +#### Terminology & Loanwords (가장 중요함) + +- **Avoid "Over-Translation":** Some terms have well-established Korean equivalents and should use them (e.g., *String* → **문자열**, *Array* → **배열**, *Dependency* → **종속성/의존성**). Others have no natural Korean equivalent and must be transliterated into Hangul or kept in English—forcing a literal native translation is unacceptable (e.g., *Instance* → "실체" or *Thread* → "실" is wrong; use **인스턴스**, **스레드**). When unsure, prefer the form Korean developers actually use over a literal dictionary translation, and keep the chosen term consistent throughout (see Terminology & Consistency). +- **The First-Mention Rule:** For critical or unfamiliar technical jargon, the **first occurrence within a single file** should use the Hangul transliteration followed by the original English in parentheses—for example, **인스턴스(Instance)**. This follows the standardized [Microsoft Korean Localization Style Guide](https://learn.microsoft.com/globalization/reference/microsoft-style-guides) for technical acronyms and core definitions. Subsequent mentions in the same file can just use the Hangul. Apply this selectively to terms a reader may want to look up in English, not to every loanword. +- **Code Elements Untouched:** Ensure variables, function names, APIs, CLI commands (`npm install`), and code itself are kept exactly as in the source. However, **human-language comments inside code blocks** (e.g., `// fetch the user`) *should* be localized, since they are explanatory prose for the reader. + +#### Tone and Politeness Level (합니다체) + +- **The "합니다체" (Hamnida-che) Standard:** Developer docs should use the standard formal-polite register, **합니다체** (the 하십시오체 family, with endings like *~합니다 / ~습니다*). This is the conventional register for Korean technical documentation and is what the Microsoft Korean Localization Style Guide prescribes. Do **not** drop into the more casual **해요체** (endings like *~해요 / ~예요*), which reads too informal for documentation. Keep the register uniform throughout a file. +- **Direct Imperatives:** English documentation loves direct commands like *"Click here"* or *"Run the following script."* Render these as polite guiding instructions—use either the 합니다체 declarative (**"~를 실행합니다"**) or the polite imperative (**"~를 실행하십시오"**) consistently, rather than blunt commands. Avoid casual forms like "~하세요" when the rest of the document is in 합니다체. + +#### Syntactic Readability for Code Logic + +- **Conditional Mapping ("If" statements):** In English, conditional outcomes often come first (*"An error will occur if the key is missing"*). Korean reads more naturally with the condition first, so prefer reordering the logic so the prerequisite precedes the result (*"키가 누락되면 오류가 발생합니다"*). The leading *만약* is optional and can be omitted when *~면* already signals the condition. +- **Variables as Nouns:** Technical English often weaves variables into sentences (*"where x is the user ID"*). Ensure the Korean translation cleanly isolates the variable marker, using phrases like **"여기서 x는 사용자 ID를 나타냅니다."** + +### Quick Quality Checklist for Developer Docs + +| What to Flag (Bad ❌) | What to Approve (Good ⭕) | Why it Matters | +| :--- | :--- | :--- | +| **"git 커밋을 저장하십시오"** | **"git commit을 수행합니다"** | Keeps the exact CLI keyword `git commit` in English instead of translating it to "커밋 저장". | +| **"그녀의 토큰"** (Using "Her/Its token") | **"해당 토큰"** or omit the pronoun | Korean drops pronouns; "그녀" (she) or "그것" (it) breaks technical flow. | +| **"라이브러리들"** (Plural "Libraries") | **"라이브러리"** | Plural markers (`~들`) are repetitive in technical specs. | +| **"콜백 함수"** (No English reference) | **"콜백 함수(Callback function)"** | Allows developers to easily look up the original English error/API docs. | + +## Evaluator Scoring Rubric + +This is the **definitive pass/fail gate** for the `evaluator` role. Criteria are split into two tiers: + +- **Tier A — Hard-fail criteria:** any material defect makes the document unusable, so these **must score 5 to pass**. A single broken command, altered number, corrupted link, or distorted fact fails the document outright. +- **Tier B — Graded criteria:** scored on the 1–5 scale below; these **pass at 4 or 5**. + +A document **PASSES only when every applicable Tier A criterion scores 5 and every applicable Tier B criterion scores 4 or 5.** Otherwise it FAILS and is returned to the translator with specific notes (cite the offending source/target snippet and the failed criterion), then re-scored. If a document still fails the same subjective criterion after **3 iterations**, escalate to a human rather than looping further. + +Tier B scale (applies to every Tier B criterion): + +- **5 — Excellent:** Fully meets the criterion; no issues. +- **4 — Good (pass):** Meets the criterion; at most 1–2 trivial, non-blocking nits per ~1,000 words. +- **3 — Borderline (fail):** Several noticeable issues, or any issue that changes how a sentence reads; revision required. +- **2 — Poor (fail):** Frequent or significant violations throughout. +- **1 — Unacceptable (fail):** Criterion is largely unmet. + +### Determining content type + +Before scoring, classify the document so the right criteria apply: + +- **Technical documentation** = content written for developers/operators (API docs, READMEs, tutorials, CLI guides, reference) **or any document that contains code, commands, or API identifiers**. Criteria 7–8 apply. +- **Non-technical content** = UI strings, marketing, narrative, or conversational copy with no code. Criteria 7–8 do **not** apply, and the register target in Criterion 4 is the audience-appropriate one rather than 합니다체. + +If a non-technical document still contains occasional code or links, Tier A Criterion 2 (and Criterion 7, for those code spans) still apply to those spans. + +### Tier A — Hard-fail criteria (must score 5) + +| # | Criterion | Passes (5) when… | Fails (<5) when… | +| :-- | :--- | :--- | :--- | +| 1 | **Accuracy (정확성)** | Meaning matches the source exactly; every number, name, and fact is preserved; nothing is added, distorted, or omitted. | **Any** mistranslation, negation flip, fabricated/dropped fact, or altered number/name — even a single isolated one. | +| 2 | **Markdown & Structural Integrity** | Frontmatter keys, Markdown structure, tables, and external URLs are preserved exactly; heading order is stable. Heading anchors follow the localized headings, and every same-document anchor link resolves to its (now-localized) target. Image/asset paths resolve to a real asset—the original asset (relative path rewritten as needed) unless a localized asset exists. | **Any** broken link (including a same-document anchor that points at the original English slug after its heading was translated), unresolved image path, translated frontmatter key, or corrupted Markdown/table. | + +### Tier B — Graded criteria (must score ≥4) + +These are **always scored** unless marked technical-only. + +| # | Criterion | Scores 5 when… | Pass floor — Score 4 | Fail ceiling — Score 3 | Scores 1 when… | +| :-- | :--- | :--- | :--- | :--- | :--- | +| 3 | **Fluency (유창성)** | Reads naturally on first pass; grammar, spelling, spacing (띄어쓰기), and punctuation all correct; no 번역투 or passive-voice overuse. | ≤2 minor spacing/punctuation slips that don't impede reading. | Any awkward 번역투 sentence requiring re-reading, or 3+ grammar/spacing/punctuation errors. | Pervasive awkwardness; frequent grammar/spacing errors. | +| 4 | **Honorifics & Tone** | Register is uniform and matches the content type (합니다체 for documentation; audience-appropriate register otherwise); no unintended slips. | A single isolated ending slip that doesn't shift the perceived register. | 2+ register slips, or a tone that doesn't fit the audience. | Register is mixed or clearly inappropriate throughout. | +| 5 | **Terminology & Consistency** | Terms follow the locale rules and are used uniformly; correct accepted-equivalent vs. transliteration choices; first-mention English reference applied where useful. | 1 minor terminology inconsistency a reader can still follow. | 2+ inconsistent renderings of the same term, or one over-translation (e.g., *Instance* → "실체"). | Terminology is inconsistent or over-translated throughout. | +| 6 | **Cultural & Linguistic Naturalness** | Idioms adapted naturally; subjects/pronouns dropped where Korean would; no redundant plural `~들`. | 1–2 redundant pronouns/plurals that don't distort meaning. | Several literal idioms or redundant pronoun/`~들` patterns that read unnaturally. | Literal idiom calques and redundant pronouns/plurals throughout. | +| 7 | **Code & Command Integrity** *(technical only — Tier A severity: any violation caps this at ≤2)* | Variables, function names, APIs, and CLI commands are untouched and in English; only explanatory prose and human-language code comments are translated. | — (no "trivial" tolerance; treat as hard-fail) | A single translated/altered identifier or command. | Code, identifiers, or commands are translated or altered. | +| 8 | **Developer Terminology Convention** *(technical only)* | Industry-standard English/Hangul terms used as developers expect; native over-translations avoided for established coding concepts. | 1 borderline term choice that developers would still recognize. | A forced native translation of an established term, or terms developers wouldn't recognize. | Established concepts consistently forced into unnatural native Korean. | + +> Criterion 7 carries Tier A severity in practice: a broken command or identifier is never a "non-blocking nit", so any violation fails the document. It is listed in Tier B only because it is conditional on technical content. + +**Overall result:** PASS only if every applicable **Tier A** criterion = 5 **and** every applicable **Tier B** criterion ≥ 4 (criteria 7–8 apply to technical documentation only). Otherwise FAIL and iterate, up to the 3-iteration escalation cap. Score each criterion independently; if one defect could fall under two criteria, record it under the most specific one and do not double-penalize. diff --git a/.github/skills/localizations/rules/pt-br.md b/.github/skills/localizations/rules/pt-br.md new file mode 100644 index 0000000..604c17f --- /dev/null +++ b/.github/skills/localizations/rules/pt-br.md @@ -0,0 +1,129 @@ +# pt-br + +These rules apply to **both roles**: the `translator` agent uses them as generation directives (how to write Brazilian Portuguese), and the `evaluator` agent uses them as review criteria (what to check and flag). Wherever a rule says "flag" or "look for", the translator should read it as "produce text that satisfies this". + +Translation quality requires exact meaning and natural Brazilian Portuguese. Verify accuracy, fluency, consistency, and cultural appropriateness rather than preserving English syntax. + +The four core pillars are: + +- **Accuracy:** Preserve the source meaning exactly, with no additions, distortions, or omissions. +- **Fluency:** Follow Brazilian Portuguese grammar, spelling, punctuation, and idiom. +- **Terminology & Consistency:** Apply specialized terms, names, and recurring phrases uniformly. +- **Cultural Appropriateness:** Use register, idioms, examples, and regional vocabulary suitable for Brazil. + +## English to Brazilian Portuguese Localization Scenario + +English-to-Portuguese quality is best evaluated by checking agreement, pronoun placement, prepositions, article use, natural clause order, and Brazilian terminology. Avoid English calques and accidental European Portuguese forms. + +### Key Evaluation Pillars for Brazilian Portuguese + +- **Regional Standard:** Use post-1990 orthography and established `pt-BR` vocabulary. Prefer **arquivo**, **tela**, **usuário**, **senha**, **fazer login/entrar**, and **salvar** where appropriate to the product glossary. +- **Reader Address:** Technical documentation normally uses a professional, direct voice with **você** understood or explicit. Keep treatment consistent; do not mix **você**, **tu**, **o senhor/a senhora**, and impersonal forms unintentionally. +- **Agreement and Government:** Verify gender/number agreement, contractions, verb and noun government, and prepositions, especially around untranslated product names. +- **Natural Syntax:** Break up English noun stacks, reduce repeated possessives, and place clitic pronouns according to natural contemporary Brazilian usage. +- **Orthography and Punctuation:** Check accents, hyphenation, capitalization, and punctuation. Preserve locale-neutral numbers when they are factual source values; localize display formats only when the content explicitly permits it. + +### Common Translation Mistakes to Flag + +- **False Cognates and Calques:** Flag misleading forms such as **aplicar para** (when **candidatar-se/solicitar** is meant), **eventualmente** for "eventually", and **biblioteca** versus **livraria** in software contexts. +- **Gerundism:** Avoid bureaucratic strings such as **vai estar executando** when **executará** or **vai executar** is clearer. A normal progressive gerund is acceptable when the action is genuinely ongoing. +- **Possessive and Pronoun Overuse:** Omit repeated **seu/sua** and **você** when context is clear, but rewrite ambiguous possessives instead of guessing their referent. +- **European Portuguese Leakage:** Flag forms such as **ficheiro**, **ecrã**, **palavra-passe**, **utilizador**, or **guardar** when the intended `pt-BR` term differs. +- **Unnatural Passive Voice:** Prefer active or reflexive constructions when they are clearer, without changing responsibility or emphasis. + +### Practical Evaluation Framework + +| Evaluation Metric | What to Look For (English to Brazilian Portuguese Context) | +| :--- | :--- | +| **Accuracy (precisão)** | Are facts, logical relationships, numbers, names, and modality preserved exactly? | +| **Fluency (fluência)** | Would a Brazilian reader understand each sentence immediately without detecting English syntax? | +| **Style Guide (estilo)** | Are spelling, accents, agreement, punctuation, pronouns, and regional conventions correct? | + +## Markdown Syntaxes + +Keep Markdown delimiters attached to the intended text. Articles, prepositions, and punctuation must not enter URLs or code spans accidentally. + +- Correct: `Instale o [**Node.js**](https://nodejs.org/) e o pacote npm.` +- Incorrect: `Instale **[o Node.js e](https://nodejs.org/)** o pacote npm.` + +When a translated heading changes its generated slug, update same-document links to the localized anchor. Preserve external URLs exactly. + +## Localization for Technical Documents for Developers + +Brazilian developer documentation combines translated concepts with English loanwords and unchanged identifiers. Prefer the terminology Brazilian developers actually use and follow the product glossary over dictionary literalism. + +### Developer-Specific Evaluation Rules + +#### Terminology and English Terms + +- Use established terms such as **cadeia de caracteres/string** according to the product glossary, **matriz/array**, **dependência**, **instância**, **thread**, **repositório**, **retorno de chamada/callback**, and **tempo de execução/runtime**. Select one approved form per concept and use it consistently. +- Keep **API**, **SDK**, protocol names, product names, and identifiers in their established form. +- For an unfamiliar critical term, the first occurrence in a file may include the English source in parentheses, for example **tempo de execução (runtime)**. Apply this selectively. +- Keep variables, function names, APIs, CLI commands (`npm install`), paths, file names, and code exactly as in the source. Translate explanatory human-language comments when they are not machine-significant. + +#### Tone and Instructions + +- Use concise professional prose. Direct instructions commonly use the imperative associated with **você**, such as **Execute o comando** and **Selecione a opção**. Keep this style consistent. +- Avoid unnecessary **por favor**, bureaucratic language, and repeated **você deve** when a direct imperative preserves the requirement. +- Preserve requirement levels: **deve/é necessário** for requirements, **recomenda-se** for recommendations, and **pode** for capability or permission. + +#### Syntactic Readability for Code Logic + +- Prefer condition-first logic: **Se a chave estiver ausente, ocorrerá um erro.** +- Isolate variables grammatically: **Aqui, `userId` representa a ID do usuário.** Do not translate or inflect the identifier. +- Rewrite ambiguous **seu/sua** references with the exact noun when more than one antecedent is possible. + +### Quick Quality Checklist for Developer Docs + +| What to Flag (Bad) | What to Approve (Good) | Why it Matters | +| :--- | :--- | :--- | +| **“vai estar executando `npm install`”** | **“execute `npm install`”** | Avoids gerundism and preserves the command. | +| **“livraria de software”** | **“biblioteca de software”** | Uses the established technical meaning. | +| Mixing **você** and **tu** | One consistent treatment | Keeps the documentation voice stable. | +| Translating `StringBuilder` | Keeping `StringBuilder` unchanged | Preserves the identifier exactly. | + +## Evaluator Scoring Rubric + +This is the **definitive pass/fail gate** for the `evaluator` role: + +- **Tier A — Hard-fail criteria** must score 5. +- **Tier B — Graded criteria** use a 1–5 scale and pass only at 4 or 5. + +A document **PASSES only when every applicable Tier A criterion scores 5 and every applicable Tier B criterion scores 4 or 5.** Otherwise return it with source/target snippets and the failed criterion. Escalate to a human when the same subjective criterion still fails after **3 iterations**. + +Tier B scale: + +- **5 — Excellent:** Fully meets the criterion. +- **4 — Good (pass):** At most 1–2 trivial, non-blocking nits per ~1,000 words. +- **3 — Borderline (fail):** Several noticeable issues or one issue that changes how a sentence reads. +- **2 — Poor (fail):** Frequent or significant violations. +- **1 — Unacceptable (fail):** The criterion is largely unmet. + +### Determining Content Type + +- **Technical documentation** targets developers/operators or contains code, commands, or API identifiers. Criteria 7–8 apply. +- **Non-technical content** includes UI, marketing, narrative, and conversational copy without code. Criteria 7–8 do not apply, and Criterion 4 uses its audience-appropriate register. + +Criterion 2 and Criterion 7 still apply to occasional code or links in otherwise non-technical content. + +### Tier A — Hard-Fail Criteria (Must Score 5) + +| # | Criterion | Passes (5) when… | Fails (<5) when… | +| :-- | :--- | :--- | :--- | +| 1 | **Accuracy (precisão)** | Meaning, facts, conditions, names, numbers, and modality exactly match the source. | Any mistranslation, omission, addition, negation flip, altered name/number, or changed requirement level occurs. | +| 2 | **Markdown & Structural Integrity** | Frontmatter keys, Markdown, tables, URLs, heading order, localized anchors, and asset paths are preserved and valid. | Any broken link/path, translated frontmatter key, stale English anchor, or corrupted Markdown/table occurs. | + +### Tier B — Graded Criteria (Must Score at Least 4) + +| # | Criterion | Scores 5 when… | Pass floor — Score 4 | Fail ceiling — Score 3 | Scores 1 when… | +| :-- | :--- | :--- | :--- | :--- | :--- | +| 3 | **Fluency (fluência)** | Grammar, agreement, prepositions, pronouns, punctuation, and syntax are natural `pt-BR`; no calques or gerundism. | At most 2 minor slips that do not impede reading. | One sentence requires rereading, or 3+ language errors occur. | English-shaped or ungrammatical prose is pervasive. | +| 4 | **Register & Reader Address** | Professional tone and treatment (**você**, impersonal, or another audience-appropriate form) are consistent. | One isolated treatment slip without a perceived voice shift. | Two or more treatment shifts or an unsuitable tone. | Register and reader address are inconsistent throughout. | +| 5 | **Terminology & Consistency** | Terms follow `pt-BR` and product conventions; translated and retained English terms are consistent. | One minor recognizable inconsistency. | Two or more inconsistent forms, a false cognate, or one misleading term. | Terminology is unreliable throughout. | +| 6 | **Regional & Linguistic Naturalness** | Idiom, pronoun placement, possessives, passives, and vocabulary are natural in Brazil. | One or two harmless stylistic nits. | Several calques, ambiguous possessives, or European Portuguese forms occur. | The text consistently sounds translated or targets the wrong locale. | +| 7 | **Code & Command Integrity** *(technical only — Tier A severity: any violation caps this at ≤2)* | Identifiers, APIs, commands, paths, and file names are unchanged; only human-language comments are translated. | — (no trivial tolerance) | A single code element or command is altered. | Code and commands are repeatedly translated or corrupted. | +| 8 | **Developer Terminology Convention** *(technical only)* | Terms match Brazilian developer usage and the product glossary without forced translation. | One borderline but recognizable choice. | A nonstandard translation would confuse a developer. | Technical concepts are consistently unnatural or unrecognizable. | + +> Criterion 7 has Tier A severity in practice: any altered command or identifier fails the document. + +**Overall result:** PASS only if Criteria 1–2 equal 5 and every applicable Criterion 3–8 is at least 4, with no Criterion 7 violation. Otherwise FAIL and iterate, up to the 3-iteration escalation cap. Record a defect under its most specific criterion only. \ No newline at end of file diff --git a/.github/skills/localizations/rules/zh-cn.md b/.github/skills/localizations/rules/zh-cn.md new file mode 100644 index 0000000..7b0e441 --- /dev/null +++ b/.github/skills/localizations/rules/zh-cn.md @@ -0,0 +1,129 @@ +# zh-cn + +These rules apply to **both roles**: the `translator` agent uses them as generation directives (how to write Simplified Chinese), and the `evaluator` agent uses them as review criteria (what to check and flag). Wherever a rule says "flag" or "look for", the translator should read it as "produce text that satisfies this". + +Translation quality requires exact meaning and natural Mainland Chinese usage. Verify accuracy, fluency, consistency, and cultural appropriateness without preserving English syntax mechanically. + +The four core pillars are: + +- **Accuracy:** Preserve every source fact, condition, number, name, and degree of obligation. +- **Fluency:** Use concise, grammatical Simplified Chinese with natural information order and punctuation. +- **Terminology & Consistency:** Follow established Mainland Chinese technical terminology and the product glossary. +- **Cultural Appropriateness:** Adapt idiom, tone, examples, and regional language for readers in Mainland China. + +## English to Simplified Chinese Localization Scenario + +English-to-Chinese quality is best evaluated by checking concise clause structure, omitted pronouns, modifier order, logical connectors, script consistency, and accepted Mainland terminology. Avoid word-for-word translation, unnecessary function words, and a mixture of Simplified and Traditional Chinese. + +### Key Evaluation Pillars for Simplified Chinese + +- **Script and Region:** Use Simplified Chinese characters and `zh-CN` terminology throughout. Flag Traditional forms or vocabulary associated with another Chinese locale when a Mainland equivalent is expected. +- **Conciseness:** Remove source-language padding and repeated subjects when context is clear, but do not omit conditions or weaken meaning. +- **Information Order:** Put time, scope, prerequisites, and conditions before the main action or result when natural in Chinese. +- **Modifier Clarity:** Break up long English noun stacks and relative clauses. Ensure each modifier clearly attaches to the intended noun. +- **Punctuation:** Use Chinese punctuation in prose (`，。；：“”《》`) and preserve ASCII punctuation inside code, URLs, commands, paths, and exact syntax. + +### Common Translation Mistakes to Flag + +- **Pronoun Overuse:** Avoid mechanical repetition of **您**, **你**, **它**, and **他们** where Chinese naturally omits the subject. +- **Passive Marker Overuse:** Do not map every English passive to **被**. Use an active, subjectless, or result construction unless the affected party is important. +- **Redundant Phrases:** Flag padding such as **进行配置操作**, **可以能够**, and repeated **的** chains when **配置**, **可以**, or a restructured sentence is clearer. +- **Literal Connectors:** Do not overuse **关于**, **在……方面**, or **当……的时候** as direct English calques when a shorter topic or conditional construction works. +- **Locale Mixing:** Flag Traditional characters and inconsistent pairs such as **文件/檔案**, **软件/軟體**, **登录/登入**, or **默认/預設**. + +### Practical Evaluation Framework + +| Evaluation Metric | What to Look For (English to Simplified Chinese Context) | +| :--- | :--- | +| **Accuracy (准确性)** | Are facts, conditions, names, numbers, and modality preserved exactly? | +| **Fluency (流畅性)** | Can a Mainland Chinese reader understand each sentence immediately without reconstructing English syntax? | +| **Style Guide (风格)** | Are Simplified characters, punctuation, terminology, and spacing conventions correct and consistent? | + +## Markdown Syntaxes + +Keep Markdown delimiters, URLs, and code spans intact. Chinese punctuation and grammatical particles must not be absorbed into a link target or code span. + +- Correct: `安装 [**Node.js**](https://nodejs.org/) 和 npm 包。` +- Incorrect: `安装 [**Node.js 和**](https://nodejs.org/) npm 包。` + +Use one consistent spacing convention around embedded Latin terms according to the product style guide; never insert spaces inside identifiers or commands. Update same-document links to localized heading anchors and preserve external URLs exactly. + +## Localization for Technical Documents for Developers + +Simplified Chinese developer documentation normally translates established concepts while retaining acronyms, product names, identifiers, and commands. Prefer the form that Mainland developers can recognize quickly. + +### Developer-Specific Evaluation Rules + +#### Terminology and English Terms + +- Use established terms such as **字符串**, **数组**, **依赖项/依赖关系** according to context, **实例**, **线程**, **存储库**, **回调函数**, and **运行时**. +- Keep established forms such as **API**, **SDK**, protocol names, product names, and language keywords in Latin script. +- For a critical unfamiliar term, the first occurrence in a file may include the English term in parentheses, for example **运行时 (runtime)**. Apply this selectively and consistently. +- Keep variables, function names, APIs, CLI commands (`npm install`), paths, file names, and code exactly as in the source. Translate human-language comments when they are explanatory and not machine-significant. + +#### Tone and Instructions + +- Use a concise, professional, neutral voice. Prefer direct verbs such as **选择**, **运行**, and **输入**. Avoid repeated **请** unless politeness is needed for the context. +- Use **您** only when the product voice requires direct respectful address; otherwise omit the reader pronoun. Never mix **你** and **您** unintentionally. +- Preserve requirement levels: **必须/需要** for requirements, **建议** for recommendations, and **可以** for capability or permission. + +#### Syntactic Readability for Code Logic + +- Prefer condition-first logic: **如果缺少密钥，则会发生错误。** Omit **则** when the shorter sentence remains clear. +- Isolate variables grammatically: **其中，`userId` 表示用户 ID。** Do not translate or inflect the variable. +- Avoid long **的** chains; split the sentence or move conditions into a preceding clause. + +### Quick Quality Checklist for Developer Docs + +| What to Flag (Bad) | What to Approve (Good) | Why it Matters | +| :--- | :--- | :--- | +| **“进行包的安装操作”** | **“安装包”** | Removes source-language padding. | +| Repeating **“您需要”** in every step | Using the direct verb | Matches concise technical style. | +| Translating `getUserById` | Keeping `getUserById` unchanged | Preserves the identifier. | +| Mixing **文件** and **檔案** | Consistent **文件** | Keeps the document in `zh-CN`. | + +## Evaluator Scoring Rubric + +This is the **definitive pass/fail gate** for the `evaluator` role: + +- **Tier A — Hard-fail criteria** must score 5. +- **Tier B — Graded criteria** use a 1–5 scale and pass only at 4 or 5. + +A document **PASSES only when every applicable Tier A criterion scores 5 and every applicable Tier B criterion scores 4 or 5.** Otherwise return it with source/target snippets and the failed criterion. Escalate to a human when the same subjective criterion still fails after **3 iterations**. + +Tier B scale: + +- **5 — Excellent:** Fully meets the criterion. +- **4 — Good (pass):** At most 1–2 trivial, non-blocking nits per ~1,000 words. +- **3 — Borderline (fail):** Several noticeable issues or one issue that changes how a sentence reads. +- **2 — Poor (fail):** Frequent or significant violations. +- **1 — Unacceptable (fail):** The criterion is largely unmet. + +### Determining Content Type + +- **Technical documentation** targets developers/operators or contains code, commands, or API identifiers. Criteria 7–8 apply. +- **Non-technical content** includes UI, marketing, narrative, and conversational copy without code. Criteria 7–8 do not apply, and Criterion 4 uses its audience-appropriate register. + +Criterion 2 and Criterion 7 still apply to occasional code or links in otherwise non-technical content. + +### Tier A — Hard-Fail Criteria (Must Score 5) + +| # | Criterion | Passes (5) when… | Fails (<5) when… | +| :-- | :--- | :--- | :--- | +| 1 | **Accuracy (准确性)** | Meaning, facts, conditions, names, numbers, and modality exactly match the source. | Any mistranslation, omission, addition, negation flip, altered name/number, or changed requirement level occurs. | +| 2 | **Markdown & Structural Integrity** | Frontmatter keys, Markdown, tables, URLs, heading order, localized anchors, and asset paths are preserved and valid. | Any broken link/path, translated frontmatter key, stale English anchor, or corrupted Markdown/table occurs. | + +### Tier B — Graded Criteria (Must Score at Least 4) + +| # | Criterion | Scores 5 when… | Pass floor — Score 4 | Fail ceiling — Score 3 | Scores 1 when… | +| :-- | :--- | :--- | :--- | :--- | :--- | +| 3 | **Fluency (流畅性)** | Clause order, modifiers, grammar, punctuation, and concision are natural; no translationese or redundant padding. | At most 2 minor slips that do not impede reading. | One sentence requires rereading, or 3+ language errors occur. | English-shaped or ungrammatical Chinese is pervasive. | +| 4 | **Register & Tone** | Professional neutral tone and reader address (**你**, **您**, or impersonal) fit the audience and remain consistent. | One isolated pronoun or politeness slip without a voice shift. | Two or more **你/您** shifts or an unsuitable level of directness. | Tone and reader address are inconsistent throughout. | +| 5 | **Terminology & Consistency** | Terms use Simplified Chinese and accepted Mainland forms consistently; English references follow the glossary. | One minor recognizable inconsistency. | Two or more inconsistent forms, a Traditional form, or one misleading term. | Terminology and script are unreliable throughout. | +| 6 | **Regional & Linguistic Naturalness** | Pronoun omission, active/result constructions, connectors, and modifier order suit Mainland Chinese. | One or two harmless stylistic nits. | Several literal pronouns, **被** constructions, calques, or **的** chains occur. | Literal English patterns or wrong-locale forms dominate. | +| 7 | **Code & Command Integrity** *(technical only — Tier A severity: any violation caps this at ≤2)* | Identifiers, APIs, commands, paths, and file names are unchanged; only human-language comments are translated. | — (no trivial tolerance) | A single code element or command is altered. | Code and commands are repeatedly translated or corrupted. | +| 8 | **Developer Terminology Convention** *(technical only)* | Terms match Mainland developer usage and the product glossary without forced translation. | One borderline but recognizable choice. | A nonstandard translation would confuse a developer. | Technical concepts are consistently unnatural or unrecognizable. | + +> Criterion 7 has Tier A severity in practice: any altered command or identifier fails the document. + +**Overall result:** PASS only if Criteria 1–2 equal 5 and every applicable Criterion 3–8 is at least 4, with no Criterion 7 violation. Otherwise FAIL and iterate, up to the 3-iteration escalation cap. Record a defect under its most specific criterion only. \ No newline at end of file diff --git a/AUTHORING.md b/AUTHORING.md index 3feebba..d156c08 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -99,7 +99,7 @@ The site runs at . **Verify** before committing: 1. **Build** — `cd docs && rm -rf dist && npm run build`. Must succeed. -2. **Page-count invariant** — 36 routable `.md` pages plus the one legacy redirect equals 37 built `index.html` pages when excluding the 404 page; the build reports 38 HTML files including the 404 page. +2. **Page-count invariant** — Starlight emits 36 workshop routes for English and each of the five configured locales, then adds the legacy redirect. This equals 217 built `index.html` pages when excluding the 404 page; the build reports 218 HTML files including the 404 page. 3. **Link check** — lychee (offline) against the built `docs/dist/`. Catches broken internal links/images. **What CI enforces vs. what you run locally:** CI (`pages.yml`) runs the **build** and the **lychee** link check on every PR. It does not run browser validation or the content-alignment agentic workflow as part of the Pages build job. After merge to `main`, `pages.yml` deploys the site to GitHub Pages. diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 69916b1..bc53608 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -31,6 +31,14 @@ export default defineConfig({ title: 'Agents in the SDLC Workshop', description: 'A hands-on workshop exploring GitHub Copilot agents across VS Code, the Copilot CLI, the GitHub Copilot app, and the Copilot cloud agent.', + locales: { + root: { label: 'English', lang: 'en' }, + 'es-es': { label: 'Español', lang: 'es-ES' }, + 'ja-jp': { label: '日本語', lang: 'ja-JP' }, + 'ko-kr': { label: '한국어', lang: 'ko-KR' }, + 'pt-br': { label: 'Português (Brasil)', lang: 'pt-BR' }, + 'zh-cn': { label: '简体中文', lang: 'zh-CN' }, + }, social: [ { icon: 'github', diff --git a/docs/package-lock.json b/docs/package-lock.json index b3a777a..7cc544b 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -929,9 +929,6 @@ "cpu": [ "arm" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -948,9 +945,6 @@ "cpu": [ "arm64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -967,9 +961,6 @@ "cpu": [ "ppc64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -986,9 +977,6 @@ "cpu": [ "riscv64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -1005,9 +993,6 @@ "cpu": [ "s390x" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -1024,9 +1009,6 @@ "cpu": [ "x64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -1043,9 +1025,6 @@ "cpu": [ "arm64" ], - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -1062,9 +1041,6 @@ "cpu": [ "x64" ], - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -1081,9 +1057,6 @@ "cpu": [ "arm" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1106,9 +1079,6 @@ "cpu": [ "arm64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1131,9 +1101,6 @@ "cpu": [ "ppc64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1156,9 +1123,6 @@ "cpu": [ "riscv64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1181,9 +1145,6 @@ "cpu": [ "s390x" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1206,9 +1167,6 @@ "cpu": [ "x64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1231,9 +1189,6 @@ "cpu": [ "arm64" ], - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1256,9 +1211,6 @@ "cpu": [ "x64" ], - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -1652,9 +1604,6 @@ "cpu": [ "arm" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1668,9 +1617,6 @@ "cpu": [ "arm" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1684,9 +1630,6 @@ "cpu": [ "arm64" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1700,9 +1643,6 @@ "cpu": [ "arm64" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1716,9 +1656,6 @@ "cpu": [ "loong64" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1732,9 +1669,6 @@ "cpu": [ "loong64" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1748,9 +1682,6 @@ "cpu": [ "ppc64" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1764,9 +1695,6 @@ "cpu": [ "ppc64" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1780,9 +1708,6 @@ "cpu": [ "riscv64" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1796,9 +1721,6 @@ "cpu": [ "riscv64" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1812,9 +1734,6 @@ "cpu": [ "s390x" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1828,9 +1747,6 @@ "cpu": [ "x64" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1844,9 +1760,6 @@ "cpu": [ "x64" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ diff --git a/docs/src/content/docs/es-es/app/0-prerequisites.md b/docs/src/content/docs/es-es/app/0-prerequisites.md new file mode 100644 index 0000000..b93e499 --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-06-30 +--- + +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/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/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]: ../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/docs/src/content/docs/es-es/app/1-install-copilot-app.md b/docs/src/content/docs/es-es/app/1-install-copilot-app.md new file mode 100644 index 0000000..e5bf258 --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-09 +--- + +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. Confirma que aparecen las tres incidencias que la plantilla ha creado en la lista de trabajo pendiente: + + - Allow users to filter games by category and publisher + - Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments + - Stretch Goal: 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]: ../0-prerequisites/ +[next-lesson]: ../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/docs/src/content/docs/es-es/app/2-add-star-rating.md b/docs/src/content/docs/es-es/app/2-add-star-rating.md new file mode 100644 index 0000000..b10c330 --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-09 +--- + +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/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/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/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]: ../1-install-copilot-app/#instalar-y-configurar-la-aplicacion-github-copilot +[next-lesson]: ../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/docs/src/content/docs/es-es/app/3-custom-instructions.md b/docs/src/content/docs/es-es/app/3-custom-instructions.md new file mode 100644 index 0000000..ffb5a1b --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-09 +--- + +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/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/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 **Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments** 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/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/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]: ../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/github +[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/docs/src/content/docs/es-es/app/4-build-filtering.md b/docs/src/content/docs/es-es/app/4-build-filtering.md new file mode 100644 index 0000000..39105d1 --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-13 +--- + +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/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/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/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/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/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]: ../0-prerequisites/ +[ex2]: ../2-add-star-rating/ +[ex3]: ../3-custom-instructions/ +[next-lesson]: ../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/docs/src/content/docs/es-es/app/5-mcp-playwright.md b/docs/src/content/docs/es-es/app/5-mcp-playwright.md new file mode 100644 index 0000000..705fe8c --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-09 +--- + +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]: ../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/docs/src/content/docs/es-es/app/6-agent-merge.md b/docs/src/content/docs/es-es/app/6-agent-merge.md new file mode 100644 index 0000000..b29b790 --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-09 +--- + +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/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/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]: ../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/docs/src/content/docs/es-es/app/7-canvases.md b/docs/src/content/docs/es-es/app/7-canvases.md new file mode 100644 index 0000000..feba666 --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-09 +--- + +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/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/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]: ../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/canvases +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/src/content/docs/es-es/app/8-review.md b/docs/src/content/docs/es-es/app/8-review.md new file mode 100644 index 0000000..7f9a64f --- /dev/null +++ b/docs/src/content/docs/es-es/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: + - geektrainer +lastUpdated: 2026-07-09 +--- + +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](../../vscode/), el [recorrido de Copilot CLI](../../cli/) o el [recorrido del agente en la nube](../../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/docs/src/content/docs/es-es/app/index.md b/docs/src/content/docs/es-es/app/index.md new file mode 100644 index 0000000..b938f5e --- /dev/null +++ b/docs/src/content/docs/es-es/app/index.md @@ -0,0 +1,57 @@ +--- +title: "Aplicación GitHub Copilot" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +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]: 0-prerequisites/ +[ex1]: 1-install-copilot-app/ +[ex2]: 2-add-star-rating/ +[ex3]: 3-custom-instructions/ +[ex4]: 4-build-filtering/ +[ex5]: 5-mcp-playwright/ +[ex6]: 6-agent-merge/ +[ex7]: 7-canvases/ +[ex8]: 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/docs/src/content/docs/es-es/index.md b/docs/src/content/docs/es-es/index.md new file mode 100644 index 0000000..9dac48a --- /dev/null +++ b/docs/src/content/docs/es-es/index.md @@ -0,0 +1,41 @@ +--- +title: "Agentes en el ciclo de vida del desarrollo de software (SDLC)" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +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](../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](../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](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](../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/docs/src/content/docs/ja-jp/app/0-prerequisites.md b/docs/src/content/docs/ja-jp/app/0-prerequisites.md new file mode 100644 index 0000000..10329a2 --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "レッスン 0 - 前提条件" +description: "GitHub Copilot app のレッスンに向けて、Tailspin Toys プロジェクト用の Node.js をインストールし、テンプレートからリポジトリの自分用コピーを作成します。" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +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/app-0-use-template.png) + +3. GitHub または Microsoft が主催するイベントの一環としてワークショップに参加している場合は、メンターの指示に従ってください。それ以外の場合は、GitHub Copilot を利用できる Organization に新しいリポジトリを作成できます。 + + ![github-samples/tailspin-toys がテンプレートに設定され、リポジトリ名が入力された Create a new repository フォーム](../../_images/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]: ../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/docs/src/content/docs/ja-jp/app/1-install-copilot-app.md b/docs/src/content/docs/ja-jp/app/1-install-copilot-app.md new file mode 100644 index 0000000..bfbda96 --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "レッスン 1 - GitHub Copilot app のインストール" +description: "GitHub Copilot app をインストールし、テンプレートから作成したリポジトリを接続して、ワークスペースを確認し、クイックチャットを試します。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +[**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. テンプレートによってバックログに用意された次の3件の Issue が表示されることを確認します。 + + - Allow users to filter games by category and publisher + - Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments + - Stretch Goal: 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]: ../0-prerequisites/ +[next-lesson]: ../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/docs/src/content/docs/ja-jp/app/2-add-star-rating.md b/docs/src/content/docs/ja-jp/app/2-add-star-rating.md new file mode 100644 index 0000000..b1edad2 --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "レッスン 2 - 最初のエージェントセッションの実行" +description: "GitHub Copilot app で最初のエージェントセッションを開始し、ゲームカードに小さな変更を加えて、最初の pull request としてマージします。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +前のレッスンでは、ワークスペースを確認し、クイックチャットを使いました。ここでは、**エージェントセッション**を開始し、プロジェクトに最初の変更を加えます。変更は小規模なものにします。ゲームのデータにはすでに星評価が含まれていますが、ホームページのゲームカードにはまだ表示されていません。エージェントに表示を依頼し、変更をレビューして、最初の 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/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/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/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]: ../1-install-copilot-app/#github-copilot-app-をインストールして構成する +[next-lesson]: ../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/docs/src/content/docs/ja-jp/app/3-custom-instructions.md b/docs/src/content/docs/ja-jp/app/3-custom-instructions.md new file mode 100644 index 0000000..1e1a71e --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "レッスン 3 - カスタム指示による Copilot のガイド" +description: "GitHub Copilot app を使い、バックログの Issue から始めてカスタム指示の標準をリポジトリに追加し、変更を pull request としてマージします。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +生成 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/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/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. **Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments** というタイトルの Issue を選択して開きます。 +3. 右上の **New session** を選択し、Issue に基づく新しいセッションを開始します。 + + ![GitHub Copilot app の Issue ビューで、右上の New session ボタンを矢印で示した画面](../../_images/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/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]: ../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/github +[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/docs/src/content/docs/ja-jp/app/4-build-filtering.md b/docs/src/content/docs/ja-jp/app/4-build-filtering.md new file mode 100644 index 0000000..781f83d --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "レッスン 4 - Autopilot による機能の構築" +description: "GitHub Copilot app の Plan モードと Autopilot モードを使って静的なクライアント側フィルター機能を構築し、ドキュメント標準が継承されることを確認して、エージェントスキルで検証します。" +authors: + - geektrainer +lastUpdated: 2026-07-13 +--- + +ここまで、プロジェクトに小さな更新をいくつか加えました。しかし、より本格的な変更には、よりしっかりしたプロセスが必要です。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/app-new-session-from-issue.png) + +4. モードに **Plan** と表示されるまで Shift+Tab を選択します。 + + ![モードセレクターが Plan に設定され、矢印で示された GitHub Copilot app のプロンプトボックス](../../_images/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/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/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/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]: ../0-prerequisites/ +[ex2]: ../2-add-star-rating/ +[ex3]: ../3-custom-instructions/ +[next-lesson]: ../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/docs/src/content/docs/ja-jp/app/5-mcp-playwright.md b/docs/src/content/docs/ja-jp/app/5-mcp-playwright.md new file mode 100644 index 0000000..4cfea9b --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "レッスン 5 - Playwright MCP server によるテスト" +description: "Playwright MCP server を GitHub Copilot app に追加し、実際のブラウザーでフィルター機能を手動テストするようエージェントに依頼します。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +前のレッスンでは、プロジェクトの自動テストスイートを使ってフィルター機能を作成し、検証しました。テストによってコードの検証を自動化できますが、エージェント自身が動作を確認できるようにすることも効果的です。実際に作成している 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]: ../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/docs/src/content/docs/ja-jp/app/6-agent-merge.md b/docs/src/content/docs/ja-jp/app/6-agent-merge.md new file mode 100644 index 0000000..eefc96a --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "レッスン 6 - Agent Merge によるマージ" +description: "フィルター機能の pull request を作成して My work でレビューし、マージを妨げる問題の修正とマージを Agent Merge に任せて、段階的なマージ自動化の最上位まで進みます。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +フィルター機能の構築と検証が完了し、ブラウザーで動作することも確認できました。最後のステップはマージです。このハーネスではすでに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/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/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]: ../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/docs/src/content/docs/ja-jp/app/7-canvases.md b/docs/src/content/docs/ja-jp/app/7-canvases.md new file mode 100644 index 0000000..9f9588f --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "レッスン 7 - キャンバスを使った計画" +description: "GitHub Copilot app でエージェント主導の共有キャンバスを作成し、エージェントと一緒に作業を計画して追跡します。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +ここまでは、チャットを通じてエージェントを指示してきました。しかし、多くの作業は会話の中ではなく、ボード、ドキュメント、チェックリスト上で行われます。**キャンバス**は、まさにそのような作業のために、アプリ内でユーザーとエージェントが共有できる領域です。このレッスンでは、ここまで取り組んできたバックログの計画と追跡に使用する、シンプルなキャンバスを作成します。 + +このレッスンでは、次の内容を学習します。 + +- キャンバスの概要と使用する場面を理解する。 +- バックログをトリアージする共有 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/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/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]: ../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/canvases +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/src/content/docs/ja-jp/app/8-review.md b/docs/src/content/docs/ja-jp/app/8-review.md new file mode 100644 index 0000000..cbcdcf4 --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "レッスン 8 - 振り返りと次のステップ" +description: "GitHub Copilot app のハーネスを振り返り、繰り返し発生する作業を自動化して、次に学ぶ内容を確認します。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +ここ数回のレッスンでは、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 ハーネス](../../vscode/)、[Copilot CLI ハーネス](../../cli/)、[Cloud agent ハーネス](../../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/docs/src/content/docs/ja-jp/app/index.md b/docs/src/content/docs/ja-jp/app/index.md new file mode 100644 index 0000000..c17dbfb --- /dev/null +++ b/docs/src/content/docs/ja-jp/app/index.md @@ -0,0 +1,57 @@ +--- +title: "GitHub Copilot app" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +[**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]: 0-prerequisites/ +[ex1]: 1-install-copilot-app/ +[ex2]: 2-add-star-rating/ +[ex3]: 3-custom-instructions/ +[ex4]: 4-build-filtering/ +[ex5]: 5-mcp-playwright/ +[ex6]: 6-agent-merge/ +[ex7]: 7-canvases/ +[ex8]: 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/docs/src/content/docs/ja-jp/index.md b/docs/src/content/docs/ja-jp/index.md new file mode 100644 index 0000000..4c1450d --- /dev/null +++ b/docs/src/content/docs/ja-jp/index.md @@ -0,0 +1,41 @@ +--- +title: "ソフトウェア開発ライフサイクル (SDLC) におけるエージェント" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +GitHub Copilot に最近追加された機能は、ソフトウェア開発ライフサイクル (SDLC) 全体を通して開発者を支援する強力なツールです。GitHub の Issue や pull request を使った作業、外部サービスとの連携、そしてもちろんコードの作成も含まれます。このラボでは、実際のユースケースを通して機能を試し、ツールを最大限に活用するためのヒントを紹介します。 + +> [!CAUTION] +> GitHub Copilot は決定論的ではなく確率的に動作するため、生成されるコードや変更されるファイルなどは毎回異なる場合があります。そのため、ラボ内のスクリーンショットやコード スニペットと、実際の結果に多少の違いが生じることがあります。これは想定される動作であり、この種のツールが持つ特性によるものです。 +> +> 何かが壊れているように見える場合や正しく動作しない場合は、メンターに相談してください。 + +## 利用環境を選ぶ + +GitHub Copilot は、どの環境で作業していても利用できます。希望する開発方法に合った利用環境を選び、共通の Tailspin Toys バックログに沿って演習を進めます。どの利用環境にも専用のセットアップ手順が用意されているため、選んだものからすぐに始められます。 + +### 🖥️ [VS Code](../vscode/) + +**Visual Studio Code** と GitHub Codespaces 内で GitHub Copilot を使用します。普段使っているエディターを離れることなく、Copilot Chat のエージェント モード、MCP サーバー、カスタム エージェントを利用できます。AI 支援を IDE に直接組み込んで使いたい場合に最適です。 + +### 💻 [Copilot CLI](../cli/) + +**GitHub Copilot CLI** は、ターミナルで動作するエージェント型アシスタントです。インストールして MCP サーバーに接続し、プラン モードでコードを生成できます。さらに、独自のスキル、カスタム エージェント、スラッシュ コマンドをすべてコマンド ラインから構築できます。 + +### 🤖 [Copilot App](app/) + +**GitHub Copilot app** は、Copilot CLI を基盤とするデスクトップ アプリケーションです。複数のエージェント セッションを並行して実行し、セッション モードの切り替え、キャンバスでの共同作業、GitHub Issue と pull request の管理をアプリ内で行えます。さらに **Agent Merge** を使用すると、リベース、レビュー フィードバックへの対応、CI の修正、マージまで、pull request の一連の作業を進められます。 + +### ☁️ [Copilot Cloud Agent](../cloud/) + +**Copilot cloud agent** は、GitHub Issue の作業をバックグラウンドで進める非同期のペア プログラマーです。作業の割り当て、カスタム エージェントによる指示、エージェント ダッシュボードでの進捗確認、作成された pull request のレビューを行えます。 + +## シナリオ + +架空の企業 Tailspin Toys に新しく参加した開発者として作業します。Tailspin Toys は、開発者をテーマにしたボード ゲームのクラウドファンディングを提供しています。これは巨大な市場です。チームのバックログはすでに GitHub Issue として登録されており、フィルタリングやページネーションなどの機能開発に加えて、アクセシビリティやコーディング規約などの品質改善にもすぐに取り組めます。サイトと Copilot の機能を確認しながら反復的に作業し、タスクを完了させます。 + +## はじめる + +上から利用環境を選んで開始します。どの利用環境も、開発に必要なセットアップから始まります。 \ No newline at end of file diff --git a/docs/src/content/docs/ko-kr/app/0-prerequisites.md b/docs/src/content/docs/ko-kr/app/0-prerequisites.md new file mode 100644 index 0000000..5296f49 --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "Lesson 0 - 필수 조건" +description: "Tailspin Toys 프로젝트에 필요한 Node.js를 설치하고 템플릿에서 리포지토리 복사본을 만들어 GitHub Copilot app 레슨을 준비합니다." +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +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/app-0-use-template.png) + +3. GitHub 또는 Microsoft가 진행하는 이벤트에서 워크숍을 수행하는 경우 멘토가 제공한 지침을 따릅니다. 그렇지 않으면 GitHub Copilot에 접근할 수 있는 조직에 새 리포지토리를 만들 수 있습니다. + + ![github-samples/tailspin-toys가 템플릿으로 설정되고 리포지토리 이름이 입력된 Create a new repository 양식](../../_images/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]: ../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/docs/src/content/docs/ko-kr/app/1-install-copilot-app.md b/docs/src/content/docs/ko-kr/app/1-install-copilot-app.md new file mode 100644 index 0000000..e7c2603 --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "Lesson 1 - GitHub Copilot app 설치" +description: "GitHub Copilot app을 설치하고, 템플릿에서 만든 리포지토리를 연결하고, 워크스페이스를 살펴보고, 빠른 채팅을 사용해 봅니다." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +[**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 + - Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments + - Stretch Goal: 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]: ../0-prerequisites/ +[next-lesson]: ../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/docs/src/content/docs/ko-kr/app/2-add-star-rating.md b/docs/src/content/docs/ko-kr/app/2-add-star-rating.md new file mode 100644 index 0000000..1bb6fc6 --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "Lesson 2 - 첫 번째 에이전트 세션 실행" +description: "GitHub Copilot app에서 첫 번째 에이전트 세션을 시작하고 게임 카드를 조금 변경한 다음 첫 번째 끌어오기 요청으로 병합합니다." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +이전 레슨에서는 워크스페이스를 살펴보고 빠른 채팅을 사용했습니다. 이제 **에이전트 세션**을 시작하고 프로젝트를 처음으로 변경합니다. 변경 범위는 작게 유지합니다. 게임 데이터에는 이미 별점이 있지만 홈페이지의 게임 카드에는 아직 표시되지 않습니다. 에이전트에게 별점을 표시하도록 요청하고, 변경 내용을 검토하고, 첫 번째 끌어오기 요청으로 병합합니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- 에이전트 세션을 시작하고 세션의 구조를 알아봅니다. +- 에이전트에게 프로젝트를 작고 구체적으로 변경하도록 요청합니다. +- 워크스페이스의 diff 보기에서 변경 내용을 검토합니다. +- 앱을 로컬에서 실행하여 브라우저에서 변경 내용을 확인합니다. +- 첫 번째 끌어오기 요청을 열고 병합합니다. + +## 시나리오 + +Tailspin Toys의 각 게임에는 별점이 있을 수 있으며, 별점은 이미 게임 세부 정보 페이지에 표시됩니다. 하지만 홈페이지의 게임 카드에는 제목, 카테고리, 퍼블리셔, 설명만 표시됩니다. 첫 세션 연습으로 에이전트에게 각 카드에 기존 별점을 표시하도록 요청합니다. 첫 번째 세션에 적합한 작고 독립적인 변경입니다. + +## 세션 구조 + +**세션**은 격리된 자체 워크스페이스에서 실행되는 에이전트와의 대화입니다. 모든 세션에는 **전용 git 작업 트리와 브랜치**가 제공됩니다. 따라서 변경 내용이 충돌하지 않게 한 세션에서는 기능을 추가하고 다른 세션에서는 버그를 수정하는 등 여러 세션을 동시에 실행할 수 있습니다. 세션은 사이드바에서 리포지토리별로 그룹화되며, 원하는 세션을 선택하여 전환할 수 있습니다. + +세션 안에는 에이전트와의 **대화**, 에이전트가 파일을 탐색하고 편집할 때의 **도구 활동**, diff와 함께 표시되는 **변경된 파일** 목록이 있습니다. + +## 세션을 시작하고 변경 요청하기 + +새 세션을 시작하여 프로젝트를 탐색하고 기능을 구현합니다. [이전 레슨][prior-lesson]에서 GitHub 리포지토리의 프로젝트를 추가했습니다. 해당 리포지토리에 새 세션을 만들고 변경을 요청합니다. + +1. GitHub Copilot app으로 돌아가거나 앱을 엽니다. +2. **Home screen**을 선택합니다. +3. 리포지토리로 `tailspin-toys`가 선택되어 있는지 확인합니다. + + ![리포지토리 선택기가 tailspin-toys로 설정되고 프롬프트 아래에 모델 선택기가 표시된 GitHub Copilot app 프롬프트 상자](../../_images/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/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/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]: ../1-install-copilot-app/#github-copilot-app-설치-및-구성 +[next-lesson]: ../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/docs/src/content/docs/ko-kr/app/3-custom-instructions.md b/docs/src/content/docs/ko-kr/app/3-custom-instructions.md new file mode 100644 index 0000000..b0d3679 --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "Lesson 3 - 사용자 지정 지침으로 Copilot 안내" +description: "GitHub Copilot app을 사용하여 백로그의 이슈에서 시작해 리포지토리에 사용자 지정 지침 표준을 추가하고 변경 내용을 끌어오기 요청으로 병합합니다." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +생성형 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/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/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. **Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments** 이슈를 선택하여 엽니다. +3. 오른쪽 위의 **New session**을 선택하여 이슈를 바탕으로 새 세션을 시작합니다. + + ![오른쪽 위의 New session 버튼을 화살표로 가리키는 GitHub Copilot app 이슈 보기](../../_images/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/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]: ../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/github +[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/docs/src/content/docs/ko-kr/app/4-build-filtering.md b/docs/src/content/docs/ko-kr/app/4-build-filtering.md new file mode 100644 index 0000000..1bf692d --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "Lesson 4 - Autopilot으로 기능 구축" +description: "GitHub Copilot app의 Plan 및 Autopilot 모드로 정적 클라이언트 쪽 필터링 기능을 구축하고, 문서화 표준이 적용되는지 확인하고, 에이전트 스킬로 검증합니다." +authors: + - geektrainer +lastUpdated: 2026-07-13 +--- + +지금까지 프로젝트를 작게 몇 차례 업데이트했습니다. 하지만 더 큰 변경에는 더 탄탄한 프로세스가 필요합니다. 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/app-new-session-from-issue.png) + +4. 모드에 **Plan**이 표시될 때까지 Shift+Tab을 선택합니다. + + ![Plan으로 설정된 모드 선택기를 화살표로 가리키는 GitHub Copilot app 프롬프트 상자](../../_images/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/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/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/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]: ../0-prerequisites/ +[ex2]: ../2-add-star-rating/ +[ex3]: ../3-custom-instructions/ +[next-lesson]: ../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/docs/src/content/docs/ko-kr/app/5-mcp-playwright.md b/docs/src/content/docs/ko-kr/app/5-mcp-playwright.md new file mode 100644 index 0000000..40a2156 --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "Lesson 5 - Playwright MCP 서버로 테스트" +description: "GitHub Copilot app에 Playwright MCP 서버를 추가하고 에이전트에게 실제 브라우저에서 필터링 기능을 수동으로 테스트하도록 요청합니다." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +이전 레슨에서는 프로젝트의 자동화된 테스트 도구 모음으로 필터링 기능을 만들고 검증했습니다. 테스트는 코드 검증을 자동화하지만 에이전트가 동작을 직접 확인하게 하는 것도 강력합니다. 에이전트는 자신이 만드는 실제 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]: ../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/docs/src/content/docs/ko-kr/app/6-agent-merge.md b/docs/src/content/docs/ko-kr/app/6-agent-merge.md new file mode 100644 index 0000000..f29b33e --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "Lesson 6 - Agent Merge로 병합" +description: "필터링 끌어오기 요청을 열고 My work에서 검토한 다음, Agent Merge가 차단 요소를 수정하고 병합하도록 하여 병합 자동화의 최상위 단계를 경험합니다." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +필터링 기능을 구축하고 검증하고 브라우저에서 작동하는 모습까지 확인했습니다. 마지막 단계는 병합입니다. 이 실습 과정에서 이미 두 번 병합했으며, 두 번 모두 끌어오기 요청을 열고 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/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/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]: ../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/docs/src/content/docs/ko-kr/app/7-canvases.md b/docs/src/content/docs/ko-kr/app/7-canvases.md new file mode 100644 index 0000000..c20dce2 --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "Lesson 7 - 캔버스로 계획 수립" +description: "GitHub Copilot app에서 공유 에이전트 기반 캔버스를 만들어 에이전트와 함께 작업을 계획하고 추적합니다." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +지금까지 채팅을 통해 에이전트를 지시했습니다. 하지만 많은 작업은 대화가 아니라 보드, 문서, 검사 목록에서 이루어집니다. **캔버스**는 바로 이러한 작업을 위해 앱 안에서 사용자와 에이전트가 함께 사용하는 화면을 제공합니다. 이 레슨에서는 지금까지 처리한 백로그를 계획하고 추적하는 간단한 캔버스를 만듭니다. + +이 레슨에서는 다음 작업을 수행합니다. + +- 캔버스의 개념과 사용 시점을 이해합니다. +- 백로그를 분류하는 공유 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/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/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]: ../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/canvases +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/src/content/docs/ko-kr/app/8-review.md b/docs/src/content/docs/ko-kr/app/8-review.md new file mode 100644 index 0000000..fe3a101 --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "Lesson 8 - 검토 및 다음 단계" +description: "GitHub Copilot app 실습 과정을 되짚어 보고, 반복 작업을 자동화하고, 다음에 살펴볼 내용을 알아봅니다." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +지난 여러 레슨에서 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 실습 과정](../../vscode/), [Copilot CLI 실습 과정](../../cli/), [Cloud agent 실습 과정](../../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/docs/src/content/docs/ko-kr/app/index.md b/docs/src/content/docs/ko-kr/app/index.md new file mode 100644 index 0000000..5433c7c --- /dev/null +++ b/docs/src/content/docs/ko-kr/app/index.md @@ -0,0 +1,57 @@ +--- +title: "GitHub Copilot app" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +[**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]: 0-prerequisites/ +[ex1]: 1-install-copilot-app/ +[ex2]: 2-add-star-rating/ +[ex3]: 3-custom-instructions/ +[ex4]: 4-build-filtering/ +[ex5]: 5-mcp-playwright/ +[ex6]: 6-agent-merge/ +[ex7]: 7-canvases/ +[ex8]: 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/docs/src/content/docs/ko-kr/index.md b/docs/src/content/docs/ko-kr/index.md new file mode 100644 index 0000000..7c7613c --- /dev/null +++ b/docs/src/content/docs/ko-kr/index.md @@ -0,0 +1,41 @@ +--- +title: "소프트웨어 개발 수명 주기(SDLC)의 에이전트" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +최근 GitHub Copilot에 추가된 기능은 소프트웨어 개발 수명 주기(SDLC) 전반에서 개발자에게 강력한 도구를 제공합니다. 여기에는 GitHub의 이슈 및 끌어오기 요청 작업, 외부 서비스와의 상호 작용, 그리고 코드 작성이 포함됩니다. 이 랩에서는 이러한 기능을 살펴보고, 실제 사용 사례와 도구를 최대한 활용하는 방법을 소개합니다. + +> [!CAUTION] +> GitHub Copilot은 결정론적이 아니라 확률론적으로 작동하므로 정확한 코드와 변경되는 파일 등이 달라질 수 있습니다. 따라서 랩의 스크린샷 및 코드 조각과 실제 환경에서 약간의 차이가 나타날 수 있습니다. 이는 예상된 결과이며, 이러한 유형의 도구가 작동하는 방식에서 비롯됩니다. +> +> 무언가 제대로 작동하지 않거나 올바르게 실행되지 않는다면 멘토에게 문의하십시오! + +## 하네스(Harness) 선택 + +GitHub Copilot은 어떤 작업 환경에서든 함께할 수 있습니다. 원하는 개발 방식에 맞는 하네스를 선택하고, Tailspin Toys의 공통 백로그를 바탕으로 연습을 진행합니다. 각 하네스는 자체 설정 과정으로 시작하므로 원하는 하네스를 선택해 바로 시작할 수 있습니다. + +### 🖥️ [VS Code](../vscode/) + +**Visual Studio Code**와 GitHub Codespaces에서 GitHub Copilot을 사용합니다. 익숙한 편집기를 벗어나지 않고 Copilot Chat 에이전트 모드, MCP 서버, 사용자 지정 에이전트를 활용합니다. AI 지원을 IDE에 직접 통합하고 싶을 때 적합합니다. + +### 💻 [Copilot CLI](../cli/) + +**GitHub Copilot CLI**는 터미널에서 실행되는 에이전트형 도우미입니다. 이를 설치하고, MCP 서버를 연결하고, 계획 모드로 코드를 생성하고, 명령줄에서 직접 스킬, 사용자 지정 에이전트, 슬래시 명령을 만듭니다. + +### 🤖 [Copilot 앱](app/) + +**GitHub Copilot 앱**은 Copilot CLI를 기반으로 구축된 데스크톱 애플리케이션입니다. 여러 에이전트 세션을 병렬로 실행하고, 세션 모드를 전환하고, 캔버스에서 협업하고, GitHub 이슈와 끌어오기 요청을 기본 기능으로 관리합니다. 여기에는 끌어오기 요청의 리베이스, 검토 피드백, CI 수정, 병합 과정을 관리하는 **Agent Merge**도 포함됩니다. + +### ☁️ [Copilot 클라우드 에이전트](../cloud/) + +**Copilot 클라우드 에이전트**는 백그라운드에서 GitHub 이슈를 처리하는 비동기 동료 프로그래머입니다. 작업을 할당하고, 사용자 지정 에이전트로 작업 방향을 안내하고, 에이전트 대시보드에서 진행 상황을 모니터링하고, 에이전트가 생성한 끌어오기 요청을 검토합니다. + +## 시나리오 + +여러분은 개발자 테마의 보드게임 크라우드펀딩을 제공하는 가상 기업 Tailspin Toys에 새로 합류한 개발자입니다. 아주 큰 시장입니다! 팀의 백로그는 이미 GitHub 이슈로 등록되어 있어 바로 작업을 시작할 수 있습니다. 필터링 및 페이지 매김과 같은 기능 작업과 접근성 및 코딩 표준과 같은 품질 개선 작업이 함께 준비되어 있습니다. 사이트와 Copilot의 기능을 모두 살펴보면서 반복적으로 작업을 진행해 과제를 완료합니다. + +## 시작하기 + +위에서 하네스를 선택해 시작합니다. 각 하네스는 개발을 시작하는 데 필요한 설정 과정으로 시작합니다. \ No newline at end of file diff --git a/docs/src/content/docs/pt-br/app/0-prerequisites.md b/docs/src/content/docs/pt-br/app/0-prerequisites.md new file mode 100644 index 0000000..1349203 --- /dev/null +++ b/docs/src/content/docs/pt-br/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "Lição 0 - Pré-requisitos" +description: "Prepare-se para as lições do aplicativo GitHub Copilot: instale o Node.js para o projeto Tailspin Toys e crie sua própria cópia do repositório a partir do modelo." +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +O aplicativo GitHub Copilot é um aplicativo para desktop que funciona como ponto central tanto para o Copilot quanto para o GitHub. Ele oferece acesso rápido a issues e pull requests e, naturalmente, permite que você desenvolva usando o GitHub Copilot. Durante este workshop, você trabalhará localmente com o aplicativo Tailspin Toys, criado com Astro, e com o aplicativo GitHub Copilot. Antes de começar, vamos verificar se o Node.js está instalado localmente e depois instalar o aplicativo Copilot. + +Nesta lição, você vai: + +- instalar o Node.js para executar os testes do projeto no seu computador. +- criar sua própria cópia do projeto Tailspin Toys a partir do modelo. + +## Instalar o Node.js + +Em várias lições, você pedirá a um agente que crie recursos e execute localmente o conjunto de testes do Tailspin Toys. Para isso, é necessário o [**Node.js**][nodejs], o único ambiente de execução exigido pelo projeto. Instale a versão **22 ou posterior**; a versão **LTS** atual é uma escolha segura. + +A opção mais simples em todas as plataformas é o instalador oficial: + +1. No sistema operacional, abra uma janela de terminal usando o Windows Terminal, o Terminal do macOS ou o aplicativo que você costuma usar. +2. Execute o comando a seguir para confirmar que você tem o Node.js 22 ou posterior instalado: + + ```shell + node --version + ``` + +3. Se você vir `v22` ou um número maior, pule para a próxima seção. + +> [!TIP] +> Você só precisa concluir estas etapas se não tiver o Node instalado ou se precisar atualizá-lo. + +4. Abra a [página de download do Node.js][node-download]. +5. Baixe a versão **LTS** para o seu sistema operacional. +6. Execute o instalador e aceite as opções padrão. No Windows, mantenha a opção **Add to PATH** selecionada. +7. Após a instalação, abra uma nova janela de terminal. +8. Confirme a instalação na nova janela de terminal executando: + + ```bash + node --version + ``` + +9. Você deve ver `v22.x.x` ou posterior. + +> [!TIP] +> Prefere contêineres? Se você tem o [**Docker**][docker], pode usar o [contêiner de desenvolvimento][dev-containers] do repositório em vez de instalar o Node.js localmente. Ele já inclui o Node. Você não precisa dos dois. + +## Configurar o repositório do laboratório + +Você trabalhará na sua própria cópia do projeto Tailspin Toys. Crie-a agora a partir do [repositório de modelo][template-repository]. O novo repositório contém todos os arquivos necessários para o laboratório, e você o conectará ao aplicativo na próxima lição. + +1. Em uma nova janela do navegador, acesse o repositório do GitHub deste laboratório: `https://github.com/github-samples/tailspin-toys`. +2. Crie sua própria cópia do repositório selecionando o botão **Use this template** na página do repositório do laboratório. Em seguida, selecione **Create a new repository**. + + ![Botão Use this template com a opção Create a new repository selecionada no menu suspenso](../../_images/app-0-use-template.png) + +3. Se você estiver fazendo o workshop como parte de um evento conduzido pelo GitHub ou pela Microsoft, siga as instruções dos mentores. Caso contrário, crie o novo repositório em uma organização na qual você tenha acesso ao GitHub Copilot. + + ![Formulário Create a new repository com github-samples/tailspin-toys definido como modelo e o nome do repositório preenchido](../../_images/app-0-create-repository.png) + +4. Anote o caminho do repositório que você criou (**organization-or-user-name/repository-name**), pois ele será usado mais adiante no laboratório. + +> [!NOTE] +> Quando você cria o repositório a partir do modelo, um backlog de issues do GitHub é criado automaticamente. Você trabalhará com essas issues durante todo o workshop e não precisará criar nenhuma. + +## Resumo e próximos passos + +Tudo pronto! Você instalou o Node.js para criar e testar o projeto no seu computador e criou sua própria cópia do repositório Tailspin Toys a partir do modelo. + +Em seguida, você instalará o aplicativo GitHub Copilot, conectará o repositório que acabou de criar e conhecerá o espaço de trabalho. Continue para a [Lição 1 - Instalar o aplicativo GitHub Copilot][next-lesson]. + +## Recursos + +- [Baixar o Node.js][node-download] +- [Criar um repositório a partir de um modelo][template-repository] +- [Sobre o aplicativo GitHub Copilot][about-copilot-app] + +[next-lesson]: ../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/docs/src/content/docs/pt-br/app/1-install-copilot-app.md b/docs/src/content/docs/pt-br/app/1-install-copilot-app.md new file mode 100644 index 0000000..14973ab --- /dev/null +++ b/docs/src/content/docs/pt-br/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "Lição 1 - Instalar o aplicativo GitHub Copilot" +description: "Instale o aplicativo GitHub Copilot, conecte o repositório criado a partir do modelo, conheça o espaço de trabalho e experimente um chat rápido." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +O [**aplicativo GitHub Copilot**][about-copilot-app] é um aplicativo para desktop voltado ao desenvolvimento orientado por agentes. Ele foi criado com base no GitHub Copilot CLI e tem integração nativa com o GitHub, portanto seus repositórios, branches e pipelines de CI funcionam sem configuração adicional. Ele foi projetado para fluxos de trabalho nos quais você orienta vários agentes em paralelo, cada um em seu espaço de trabalho isolado, em vez de fazer todo o trabalho por conta própria, além de automatizar tarefas repetitivas. Com o Node.js instalado e sua cópia do projeto pronta, a próxima etapa é instalar o aplicativo e conectar esse repositório. + +Nesta lição, você vai: + +- instalar o aplicativo GitHub Copilot e entrar na sua conta. +- adicionar seu projeto ao aplicativo por meio do repositório do GitHub. +- conhecer o espaço de trabalho, incluindo o backlog criado pelo modelo. +- experimentar um chat rápido para saber mais sobre o próprio aplicativo. + +## Cenário + +Sua equipe está adotando agentes de IA para trabalhar em um backlog crescente. O aplicativo Copilot oferece um único lugar para orientar esse trabalho: selecionar issues, executar agentes, revisar alterações e fazer merge de pull requests. Nesta lição, você instalará e conectará o aplicativo e aprenderá a iniciar uma conversa sobre o projeto. + +> [!NOTE] +> É necessário ter um plano elegível do Copilot: Copilot Student ou qualquer plano pago (Pro, Pro+, Business ou Enterprise). Se você usa o Copilot Business ou o Copilot Enterprise, o administrador deve habilitar a política **Copilot CLI** para que o aplicativo funcione. + +## Instalar e configurar o aplicativo GitHub Copilot + +Como você pode imaginar, a primeira etapa para usar o aplicativo GitHub Copilot é instalá-lo. Há versões disponíveis para Windows, macOS e Linux. Vamos instalar o aplicativo, autenticar a conta e adicionar o repositório Tailspin Toys. + +1. Em um navegador, abra a [página inicial do aplicativo GitHub Copilot][download-app]. +2. Baixe o aplicativo para sua plataforma e instale-o seguindo as instruções da página. +3. Abra o aplicativo após a instalação. +4. Selecione **Sign in to GitHub** e siga as instruções para se autenticar. Se você usa o GitHub Enterprise Server, escolha **Use GitHub Enterprise** e informe o endereço do servidor quando solicitado. +5. Após a autenticação, o aplicativo perguntará sobre a conexão dos seus repositórios. Selecione o repositório Tailspin Toys que você acabou de criar, cujo nome deve ser `/tailspin-toys`. +6. Selecione **Continue** para continuar a integração. +7. Quando o aplicativo solicitar um tema, selecione aquele que mais lhe agrada e depois selecione **Finish**. + +> [!NOTE] +> Se a sua cópia do Tailspin Toys não aparecer automaticamente na lista, você poderá adicioná-la depois de concluir a integração no aplicativo. Ao final, o aplicativo Copilot exibirá a tela inicial. Nela, selecione **Choose from GitHub**, pesquise o repositório pelo nome (\/tailspin-toys) e selecione-o. O repositório será adicionado ao aplicativo Copilot. + +## Conhecer o espaço de trabalho + +Com o projeto conectado, reserve um momento para conhecer o espaço de trabalho. O aplicativo organiza tudo em algumas áreas na barra lateral: + +- **Sessions**: onde os agentes trabalham. Cada sessão é executada em seu próprio espaço de trabalho isolado, permitindo executar várias sessões ao mesmo tempo sem que as alterações entrem em conflito. Você iniciará sua primeira sessão na próxima lição. +- **Quick chats**: conversas leves para perguntas e brainstorming que não precisam de branch ou espaço de trabalho próprios. Você experimentará uma ao final desta lição. +- **My work**: suas issues e pull requests, exibidos por meio da **integração nativa com o GitHub**. Nessa área, você pode procurar e filtrar issues e pull requests, verificar o status da CI, iniciar uma sessão a partir de uma issue e revisar pull requests sem sair do aplicativo. +- **Automations**: tarefas de agente salvas que são executadas em uma agenda ou sob demanda. Você criará uma perto do fim deste percurso. + +### Localizar o backlog criado pelo modelo + +Como o aplicativo tem integração nativa com o GitHub, o trabalho pendente no repositório aparece dentro dele. Quando você criou o repositório a partir do modelo, um backlog de issues foi criado. Vamos confirmar que ele está disponível. + +1. Selecione **My work** na barra lateral. +2. Confirme que você vê as três issues criadas pelo modelo para o backlog: + + - Allow users to filter games by category and publisher + - Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments + - Stretch Goal: Implement pagination on the game list page + +3. Selecione uma issue para ler os detalhes. Cada issue também serve como ponto de partida para uma sessão de agente. Você começará a trabalhar com elas mais adiante neste percurso. + +> [!NOTE] +> A lista de itens em My work é filtrada automaticamente para exibir somente itens dos repositórios adicionados ao aplicativo Copilot. Quer ver itens de trabalho de outros repositórios? Adicione-os ao aplicativo. + +## Experimentar um chat rápido + +Uma ótima maneira de se familiarizar com o aplicativo é usá-lo para saber mais sobre o *próprio aplicativo*, e um **chat rápido** é a ferramenta ideal. Os chats rápidos permitem fazer perguntas ou brainstorming sem criar uma branch ou worktree. Por isso, são perfeitos para perguntas rápidas e descartáveis, sem exigir uma sessão. + +1. Na barra lateral, selecione **+** ao lado de **Quick chats** para abrir um novo chat. +2. Pergunte ao aplicativo como funcionam as próprias sessões: + + ```plaintext + How does the GitHub Copilot app use worktrees? + ``` + +3. Leia a resposta na visualização da conversa. Você verá que cada sessão é executada em seu próprio git worktree isolado, o que permite executar vários agentes em paralelo sem que as alterações entrem em conflito. Você pode continuar a conversa ou iniciar um novo chat a qualquer momento. + +## Resumo e próximos passos + +Parabéns! Você instalou o aplicativo GitHub Copilot, conectou o projeto e explorou o espaço de trabalho. Você aprendeu a: + +- instalar o aplicativo e entrar no GitHub. +- adicionar um projeto por meio do repositório do GitHub. +- conhecer o espaço de trabalho e localizar o backlog criado em **My work**. +- usar um chat rápido para fazer uma pergunta rápida e descartável. + +Em seguida, você iniciará sua primeira sessão de agente e fará a primeira alteração no projeto: exibir uma avaliação por estrelas nos cards dos jogos. Continue para a [Lição 2 - Executar sua primeira sessão de agente][next-lesson]. + +## Recursos + +- [Sobre o aplicativo GitHub Copilot][about-copilot-app] +- [Introdução ao aplicativo GitHub Copilot][getting-started] +- [Trabalhar com sessões de agente no aplicativo GitHub Copilot][agent-sessions] + +[ex0]: ../0-prerequisites/ +[next-lesson]: ../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/docs/src/content/docs/pt-br/app/2-add-star-rating.md b/docs/src/content/docs/pt-br/app/2-add-star-rating.md new file mode 100644 index 0000000..3a546d5 --- /dev/null +++ b/docs/src/content/docs/pt-br/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "Lição 2 - Executar sua primeira sessão de agente" +description: "Inicie sua primeira sessão de agente no aplicativo GitHub Copilot, faça uma pequena alteração nos cards dos jogos e integre-a como seu primeiro pull request." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +Na lição anterior, você conheceu o espaço de trabalho e usou um chat rápido. Agora é hora de iniciar uma **sessão de agente** e fazer sua primeira alteração no projeto. A mudança será pequena: os dados dos jogos já têm uma avaliação por estrelas, mas os cards dos jogos na página inicial ainda não a exibem. Você pedirá ao agente que mostre essa avaliação, revisará a alteração e fará o merge dela como seu primeiro pull request. + +Nesta lição, você vai: + +- iniciar uma sessão de agente e aprender como ela é estruturada. +- pedir ao agente que faça uma alteração pequena e específica no projeto. +- revisar a alteração na visualização de diff do espaço de trabalho. +- executar o aplicativo localmente para confirmar a alteração no navegador. +- abrir e fazer merge do seu primeiro pull request. + +## Cenário + +Cada jogo no Tailspin Toys pode ter uma avaliação por estrelas, que já aparece na página de detalhes do jogo. No entanto, os cards dos jogos na página inicial mostram apenas título, categoria, distribuidora e descrição. Como aquecimento, você fará com que o agente exiba em cada card a avaliação existente. Essa alteração pequena e independente é perfeita para sua primeira sessão. + +## Anatomia de uma sessão + +Uma **sessão** é uma conversa com um agente executada em seu próprio espaço de trabalho isolado. Cada sessão recebe um **git worktree e uma branch dedicados**, o que permite executar várias sessões ao mesmo tempo, uma adicionando um recurso e outra corrigindo um bug, sem que as alterações entrem em conflito. Suas sessões aparecem na barra lateral agrupadas por repositório. Selecione qualquer uma delas para acessá-la. + +Em uma sessão, você verá três elementos: a **conversa** com o agente, a **atividade de ferramentas** do agente enquanto ele explora e edita arquivos e a lista de **arquivos alterados** com os respectivos diffs. + +## Iniciar uma sessão e solicitar a alteração + +Vamos iniciar uma nova sessão para começar a explorar o projeto e implementar o recurso. Em uma [lição anterior][prior-lesson], você adicionou o projeto por meio do repositório do GitHub. Criaremos uma nova sessão para esse repositório e solicitaremos a alteração. + +1. Volte ao aplicativo GitHub Copilot ou abra-o. +2. Selecione **Home screen**. +3. Verifique se `tailspin-toys` está selecionado como repositório. + + ![Caixa de prompt do aplicativo GitHub Copilot com o seletor de repositório definido como tailspin-toys e o seletor de modelo exibido abaixo do prompt](../../_images/app-2-start-session.png) + +4. Use o prompt a seguir para solicitar a alteração: + + ```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] +> Observe que o prompt contém o nome do arquivo que o Copilot deve atualizar. Embora não seja obrigatório especificar os arquivos que o Copilot deve incluir no trabalho, indicar a direção certa ajuda o Copilot a gerar código mais rapidamente e reduz o uso de tokens. + +5. Selecione Enter para enviar o prompt ao Copilot. + +O aplicativo Copilot começa criando um novo worktree, uma cópia isolada do projeto. Em seguida, ele explora o projeto, localiza os arquivos que precisam ser atualizados e cria o código necessário para adicionar o novo recurso. Você acabou de adicionar um recurso com o aplicativo Copilot. + +## Revisar o diff + +Todas as alterações geradas por IA devem ser revisadas antes do merge, mesmo as pequenas. Vamos explorar as alterações diretamente no aplicativo Copilot. + +1. No canto superior direito do aplicativo, selecione **Toggle review panel**. A tela de diff será aberta com todas as alterações pendentes feitas pelo Copilot. + + ![Barra de ferramentas superior do aplicativo GitHub Copilot com uma seta apontando para o botão Toggle review panel à direita de Create PR](../../_images/app-2-review-panel.png) + +2. Você verá código adicionado a `GameCard.astro`, o arquivo principal usado para exibir os detalhes do jogo. Ele deve ser semelhante ao exemplo a seguir: um pequeno bloco que renderiza a avaliação quando ela existe e usa "No rating yet" quando `starRating` é `null`: + + ```astro + {game.starRating !== null ? ( + + ★ {game.starRating} / 5 + + ) : ( + + No rating yet + + )} + ``` + +> [!NOTE] +> Como o Copilot, assim como todas as ferramentas de IA generativa, é probabilístico, e não determinístico, o código exato pode ser diferente do exemplo. No entanto, ele deve ser relativamente semelhante. + +## Verificar as alterações + +Não devemos apenas ler o código e presumir que ele funciona. Também precisamos testar tudo visualmente. Para isso, iniciaremos o aplicativo no terminal e confirmaremos o funcionamento. O aplicativo Copilot inclui um terminal. + +1. No painel de revisão à direita do aplicativo Copilot, selecione **Terminal**. Se não houver um botão **Terminal**, selecione **+** (identificado como **Open in panel**) e depois selecione **Terminal**. + + ![Botão Terminal no painel de revisão do aplicativo GitHub Copilot](../../_images/app-terminal-screenshot.png) + +2. Digite o comando a seguir na janela do terminal para iniciar o servidor de desenvolvimento do aplicativo Web: + + ```shell + npm run dev + ``` + +3. Quando o servidor iniciar, o que levará apenas alguns instantes, abra uma janela do navegador. +4. Acesse http://localhost:4321. +5. Agora você deve ver avaliações por estrelas em todos os jogos da página inicial. +6. Volte à janela do terminal. +7. Selecione Ctrl+C para interromper o servidor de desenvolvimento. + +## Abrir e fazer merge do primeiro pull request + +A alteração está correta. Agora é hora de entregá-la. Você pedirá ao agente que abra um pull request e depois fará a revisão e o merge no github.com. Por enquanto, gerenciaremos esse processo manualmente. Em uma próxima lição, veremos como o Copilot pode automatizar parte desse trabalho. + +1. No canto superior direito, selecione **Create PR**. +2. Se solicitado, selecione **Sign in with your browser** e siga as instruções para se autenticar. +3. O Copilot começará a criar o PR. + +Após a criação do PR, o Copilot monitorará os fluxos de trabalho do repositório que precisam ser executados. Depois de alguns instantes, o botão no canto superior direito mudará para **Ready to merge**, indicando que o PR está pronto para o merge. + +4. Selecione o indicador **PR** logo acima do chat para abrir o PR no painel de revisão e visualizá-lo. Faça as revisões necessárias nesse painel. +5. Quando estiver tudo pronto, selecione **Ready to merge**. +6. Na nova caixa de diálogo, selecione **Merge pull request** para fazer o merge do pull request. + +Você acaba de enviar um novo recurso para o site. + +## Resumo e próximos passos + +Você iniciou sua primeira sessão de agente e entregou sua primeira alteração. Especificamente, você: + +- iniciou uma sessão de agente e aprendeu como as sessões são estruturadas. +- orientou o agente a fazer uma alteração pequena e específica nos cards dos jogos. +- revisou a alteração na visualização de diff do espaço de trabalho. +- executou o aplicativo localmente para confirmar a avaliação por estrelas no navegador. +- abriu um pull request e fez o merge por conta própria no github.com. + +Em seguida, você usará o aplicativo para adicionar um padrão de instruções personalizadas ao repositório, começando por uma das issues do backlog. Continue para a [Lição 3 - Orientar o Copilot com instruções personalizadas][next-lesson]. + +## Recursos + +- [Trabalhar com sessões de agente no aplicativo GitHub Copilot][agent-sessions] +- [Sobre o aplicativo GitHub Copilot][about-copilot-app] +- [Gerenciar issues e pull requests com o aplicativo GitHub Copilot][managing-issues-prs] + +[prior-lesson]: ../1-install-copilot-app/#instalar-e-configurar-o-aplicativo-github-copilot +[next-lesson]: ../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/docs/src/content/docs/pt-br/app/3-custom-instructions.md b/docs/src/content/docs/pt-br/app/3-custom-instructions.md new file mode 100644 index 0000000..73f946f --- /dev/null +++ b/docs/src/content/docs/pt-br/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "Lição 3 - Orientar o Copilot com instruções personalizadas" +description: "Use o aplicativo GitHub Copilot para adicionar ao repositório um padrão de instruções personalizadas, começando por uma issue do backlog e fazendo o merge da alteração como um pull request." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +O contexto é fundamental ao trabalhar com IA generativa. Se uma tarefa precisa ser realizada de determinada maneira ou se há informações de apoio que o Copilot deve conhecer, esse contexto precisa estar disponível. Uma das ferramentas mais eficientes para isso são os [arquivos de instruções][instruction-files], que descrevem não apenas *qual* código você deseja, mas *como* ele deve ser estruturado. Nesta lição, você adicionará um padrão de documentação ao repositório. Você fará isso da mesma forma que realizará a maior parte do trabalho daqui em diante: começando por uma issue do backlog e permitindo que o agente faça a alteração. + +Nesta lição, você vai: + +- explorar como as instruções do repositório e os arquivos de instruções com escopo de caminho chegam ao agente. +- iniciar uma sessão a partir da issue de instruções no backlog. +- pedir ao agente que adicione um padrão de documentação a `.github/copilot-instructions.md`. +- revisar a alteração e fazer o merge dela como um pull request. + +## Cenário + +Como toda boa equipe de desenvolvimento, a Tailspin Toys tem diretrizes e requisitos para as práticas de desenvolvimento. Entre eles estão: + +- A documentação deve ser adicionada ao código na forma de comentários de documentação TSDoc. +- A formatação deve ser documentada e aplicada por meio de linting. + +Com os arquivos de instruções, você garantirá que o Copilot tenha as informações certas para executar as tarefas de acordo com as práticas destacadas. + +## Arquivos de instruções + +As instruções personalizadas permitem fornecer contexto e preferências ao Copilot para que ele compreenda melhor seu estilo de programação e seus requisitos. Esse recurso ajuda a orientar o Copilot para obter sugestões e trechos de código mais relevantes. Você pode especificar convenções de código, bibliotecas e até os tipos de comentários que deseja incluir no código. É possível criar instruções para todo o repositório ou para tipos de arquivo específicos, fornecendo contexto no nível da tarefa. + +Há dois tipos de arquivos de instruções: + +- `.github/copilot-instructions.md`, um único arquivo de instruções enviado ao Copilot em **todas** as solicitações do repositório. Esse arquivo deve conter informações no nível do projeto, ou seja, contexto relevante para a maioria das solicitações enviadas ao Copilot pelo chat ou pela CLI. Isso pode incluir a pilha de tecnologias usada, uma visão geral do que está sendo criado, boas práticas e outras orientações globais. +- Os arquivos `.github/instructions/*.instructions.md` podem ser criados para tarefas ou tipos de arquivo específicos. Você pode usá-los para fornecer diretrizes para determinadas linguagens, como TypeScript ou Astro, ou para tarefas como criar um componente de interface ou um novo conjunto de testes de unidade. + +> [!NOTE] +> O Copilot também oferece suporte a outros padrões para incorporar orientações por meio de AGENTS.md, CLAUDE.md e GEMINI.md, garantindo que ele sempre tenha o contexto correto. + +### Boas práticas para gerenciar arquivos de instruções + +Uma discussão completa sobre a criação de arquivos de instruções está fora do escopo do workshop. No entanto, os exemplos fornecidos no projeto de amostra demonstram uma abordagem representativa. Em termos gerais: + +- Mantenha as instruções em `copilot-instructions.md` concentradas em orientações no nível do projeto, como uma descrição do que está sendo criado, a estrutura do projeto e os padrões globais de código. +- Use arquivos `*.instructions.md` para fornecer instruções específicas para tipos de arquivo, como testes de unidade, componentes Astro e a camada de dados, ou para tarefas específicas. +- Use linguagem natural. Mantenha as orientações claras. Forneça exemplos de como o código deve e não deve ser. + +Não existe uma única maneira correta de criar arquivos de instruções, assim como não existe uma única maneira correta de usar IA. Com a experimentação, você descobrirá o que funciona melhor para seu projeto. + +> [!TIP] +> Todo projeto que usa o GitHub Copilot deve ter uma coleção robusta de arquivos de instruções. Ao explorar os arquivos deste projeto, você perceberá que há instruções para vários tipos de arquivos de código. +> +> Procura modelos ou um ponto de partida? Explore o [awesome-copilot][awesome-copilot], um repositório repleto de arquivos de instruções, agentes personalizados e outros recursos. + +## Explorar os arquivos de instruções personalizadas deste projeto + +Reserve um momento para ler os arquivos de instruções incluídos no repositório. Há um arquivo principal `copilot-instructions.md` e uma coleção de arquivos `*.instructions.md` para várias tarefas. Abra-os no editor ou na interface Web do GitHub. + +1. Se o painel de revisão ainda não estiver visível, abra-o selecionando **Toggle review panel** no canto superior direito. + + ![Barra de ferramentas superior do aplicativo GitHub Copilot com uma seta apontando para o botão Toggle review panel à direita de Create PR](../../_images/app-2-review-panel.png) + +2. Selecione **+** para adicionar um novo item ao painel de revisão. +3. Selecione **File**. +4. Pesquise `copilot-instructions.md`. +5. Selecione `copilot-instructions.md` na lista de arquivos para abri-lo. +6. Explore o arquivo. Observe a breve descrição do projeto e seções como **Agent notes**, **Code standards**, **Scripts** e **Repository Structure**. Em **Code standards**, observe a orientação aninhada **GitHub Actions Workflows**. Essas instruções se aplicam a qualquer interação com o Copilot. +7. Selecione **Show folder view** para abrir o navegador de pastas. + + ![Botão Show folder view no painel de revisão com um arquivo aberto no aplicativo GitHub Copilot](../../_images/app-show-folder-view.png) + +8. Acesse a pasta `.github/instructions` e explore os arquivos. Observe que há instruções para arquivos Astro, a camada de dados Drizzle, testes e muito mais. +9. Abra `.github/instructions/unit-tests.instructions.md`. Observe o campo `applyTo` na parte superior. Ele define um glob, relativo à raiz do repositório, que determina a quais arquivos as instruções se aplicam. Nesse caso, qualquer arquivo de teste TypeScript, por exemplo um arquivo correspondente a `**/*.test.ts`, será incluído. +10. Observe as instruções específicas para criar testes de unidade neste projeto. +11. Por fim, abra `.github/instructions/drizzle.instructions.md` e role até o final. Observe os links para outros arquivos de instruções, como `unit-tests.instructions.md`, e para arquivos existentes no projeto. Isso permite dividir conjuntos maiores de instruções em arquivos menores e reutilizáveis e indicar ao Copilot exemplos a serem seguidos ao gerar código. Os caminhos ali são relativos ao arquivo de instruções, e não à raiz do repositório. + +> [!NOTE] +> A seção **Code formatting requirements** em `copilot-instructions.md` documenta os padrões de código do projeto, mas ainda não exige documentação no código. Nas próximas etapas, você adicionará regras para comentários de documentação TSDoc e cabeçalhos de comentários nos arquivos. + +## Começar pela issue de instruções + +Na lição anterior, você iniciou uma sessão com um prompt direto. No entanto, a maior parte do trabalho começa com uma issue. Vamos criar uma nova sessão com base em uma issue criada para atualizar os arquivos de instruções e depois solicitar a atualização. + +> [!NOTE] +> Como os arquivos de instruções têm grande impacto no código gerado pelo Copilot, é preciso garantir que eles orientem o Copilot com clareza. Permitir que o Copilot crie uma primeira versão, como você fará nesta lição, é uma ótima abordagem. Depois, revise o resultado para confirmar que as atualizações atendem aos requisitos. + +1. Selecione **My work** na barra lateral. +2. Selecione a issue intitulada **Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments** para abri-la. +3. Selecione **New session** no canto superior direito para iniciar uma nova sessão com base na issue. + + ![Visualização da issue no aplicativo GitHub Copilot com uma seta apontando para o botão New session no canto superior direito](../../_images/app-new-session-from-issue.png) + +4. Use o prompt a seguir para solicitar que o Copilot atualize os arquivos de instruções de acordo com os requisitos documentados na 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! + ``` + +O Copilot fará as atualizações. + +## Revisar a alteração + +Vamos ler as atualizações feitas pelo Copilot e também pedir um exemplo do código que ele passará a gerar com base nas instruções atualizadas. + +1. Selecione **Changes** no canto superior direito para abrir as alterações no código. + + ![Abas do painel da sessão no aplicativo GitHub Copilot com uma seta apontando para a aba Changes](../../_images/app-select-changes.png) + +2. Revise o arquivo de instruções atualizado. Confirme se ele contém as diretrizes para adicionar documentação e comentários ao código. + +> [!NOTE] +> Como a IA é probabilística, e não determinística, o texto exato pode variar. + +3. Use o prompt a seguir para pedir ao Copilot que crie um exemplo do código que passará a gerar: + + ```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. Revise o código proposto pelo Copilot. Observe os comentários de documentação TSDoc e o comentário de cabeçalho do arquivo, exatamente como solicitado pelas instruções atualizadas. + +Você atualizou os arquivos de instruções do projeto e viu o impacto que eles terão. + +## Abrir e fazer merge do pull request + +Os arquivos de instruções se tornam ativos do repositório, portanto são compartilhados com o restante da equipe. Vamos criar um PR com esse trabalho, como faríamos com qualquer outro ativo. + +1. No canto superior direito, selecione **Create PR**. +2. Se solicitado, selecione **Sign in with your browser** e siga as instruções para se autenticar. +3. O Copilot começará a criar o PR. + +Após a criação do PR, o Copilot monitorará os fluxos de trabalho do repositório que precisam ser executados. Depois de alguns instantes, o botão no canto superior direito mudará para **Ready to merge**, indicando que o PR está pronto para o merge. + +4. Selecione **Ready to merge**. +5. Na nova caixa de diálogo, selecione **Merge pull request** para fazer o merge do pull request. + +> [!NOTE] +> Depois que o padrão for integrado à branch padrão, ele fará parte do projeto para toda a equipe e para cada nova sessão. Quando você iniciar a sessão de filtragem na próxima lição a partir de uma branch padrão atualizada, o agente seguirá esse padrão automaticamente. O código TypeScript gerado incluirá comentários de documentação TSDoc sem que você precise solicitá-los, uma demonstração pequena, mas concreta, de como as instruções moldam o código gerado. + +## Resumo e próximos passos + +Você explorou como o aplicativo obtém contexto dos arquivos de instruções e usou uma sessão para adicionar e integrar um padrão para todo o repositório. Especificamente, você: + +- explorou o arquivo `copilot-instructions.md` do repositório e os arquivos `*.instructions.md` com escopo de caminho. +- iniciou uma sessão a partir da issue de instruções no backlog. +- pediu ao agente que adicionasse um padrão de documentação a `.github/copilot-instructions.md`. +- revisou a alteração e fez o merge dela como um pull request. + +Em seguida, você criará o recurso de filtragem em uma nova sessão e verá como ele adota o padrão que acabou de integrar. Continue para a [Lição 4 - Criar um recurso com o Autopilot][next-lesson]. + +## Recursos + +- [Arquivos de instruções para personalização do GitHub Copilot][instruction-files] +- [Personalizar o aplicativo GitHub Copilot][customize-app] +- [Boas práticas para criar instruções personalizadas][instructions-best-practices] +- [Awesome Copilot — uma coleção de arquivos de instruções e outros recursos][awesome-copilot] + +[next-lesson]: ../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/github +[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/docs/src/content/docs/pt-br/app/4-build-filtering.md b/docs/src/content/docs/pt-br/app/4-build-filtering.md new file mode 100644 index 0000000..d36228c --- /dev/null +++ b/docs/src/content/docs/pt-br/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "Lição 4 - Criar um recurso com o Autopilot" +description: "Use os modos Plan e Autopilot no aplicativo GitHub Copilot para criar um recurso estático de filtragem no lado do cliente, observar como ele herda seu padrão de documentação e verificá-lo com uma skill de agente." +authors: + - geektrainer +lastUpdated: 2026-07-13 +--- + +Até agora, fizemos algumas pequenas atualizações no projeto. No entanto, alterações mais robustas exigem um processo mais completo. O aplicativo GitHub Copilot foi criado para trabalhar com nosso fluxo existente e ajudar a garantir que criemos as soluções certas da maneira correta. Esta é a primeira de três lições nas quais você seguirá um processo típico de desenvolvimento, começando por usar uma issue para gerar um novo recurso e uma skill de agente para executar os testes de validação e os linters. + +Nesta lição, você vai: + +- iniciar uma nova sessão a partir da issue de filtragem. +- usar o modo **Plan** para planejar o recurso e depois o **Autopilot** para criá-lo. +- confirmar que o código gerado segue o padrão de documentação integrado anteriormente. +- verificar o trabalho com a skill `quality-checks` do projeto. + +## Cenário + +A página inicial lista todos os jogos, mas os visitantes não conseguem restringir a lista. A issue de filtragem solicita que eles possam filtrar jogos por **categoria** e **distribuidora**. Vamos usar o Copilot para implementar essa funcionalidade. + +## Contexto + +Introduzir agentes de programação com IA no fluxo de desenvolvimento não muda os fundamentos. Na verdade, eles se tornam ainda mais importantes. A maioria das pessoas desenvolvedoras segue um fluxo semelhante a este: + +1. Abrir uma issue com os detalhes do que precisa ser feito. +2. Criar um plano do que precisa ser desenvolvido. +3. Criar e revisar o código. +4. Executar os testes para validar o código. +5. Validar manualmente a nova funcionalidade. +6. Criar um pull request (PR). +7. Depois que o código for revisado e o processo de integração contínua for concluído com êxito, fazer o merge do código. + +> [!NOTE] +> Os detalhes exatos variam de acordo com sua equipe e organização, mas a maioria dos fluxos será uma variação do processo descrito acima. + +Ao seguir essa abordagem padrão, você garante que o código gerado por IA atenda aos requisitos definidos e passe pelo mesmo processo de avaliação do código escrito manualmente. + +## Modos de sessão + +O **modo de sessão** controla o grau de autonomia do agente. Você pode defini-lo no menu suspenso abaixo do campo de prompt e alterá-lo a qualquer momento: + +- **Interactive**: você e o agente trabalham em conjunto. O agente sugere alterações e aguarda sua orientação antes de prosseguir. +- **Plan**: o agente cria primeiro um plano. Você revisa e aprova o plano antes que o agente o execute. +- **Autopilot**: o agente trabalha com total autonomia, escrevendo código, executando testes e iterando sem aguardar sua orientação. + +## Planejar o recurso de filtragem + +O melhor momento para detectar um possível problema é antes que qualquer código seja escrito, e a melhor maneira de fazer isso é planejar com antecedência. Ao planejar com o Copilot, você pedirá que ele gere um conjunto de etapas e documente a abordagem que seguirá. Em seguida, poderá revisar o plano e fazer sugestões para melhorá-lo antes de permitir que o Copilot gere o código com base nele. + +Vamos abrir a issue, iniciar uma nova sessão e criar um plano alternando para o modo Plan e fazendo a solicitação. + +1. Selecione **My work** na aba de navegação. +2. Selecione a issue intitulada **Allow users to filter games by category and publisher**. +3. Selecione **New session** no canto superior direito. + + ![Visualização da issue no aplicativo GitHub Copilot com uma seta apontando para o botão New session no canto superior direito](../../_images/app-new-session-from-issue.png) + +4. Selecione Shift+Tab até que o modo exibido seja **Plan**. + + ![Caixa de prompt do aplicativo GitHub Copilot com uma seta apontando para o seletor de modo definido como Plan](../../_images/app-4-plan-mode.png) + +5. Envie o prompt a seguir. A issue de filtragem já está no contexto da sessão porque você iniciou a partir dela: + + ```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. O agente pode fazer perguntas complementares enquanto cria o plano. Responda com base em como você criaria o recurso. + +> [!NOTE] +> Como o Copilot é probabilístico, as perguntas complementares exatas podem variar. Na verdade, ele pode não fazer nenhuma pergunta. Isso é perfeitamente normal. + +7. Ao terminar, o Copilot apresentará um resumo do plano. Revise-o. Ele deve propor a criação de consultas, a adição de controles de filtro e, naturalmente, testes. Se desejar, forneça feedback para refiná-lo. O agente incorporará suas sugestões em uma nova versão. + +## Criar com o Autopilot + +Com o plano pronto, vamos permitir que o Copilot crie a implementação. + +1. Na lista de opções da caixa de diálogo **Plan summary**, selecione a opção mais próxima de **Approve and implement with autopilot**. + +O Copilot começará a trabalhar na implementação. + +> [!NOTE] +> Se o Copilot não começar a criar automaticamente o código necessário, você poderá solicitar isso com um prompt como "Go ahead and start building out the plan!". +> +> A criação das atualizações necessárias levará vários minutos. O agente edita e cria arquivos, escreve e executa testes e faz iterações. Este é um bom momento para refletir sobre o que você explorou até agora ou fazer uma pausa. + +## Revisar as alterações + +Todo código gerado por IA precisa ser revisado antes do merge. Vamos revisar o código e executar o site para confirmar que tudo está correto. + +1. Selecione **Changes** no canto superior direito para abrir as alterações no código. + + ![Abas do painel da sessão no aplicativo GitHub Copilot com uma seta apontando para a aba Changes](../../_images/app-select-changes.png) + +2. Revise as alterações. Você deverá ver novos arquivos TypeScript e Astro, além de arquivos de teste. Observe que as novas funções auxiliares incluem comentários de documentação TSDoc e um comentário de cabeçalho do arquivo. O padrão de documentação integrado na Lição 3 foi aplicado automaticamente, sem que você precisasse solicitá-lo. +3. No painel de revisão à direita do aplicativo Copilot, selecione **Terminal**. Se não houver um botão **Terminal**, selecione **+** (identificado como **Open in panel**) e depois selecione **Terminal**. + + ![Botão Terminal no painel de revisão do aplicativo GitHub Copilot](../../_images/app-terminal-screenshot.png) + +4. Digite o comando a seguir na janela do terminal para iniciar o servidor de desenvolvimento do aplicativo Web: + + ```shell + npm run dev + ``` + +5. Quando o servidor iniciar, o que levará apenas alguns instantes, abra uma janela do navegador. +6. Acesse http://localhost:4321. +7. Agora você deve ver filtros disponíveis na página inicial. +8. Se algo não estiver correto, peça ao Copilot que faça as atualizações. +9. Quando estiver tudo certo, volte à janela do terminal. +10. Selecione Ctrl+C para interromper o servidor de desenvolvimento. + +## Verificar o trabalho com a skill quality-checks + +Você poderia apenas examinar o diff e considerar o trabalho concluído, mas a equipe definiu um padrão de qualidade e uma maneira repetível de verificá-lo. + +As **skills de agente** permitem fornecer ao Copilot orientações sobre como executar tarefas repetíveis, como executar testes, gerar builds ou criar pull requests. Uma skill é uma pasta de instruções, scripts e recursos que o agente pode carregar sob demanda. [Agent Skills é um padrão aberto][agent-skills-repo] usado por vários agentes. Por isso, a mesma skill funciona no Copilot Chat em modo de agente, no agente de nuvem do Copilot, no Copilot CLI e no aplicativo GitHub Copilot. + +As skills ficam na pasta `.github/skills` de um projeto ou globalmente em `~/.copilot/skills`. Cada skill é uma pasta que contém um arquivo `SKILL.md` com frontmatter YAML, formado por `name` e `description`, seguido pelas instruções em 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. +--- +``` + +As skills também podem incluir subpastas com scripts, ativos e materiais de referência. A estrutura completa é descrita na [especificação de skills de agente][agent-skills-spec]. + +> [!TIP] +> As skills são carregadas dinamicamente. O agente decide qual skill se aplica com base no campo `description`. Uma descrição clara e específica para o cenário é o que diferencia uma skill usada de uma ignorada. + +## Explorar a skill quality-checks + +Vamos explorar a skill para entender o que ela faz. + +1. Se o painel de revisão ainda não estiver visível, abra-o selecionando **Toggle review panel** no canto superior direito. + + ![Barra de ferramentas superior do aplicativo GitHub Copilot com uma seta apontando para o botão Toggle review panel à direita de Create PR](../../_images/app-2-review-panel.png) + +2. Selecione **+** para adicionar um novo item ao painel de revisão. +3. Selecione **File**. +4. Pesquise `SKILL.md`. +5. Selecione `SKILL.md .github/skills/quality-checks` na lista de arquivos para abri-lo. +6. Observe `name` e `description`. A descrição informa ao agente *quando* usar a skill: sempre que alterações no código precisarem ser testadas, verificadas por lint ou validadas antes de um commit, push ou merge. +7. Leia a skill. Observe que ela documenta qual script executa cada conjunto, como testes de unidade, testes de ponta a ponta do Playwright e ESLint, em que ordem e como depurar falhas comuns. Assim, o agente executa as verificações da maneira definida pela equipe, em vez de tentar adivinhar. + +## Executar as verificações + +Na mesma sessão de filtragem, peça ao agente que verifique o trabalho. Você não precisará nomear a skill, pois o agente a associará à sua solicitação. + +1. Volte ao aplicativo Copilot. +2. Chame diretamente a skill usando o comando de barra `/quality-checks` e selecione Enter. +3. Seguindo a skill, o agente executa os testes de unidade, o linter e os testes de ponta a ponta e relata os resultados. Se algo falhar, peça que ele corrija o problema e execute novamente as verificações até que tudo passe. +4. **Mantenha esta sessão aberta.** Na próxima lição, você adicionará o servidor MCP do Playwright e o usará para ver o recurso de filtragem funcionando em um navegador real. + +## Resumo e próximos passos + +Você criou um recurso real de ponta a ponta e o verificou de acordo com o padrão da equipe. Especificamente, você: + +- iniciou uma nova sessão a partir da issue de filtragem em um projeto atualizado. +- usou o modo Plan para planejar o recurso e o Autopilot para criá-lo. +- confirmou que o código auxiliar gerado seguiu o padrão de documentação integrado na Lição 3. +- verificou o trabalho com a skill `quality-checks`. + +Em seguida, você conectará o servidor MCP do Playwright e pedirá ao agente que explore o recurso de filtragem em um navegador real. Continue para a [Lição 5 - Testar com o servidor MCP do Playwright][next-lesson]. + +## Recursos + +- [Trabalhar com sessões de agente no aplicativo GitHub Copilot][agent-sessions] +- [Sobre Agent Skills][about-agent-skills] +- [Personalizar o aplicativo GitHub Copilot][customize-app] +- [Sobre sandboxes locais e na nuvem para o GitHub Copilot][sandboxes] + +[ex0]: ../0-prerequisites/ +[ex2]: ../2-add-star-rating/ +[ex3]: ../3-custom-instructions/ +[next-lesson]: ../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/docs/src/content/docs/pt-br/app/5-mcp-playwright.md b/docs/src/content/docs/pt-br/app/5-mcp-playwright.md new file mode 100644 index 0000000..1f9ea34 --- /dev/null +++ b/docs/src/content/docs/pt-br/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "Lição 5 - Testar com o servidor MCP do Playwright" +description: "Adicione o servidor MCP do Playwright ao aplicativo GitHub Copilot e peça ao agente que teste manualmente o recurso de filtragem em um navegador real." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +Na lição anterior, você criou e verificou o recurso de filtragem com o conjunto de testes automatizados do projeto. Os testes automatizam a validação do código, mas permitir que o agente confirme o comportamento é uma abordagem eficiente. Assim, o agente pode responder a problemas identificados na própria interface que está criando. Vamos explorar como o MCP dá aos agentes de IA acesso a recursos externos e adicionar o servidor MCP do Playwright para permitir que o Copilot interaja diretamente com o site que você está desenvolvendo. + +Nesta lição, você vai: + +- entender o que é o Model Context Protocol (MCP) e como o aplicativo GitHub Copilot o utiliza. +- adicionar o servidor MCP do Playwright nas configurações do aplicativo. +- pedir ao agente que controle um navegador e explore o recurso de filtragem. + +## Cenário + +Embora os testes de unidade e de ponta a ponta sejam importantes, validar atualizações na interface exige interagir com ela. Você quer permitir que o Copilot use o site em desenvolvimento como uma pessoa usuária faria, automatizando ainda mais o processo de alteração e aumentando a confiança de que as atualizações se comportam conforme o esperado. + +## O que é o Model Context Protocol (MCP)? + +O [Model Context Protocol (MCP)][mcp-blog-post] oferece aos agentes de IA uma forma de se comunicar com ferramentas e serviços externos em tempo real. Isso permite que eles acessem informações atualizadas, usando recursos, e realizem ações em seu nome, usando ferramentas. + +Essas ferramentas e esses recursos são acessados por meio de um servidor MCP, que funciona como uma ponte entre o agente de IA e as ferramentas e os serviços externos. O servidor MCP é responsável por gerenciar essa comunicação, seja com APIs existentes ou com ferramentas locais, como pacotes NPM. Cada servidor MCP representa um conjunto diferente de ferramentas e recursos que o agente de IA pode acessar. + +Alguns servidores MCP conhecidos são: + +- [**GitHub MCP Server**](https://github.com/github/github-mcp-server): oferece acesso a um conjunto de APIs para gerenciar repositórios do GitHub. Ele permite que o agente de IA realize ações como criar repositórios, atualizar repositórios existentes e gerenciar issues e pull requests. +- [**Playwright MCP Server**][playwright-mcp-server]: oferece recursos de automação de navegador usando o Playwright. Ele permite que o agente de IA realize ações como acessar páginas Web, preencher formulários e selecionar botões. + +Há muitos outros servidores MCP que fornecem acesso a diferentes ferramentas e recursos. O GitHub mantém um [registro de MCP](https://github.com/mcp) para facilitar a descoberta e as contribuições ao ecossistema. + +> [!CAUTION] +> Trate os servidores MCP como qualquer outra dependência do projeto. Antes de usar um servidor MCP, revise cuidadosamente o código-fonte, verifique quem o publicou e considere as implicações de segurança. Use apenas servidores MCP confiáveis e tenha cuidado ao conceder acesso a recursos ou operações confidenciais. + +## Adicionar o servidor MCP do Playwright + +Você adiciona e gerencia servidores MCP nas configurações do aplicativo. O aplicativo inclui um catálogo de servidores conhecidos, portanto o [servidor MCP do Playwright][playwright-mcp-server] está a poucas seleções de distância. + +1. Selecione Ctrl+, para abrir a página de configurações do aplicativo Copilot. +2. Selecione **MCP servers**. +3. Na caixa de diálogo de pesquisa, digite `Playwright`. +4. Selecione **Playwright** na lista de **Popular MCP servers**. +5. Selecione **Add server** para adicioná-lo à lista de servidores MCP disponíveis. +6. Selecione Esc para fechar a caixa de diálogo de configurações. + +Você adicionou o servidor MCP do Playwright. + +## Pedir ao Copilot que explore o recurso com o Playwright + +Vamos pedir ao Copilot que teste manualmente o recurso usando o servidor MCP do Playwright. + +1. Use o prompt a seguir para pedir ao Copilot que valide a nova funcionalidade: + + ```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. + ``` + +O Copilot iniciará um navegador por meio do servidor MCP do Playwright, percorrerá cada etapa e relatará o que encontrou. Você verá um navegador ser aberto no sistema para executar as tarefas. + +2. Leia o resumo e compare-o aos critérios de aceitação da issue. Se algo parecer incorreto, faça perguntas complementares ou peça que o agente corrija o código antes de abrir um pull request. +3. Mantenha esta sessão aberta, pois vamos concluí-la na próxima lição. + +O Copilot também validou a funcionalidade no navegador, explorando o recurso como uma pessoa usuária faria. + +## Resumo e próximos passos + +Parabéns! Você usou o servidor MCP do Playwright para explorar o recurso em um navegador real a partir do aplicativo GitHub Copilot. Recapitulando, você: + +- aprendeu o que é o Model Context Protocol (MCP) e como o aplicativo disponibiliza ferramentas MCP. +- adicionou o servidor MCP do Playwright nas configurações do aplicativo. +- pediu ao agente que controlasse um navegador e explorasse o recurso de filtragem. + +O recurso está criado, verificado e funcionando. Agora é hora de entregá-lo usando o **Agent Merge** para abrir e fazer o merge do pull request. Continue para a [Lição 6 - Fazer merge com o Agent Merge][next-lesson]. + +## Recursos + +- [O que é MCP e por que todos estão falando sobre ele?][mcp-blog-post] +- [Servidor MCP do Microsoft Playwright][playwright-mcp-server] +- [Configurar servidores MCP no aplicativo GitHub Copilot][customize-app] + +[next-lesson]: ../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/docs/src/content/docs/pt-br/app/6-agent-merge.md b/docs/src/content/docs/pt-br/app/6-agent-merge.md new file mode 100644 index 0000000..44e61b3 --- /dev/null +++ b/docs/src/content/docs/pt-br/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "Lição 6 - Fazer merge com o Agent Merge" +description: "Abra o pull request de filtragem, revise-o em My work e permita que o Agent Merge corrija o que estiver bloqueando e faça o merge para você, no nível mais alto da automação de merge." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +O recurso de filtragem está criado, verificado e funcionando em um navegador. A última etapa é fazer o merge. Você já fez isso duas vezes neste percurso. Nas duas ocasiões, abriu o pull request e fez o merge por conta própria no github.com. Desta vez, o aplicativo fará o trabalho operacional com o **Agent Merge**, que conduz todo o ciclo de vida de um pull request dentro do aplicativo. + +Nesta lição, você vai: + +- aprender o que é o Agent Merge e como ele automatiza o ciclo de vida do merge. +- habilitar o Agent Merge na sessão de filtragem. +- observar como ele cria o pull request, executa a CI e faz o merge quando todas as verificações passam. + +## Cenário + +Nos últimos módulos, você explorou vários níveis de automação, desde a criação de código até permitir que o Copilot valide diretamente uma interface. Para acelerar ainda mais o desenvolvimento, a Tailspin Toys quer descobrir se pull requests já avaliados e validados podem ter o merge feito automaticamente. + +## Apresentação do Agent Merge + +O **Agent Merge** permite automatizar a etapa final de integração de um pull request por meio do aplicativo Copilot. Quando você o habilita, a sessão do aplicativo lê o pull request, resolve o que estiver bloqueando o merge, como verificações de CI com falha, comentários de revisão e a necessidade de rebase, e faz o merge assim que o GitHub permite. Ele é executado em segundo plano, continua funcionando após reinicializações do aplicativo e é desativado automaticamente quando o pull request é integrado. + +Até aqui, você selecionou **Merge pull request** no github.com. O Agent Merge transfere essa responsabilidade ao agente, permitindo que você passe para a próxima tarefa enquanto ele conduz o PR até a conclusão. Você ainda revisa e aprova o trabalho; o agente apenas cuida das etapas operacionais finais. + +## Usar o Agent Merge para gerenciar o PR + +Você revisou o código manualmente, executou testes e permitiu que o Copilot validasse a interface. Agora é hora de integrar o novo código à base de código. Vamos permitir que o Agent Merge conduza o PR pela integração contínua (CI) e faça o merge. + +1. Volte à sessão mantida aberta no módulo anterior, na qual você estava adicionando a funcionalidade de filtragem. +2. No canto superior direito, selecione o menu suspenso ao lado de **Create PR**. +3. Selecione **Agent merge** para habilitá-lo. + + ![Menu suspenso Create PR expandido no aplicativo GitHub Copilot, com uma seta apontando para a opção Agent merge](../../_images/app-enable-agent-merge.png) + +4. O texto do botão mudará para **Agent merge**. +5. Selecione o botão **Agent merge** para iniciar o processo. + +O aplicativo Copilot começará a criar e gerenciar o PR. Primeiro, ele explora o projeto para determinar a melhor maneira de criar um PR e depois cria o novo PR. + +Após alguns instantes, você verá que o Copilot voltou a trabalhar, agora analisando as condições do PR, incluindo o processo de CI que executa todos os testes do repositório. Ele informará o status das revisões deixadas por outras pessoas da equipe, das verificações que precisam ser executadas e da possibilidade de fazer o merge do PR. + +6. Permita que o Agent Merge faça o merge do pull request selecionando o menu suspenso ao lado de **Agent merge** e depois **Merge pull request**. + + ![Menu suspenso Agent merge mostrando as ações permitidas ao agente — Address reviews, Fix CI failures, Resolve conflicts — com uma seta apontando para Merge pull request](../../_images/app-agent-merge-merge.png) + +7. Quando todos os processos de CI estiverem verdes, indicando que os testes passaram, o Copilot fará o merge do pull request. + +## Resumo e próximos passos + +Você automatizou várias partes do processo de desenvolvimento, incluindo a geração, o teste e a validação de código e, agora, o processo de pull request. Você: + +- aprendeu o que é o Agent Merge e como ele automatiza o ciclo de vida do merge. +- habilitou o Agent Merge na sessão de filtragem. +- observou como ele criou o pull request, executou a CI e fez o merge quando todas as verificações passaram. + +Em seguida, você explorará **canvases**, uma maneira mais completa de planejar e visualizar o trabalho com o agente. Continue para a [Lição 7 - Planejar com canvases][next-lesson]. + +## Recursos + +- [Gerenciar issues e pull requests com o aplicativo GitHub Copilot][managing-issues-prs] +- [Sobre o aplicativo GitHub Copilot][about-copilot-app] + +[next-lesson]: ../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/docs/src/content/docs/pt-br/app/7-canvases.md b/docs/src/content/docs/pt-br/app/7-canvases.md new file mode 100644 index 0000000..4363fbf --- /dev/null +++ b/docs/src/content/docs/pt-br/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "Lição 7 - Planejar com canvases" +description: "Crie um canvas compartilhado e orientado por agentes no aplicativo GitHub Copilot para planejar e acompanhar seu trabalho junto com o agente." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +Até agora, você orientou agentes pelo chat. No entanto, grande parte do trabalho não acontece em uma conversa, mas em um quadro, documento ou checklist. Os **canvases** oferecem a você e ao agente uma superfície compartilhada exatamente para esse tipo de trabalho, dentro do aplicativo. Nesta lição, você criará um canvas simples para planejar e acompanhar o backlog no qual vem trabalhando. + +Nesta lição, você vai: + +- entender o que é um canvas e quando usá-lo. +- criar um canvas compartilhado de quadro Kanban para fazer a triagem do backlog. +- salvar o canvas no repositório e integrá-lo para a equipe. +- abrir o canvas em uma nova sessão e começar a trabalhar a partir dele. + +## Cenário + +Analisar uma lista de issues pode ser uma tarefa desafiadora, mesmo nas melhores condições. As pessoas desenvolvedoras da Tailspin Toys procuram uma ferramenta que permita fazer rapidamente a triagem de issues e começar a trabalhar nelas no aplicativo Copilot. + +## O que é um canvas? + +Um [canvas][canvas-docs] é uma superfície interativa e compartilhada para um artefato de trabalho, como um plano, um quadro de triagem, um checklist de lançamento, um painel ou um documento. Embora o chat seja ótimo para descrever intenções e analisar ambiguidades, a maior parte do trabalho acontece em uma *superfície*. Os canvases permitem colaborar com o agente diretamente nessa superfície. + +Os canvases são **bidirecionais**: o agente pode atualizar o canvas enquanto trabalha, e você pode editar a mesma superfície. Quando você cria um canvas, o agente o desenvolve com base no prompt e no fluxo de trabalho. Você pode pedir que ele adicione, remova ou revise recursos durante o processo. Depois de criado, o canvas é aberto no painel direito do aplicativo. + +Alguns exemplos comuns incluem: + +- **Canvases Markdown** para planejar o dia e priorizar issues e pull requests. +- **Quadros Kanban agênticos** nos quais pessoas e agentes adicionam cards e movem o trabalho entre colunas. +- **Quadros de triagem de issues** que resumem as principais issues e os temas recorrentes de um repositório. + +## Por que usar um canvas? + +Use um canvas quando uma tarefa exigir estrutura, iteração e verificação e o chat não for suficiente. Um canvas permite: + +- fundamentar o trabalho do agente em um artefato real adequado ao seu fluxo de trabalho. +- orientar ou corrigir o trabalho diretamente na superfície compartilhada e depois permitir que o agente continue a partir das suas alterações. +- acompanhar o progresso como alterações visíveis em um artefato, e não apenas como respostas no chat. + +## Criar um canvas para acompanhar o trabalho + +Você já entregou muitos recursos: a avaliação por estrelas, o padrão de documentação e o recurso de filtragem foram integrados. No entanto, ainda há itens no backlog. Vamos criar um canvas para ajudar a fazer rapidamente a triagem do trabalho. + +1. Volte ao aplicativo GitHub Copilot ou abra-o. +2. Selecione **Home screen**. +3. Verifique se `tailspin-toys` está selecionado como repositório. +4. Na caixa de prompt, use o prompt a seguir para criar um canvas que atenda às nossas necessidades: + + ```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. + ``` + +O Copilot começará a criar o canvas. + +> [!NOTE] +> A criação levará alguns minutos. Como essa é uma tarefa complexa, talvez a primeira versão não atenda a todas as suas expectativas. Você pode continuar enviando prompts para criar a ferramenta ideal para suas necessidades. + +## Salvar o canvas e integrá-lo ao repositório + +Os canvases podem se tornar ativos do repositório, assim como arquivos de instruções e skills. Vamos pedir ao Copilot que adicione o canvas ao repositório e faça o merge para que toda a equipe possa usá-lo. + +1. Na mesma sessão, peça ao Copilot que salve o canvas no repositório usando o prompt a seguir: + + ```plaintext + Let's save this canvas definition to the repository so I can share it with my development team + ``` + +2. Depois que o Copilot salvar os arquivos do canvas, selecione o menu suspenso ao lado de **Create PR** no canto superior direito. +3. Selecione **Agent merge** para habilitá-lo. + + ![Menu suspenso Create PR expandido no aplicativo GitHub Copilot, com uma seta apontando para a opção Agent merge](../../_images/app-enable-agent-merge.png) + +4. O texto do botão mudará para **Agent merge**. +5. Selecione o botão **Agent merge** para iniciar o processo. + +O aplicativo Copilot começará a criar e gerenciar o PR. Primeiro, ele explora o projeto para determinar a melhor maneira de criar um PR e depois cria o pull request. + +Após alguns instantes, você verá que o Copilot voltou a trabalhar, agora analisando as condições do PR, incluindo o processo de CI que executa todos os testes do repositório. Ele informará o status das revisões deixadas por outras pessoas da equipe, das verificações que precisam ser executadas e da possibilidade de fazer o merge do PR. + +6. Permita que o Agent Merge faça o merge do pull request selecionando o menu suspenso ao lado de **Agent merge** e depois **Merge pull request**. + + ![Menu suspenso Agent merge mostrando as ações permitidas ao agente — Address reviews, Fix CI failures, Resolve conflicts — com uma seta apontando para Merge pull request](../../_images/app-agent-merge-merge.png) + +7. Aguarde até que todos os processos de CI sejam concluídos com êxito e fiquem verdes. Quando isso acontecer, o Copilot fará o merge do pull request automaticamente. + +Você criou um novo canvas compartilhado para a equipe. + +## Trabalhar no canvas + +Com o canvas criado, vamos iniciar uma nova sessão e usá-lo. + +1. No aplicativo Copilot, inicie uma nova sessão selecionando **New session** ao lado de **tailspin-toys**. +2. Peça ao Copilot que abra o canvas de triagem usando o prompt a seguir: + + ```plaintext + Open the triage issues canvas + ``` + +3. O canvas criado será aberto nessa nova sessão. +4. Selecione **Add to current context** em uma das issues que mais lhe interessam. +5. O Copilot começará a trabalhar na issue. + +Você usou um canvas criado por você para otimizar o processo de desenvolvimento. + +## Resumo e próximos passos + +Você criou uma superfície compartilhada na qual você e o agente podem colaborar. Você: + +- aprendeu o que são canvases e quando usá-los. +- criou com o agente um canvas compartilhado de quadro Kanban para triagem. +- salvou o canvas no repositório e fez o merge dele com o Agent Merge. +- abriu o canvas em uma nova sessão e o usou para começar a trabalhar. + +Com o backlog acompanhado, é hora de revisar tudo o que você criou e decidir os próximos passos. Continue para a [Lição 8 - Revisão e próximos passos][next-lesson]. + +## Recursos + +- [Trabalhar com extensões de canvas no aplicativo GitHub Copilot][canvas-docs] +- [Canvases no Awesome Copilot][awesome-copilot-canvases] +- [Sobre o aplicativo GitHub Copilot][about-copilot-app] + +[next-lesson]: ../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/canvases +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/src/content/docs/pt-br/app/8-review.md b/docs/src/content/docs/pt-br/app/8-review.md new file mode 100644 index 0000000..704a178 --- /dev/null +++ b/docs/src/content/docs/pt-br/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "Lição 8 - Revisão e próximos passos" +description: "Recapitule o percurso do aplicativo GitHub Copilot, automatize trabalhos recorrentes e explore os próximos passos." +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +Nas últimas lições, você levou um recurso da ideia ao merge com o aplicativo GitHub Copilot. Nesse processo, você: + +- conectou um repositório e conheceu o espaço de trabalho do aplicativo e o backlog criado pelo modelo. +- iniciou sessões a partir de uma tarefa direta e de issues e usou os modos Plan e Autopilot para controlar como o agente trabalha. +- orientou o agente com instruções personalizadas e uma skill reutilizável. +- testou o trabalho com o servidor MCP do Playwright em um navegador real. +- colaborou com o agente em um canvas compartilhado. +- entregou alterações avançando por níveis de automação de merge, desde fazer o merge por conta própria no github.com até permitir que o **Agent Merge** integrasse um pull request. + +Vamos automatizar parte do trabalho recorrente, analisar boas práticas e explorar os próximos passos. + +## Automatizar trabalhos recorrentes + +O aplicativo pode executar agentes para você em uma agenda ou sob demanda por meio de **automações**, ideais para tarefas rotineiras como fazer a triagem de novas issues ou recapitular atividades recentes. Vamos criar uma automação simples e não destrutiva. + +1. Selecione **Automations** na barra lateral e depois selecione **New automation**. +2. Dê um nome a ela, como `Recap my recent work`. +3. Escolha um gatilho. **Manual** permite executá-la sob demanda; **On a schedule** a executa automaticamente; **When an issue is created** reage a novas issues. Escolha **Manual** para esta lição. +4. Insira um prompt somente leitura para impedir que a automação faça alterações. Por exemplo: + + ```plaintext + Summarize the pull requests merged in this repository over the last week, and list any issues still open in the backlog. + ``` + +5. Escolha o projeto, ou seja, seu repositório Tailspin Toys, e crie a automação. +6. Execute-a sob demanda para ver o resultado. + +> [!TIP] +> As automações podem ser executadas localmente ou na nuvem. Habilite **Run in the cloud** e escolha as **Tools** que uma automação pode usar quando quiser que ela seja executada sem supervisão e de acordo com uma agenda. Mantenha as automações agendadas com escopo limitado e sem ações destrutivas até confiar nos resultados. + +## Boas práticas + +Ao usar qualquer ferramenta de IA, a infraestrutura ao redor dela influencia a qualidade dos resultados. Arquivos de instruções, skills e agentes personalizados tiveram uma função neste workshop. Invista neles e reutilize-os entre as sessões. + +Associe o **modo e o modelo** à tarefa. Use **Plan** para analisar uma abordagem antes de desenvolver, **Interactive** para acompanhar alterações específicas e **Autopilot** somente para tarefas isoladas e com escopo bem definido. Escolha um modelo mais rápido para edições rotineiras e um modelo mais avançado, com maior esforço de raciocínio, para trabalhos complexos. + +O contexto continua tão importante quanto a infraestrutura. Descrever claramente *o que* você quer criar, *por que* e *como* muda significativamente o resultado. Os chats rápidos são ótimos para definir o escopo de uma ideia antes de transformá-la em uma sessão completa. + +## Mais recursos para explorar + +Você percorreu o fluxo de trabalho principal. Veja outros recursos que valem a pena conhecer: + +- **Quick chats** para perguntas rápidas e descartáveis que não exigem uma sessão completa. +- **Rubber duck** para analisar um problema e receber feedback relevante antes de começar a desenvolver. +- [**Agentes personalizados**][custom-agents] para empacotar uma função, suas ferramentas e instruções para trabalhos especializados e repetíveis. +- [`/chronicle`][chronicle] para gerar uma narrativa do que aconteceu em uma sessão. +- [Bring your own key (BYOK)][byok] para usar modelos do seu próprio provedor, incluindo modelos locais por meio de Ollama, Foundry Local ou LM Studio. +- [Sandboxes na nuvem][sandboxes] para executar sessões em um ambiente isolado hospedado pelo GitHub. +- [Deep links][deep-links] para abrir o aplicativo diretamente em um repositório, uma sessão ou um prompt. + +## Próximos passos + +A melhor maneira de melhorar com qualquer ferramenta é continuar usando-a. Use-a em código de produção, em projetos pessoais ou naquele pequeno aplicativo que você planeja criar há anos. Compartilhe o que aprendeu com sua equipe e aprenda com as experiências dela. E, como sempre, explore a documentação. + +Para conhecer melhor o ecossistema do GitHub Copilot, confira o [percurso do VS Code](../../vscode/), o [percurso do Copilot CLI](../../cli/) ou o [percurso do agente de nuvem](../../cloud/). + +## Recursos + +- [Sobre o aplicativo GitHub Copilot][about-copilot-app] +- [Introdução ao aplicativo GitHub Copilot][getting-started] +- [Personalizar o aplicativo GitHub Copilot][customize] +- [Usar automações][using-automations] +- [Trabalhar com extensões de canvas][canvas-docs] +- [Sobre sandboxes locais e na nuvem][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/docs/src/content/docs/pt-br/app/index.md b/docs/src/content/docs/pt-br/app/index.md new file mode 100644 index 0000000..0cb6070 --- /dev/null +++ b/docs/src/content/docs/pt-br/app/index.md @@ -0,0 +1,57 @@ +--- +title: "Aplicativo GitHub Copilot" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +O [**aplicativo GitHub Copilot**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) é um aplicativo para desktop criado com base no Copilot CLI que reúne o desenvolvimento orientado por agentes em um espaço de trabalho único e focado. Ele oferece sessões paralelas de agentes, modos de sessão alternáveis, canvases compartilhados e gerenciamento nativo de issues e pull requests do GitHub, incluindo o **Agent Merge**, que conduz um pull request por rebases, feedback de revisão, correções de CI e merge. + +Ao longo destas lições, você instalará o aplicativo e configurará o projeto. Depois, conhecerá o espaço de trabalho do aplicativo e o backlog que o modelo criou para você. Você começará com uma pequena alteração, adicionando uma avaliação por estrelas, e então adicionará a partir de uma issue um padrão de instruções personalizadas, criará um recurso de filtragem em uma sessão isolada de agente e o verificará com uma skill reutilizável. Você adicionará o servidor MCP do Playwright para explorar o recurso em um navegador real e, em seguida, avançará por níveis de automação de merge até que o **Agent Merge** conclua o merge do pull request. Por fim, você colaborará em um canvas compartilhado e automatizará trabalhos recorrentes, completando todo o ciclo, da ideia ao recurso integrado. + +## Lições + +| Lição | Tópico | Descrição | +|--------|-------|-------------| +| [0. Pré-requisitos][ex0] | Configuração | Instale o Node.js e crie sua cópia do projeto Tailspin Toys | +| [1. Instalar o aplicativo Copilot][ex1] | Configuração | Instale o aplicativo, conecte seu projeto e conheça o espaço de trabalho | +| [2. Executar sua primeira sessão de agente][ex2] | Primeira alteração | Inicie uma sessão e entregue uma pequena alteração como seu primeiro pull request | +| [3. Orientar o Copilot com instruções personalizadas][ex3] | Contexto | Adicione a partir de uma issue um padrão de documentação e faça o merge | +| [4. Criar um recurso com o Autopilot][ex4] | Recurso principal | Use Plan e Autopilot para criar a filtragem e verifique-a com uma skill | +| [5. Testar com o MCP do Playwright][ex5] | Ferramentas externas | Adicione o servidor MCP do Playwright e explore o recurso em um navegador | +| [6. Fazer merge com o Agent Merge][ex6] | Merge | Permita que o Agent Merge corrija e integre o pull request de filtragem | +| [7. Planejar com canvases][ex7] | Colaboração | Crie um canvas compartilhado para planejar e acompanhar seu trabalho | +| [8. Revisão e próximos passos][ex8] | Resumo | Automatize tarefas recorrentes e explore os próximos passos | + +## Pré-requisitos + +Antes de participar deste workshop, verifique se você tem: + +- [ ] Uma conta do GitHub com um plano ativo **Copilot Student, Pro, Pro+, Business ou Enterprise** +- [ ] Um computador com **macOS, Linux ou Windows** +- [ ] O [Git instalado][install-git] no computador + +> [!TIP] +> Não tem um plano pago? Estudantes verificados podem obter o GitHub Copilot gratuitamente por meio do [GitHub Education][callout-student-plan-education]. O plano **Copilot Student** inclui os recursos de agente, MCP, revisão de código e Copilot CLI usados neste workshop. Portanto, você pode concluir todos os percursos com esse plano. + +> [!NOTE] +> Como o aplicativo Copilot é executado no seu computador, e não em um codespace, a [Lição 0][ex0] orienta você na instalação do Node.js e na criação da sua cópia do projeto antes da instalação do aplicativo. + +> [!NOTE] +> Se você usa o Copilot Business ou o Copilot Enterprise, o administrador deve habilitar a política **Copilot CLI** para que você possa usar o aplicativo. + +## Começar + +[**Comece pela Lição 0: Pré-requisitos →**][ex0] + +[ex0]: 0-prerequisites/ +[ex1]: 1-install-copilot-app/ +[ex2]: 2-add-star-rating/ +[ex3]: 3-custom-instructions/ +[ex4]: 4-build-filtering/ +[ex5]: 5-mcp-playwright/ +[ex6]: 6-agent-merge/ +[ex7]: 7-canvases/ +[ex8]: 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/docs/src/content/docs/pt-br/index.md b/docs/src/content/docs/pt-br/index.md new file mode 100644 index 0000000..7809723 --- /dev/null +++ b/docs/src/content/docs/pt-br/index.md @@ -0,0 +1,41 @@ +--- +title: "Agentes no ciclo de vida de desenvolvimento de software (SDLC)" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +As adições recentes aos recursos do GitHub Copilot oferecem ferramentas avançadas para apoiar pessoas desenvolvedoras durante todo o ciclo de vida de desenvolvimento de software (SDLC). Isso inclui trabalhar com problemas e solicitações de pull no GitHub, interagir com serviços externos e, é claro, criar código. Este laboratório explora esses recursos e apresenta casos de uso reais e dicas para aproveitar as ferramentas ao máximo. + +> [!CAUTION] +> Como o GitHub Copilot é probabilístico, e não determinístico, o código exato, os arquivos alterados e outros detalhes podem variar. Por isso, talvez você perceba pequenas diferenças entre as capturas de tela e os trechos de código do laboratório e o que aparece em sua experiência. Isso é esperado e faz parte da natureza do trabalho com essa categoria de ferramentas. +> +> Se algo parecer quebrado ou não estiver funcionando corretamente, peça ajuda a uma pessoa mentora! + +## Escolha seu ambiente + +O GitHub Copilot acompanha você onde quer que trabalhe. Escolha o ambiente que corresponde à forma como você quer desenvolver e conclua os exercícios usando um backlog compartilhado da Tailspin Toys. Cada ambiente começa com sua própria configuração, para que você possa ir direto ao que escolheu. + +### 🖥️ [VS Code](../vscode/) + +GitHub Copilot no **Visual Studio Code** e no GitHub Codespaces. Trabalhe com o modo de agente do Copilot Chat, servidores MCP e agentes personalizados sem sair do editor que você já usa — ideal para integrar a assistência de IA diretamente ao seu IDE. + +### 💻 [Copilot CLI](../cli/) + +**GitHub Copilot CLI** — um assistente baseado em agentes que é executado no terminal. Instale-o, conecte servidores MCP, gere código com o modo de planejamento e crie suas próprias habilidades, agentes personalizados e comandos de barra, tudo pela linha de comando. + +### 🤖 [Aplicativo Copilot](app/) + +O **aplicativo GitHub Copilot** — um aplicativo para desktop criado com base no Copilot CLI. Execute sessões paralelas de agentes, alterne entre modos de sessão, colabore em telas e gerencie problemas e solicitações de pull do GitHub de forma nativa — incluindo o **Agent Merge**, que conduz uma solicitação de pull por rebases, comentários de revisão, correções de CI e mesclagem. + +### ☁️ [Agente de nuvem do Copilot](../cloud/) + +**Agente de nuvem do Copilot** — um programador parceiro assíncrono que trabalha em problemas do GitHub em segundo plano. Atribua tarefas, oriente-o com agentes personalizados, acompanhe o progresso no painel de agentes e revise as solicitações de pull que ele abre. + +## Cenário + +Você é uma nova pessoa desenvolvedora na Tailspin Toys, uma empresa fictícia que oferece financiamento coletivo para jogos de tabuleiro com tema de desenvolvimento — um mercado enorme! O backlog da sua equipe já está registrado como problemas do GitHub e pronto para você começar — com trabalhos em funcionalidades, como filtragem e paginação, além de melhorias de qualidade, como acessibilidade e padrões de codificação. Você trabalhará de forma iterativa, explorando tanto o site quanto os recursos do Copilot para concluir as tarefas. + +## Comece agora + +Escolha um dos ambientes acima para começar — cada um é aberto com a configuração necessária para você iniciar o desenvolvimento. \ No newline at end of file diff --git a/docs/src/content/docs/zh-cn/app/0-prerequisites.md b/docs/src/content/docs/zh-cn/app/0-prerequisites.md new file mode 100644 index 0000000..b23c75d --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/0-prerequisites.md @@ -0,0 +1,85 @@ +--- +title: "第 0 课 - 先决条件" +description: "为 GitHub Copilot app 课程做好准备：为 Tailspin Toys 项目安装 Node.js，并通过模板创建自己的存储库副本。" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +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]，可以使用存储库的[开发容器][dev-containers]，无需在本地安装 Node.js。开发容器已包含 Node，两种方式无需同时使用。 + +## 设置实验存储库 + +你将使用自己的 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/app-0-use-template.png) + +3. 如果在 GitHub 或 Microsoft 主办的活动中参加本研讨会，请遵循导师提供的说明。否则，可在有权使用 GitHub Copilot 的组织中创建新存储库。 + + ![Create a new repository 表单，其中 github-samples/tailspin-toys 被设为模板，且已填写存储库名称](../../_images/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]: ../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/docs/src/content/docs/zh-cn/app/1-install-copilot-app.md b/docs/src/content/docs/zh-cn/app/1-install-copilot-app.md new file mode 100644 index 0000000..3c3728f --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/1-install-copilot-app.md @@ -0,0 +1,100 @@ +--- +title: "第 1 课 - 安装 GitHub Copilot app" +description: "安装 GitHub Copilot app，连接通过模板创建的存储库，熟悉工作区并尝试快速聊天。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +[**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 + - Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments + - Stretch Goal: Implement pagination on the game list page + +3. 选择一个议题以阅读详细信息。每个议题也可以作为智能体会话的启动点，后续课程会从这些议题开始工作。 + +> [!NOTE] +> My work 中的项目会自动筛选，仅显示已添加到 Copilot app 的存储库中的项目。要查看其他存储库中的工作项，请将相应存储库添加到应用。 + +## 尝试快速聊天 + +熟悉应用的一种好方法是用它来了解*应用本身*，而 **Quick chats** 正适合这种场景。通过快速聊天，无需创建分支或工作树即可提问或集思广益，非常适合无需会话的一次性问题。 + +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]: ../0-prerequisites/ +[next-lesson]: ../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/docs/src/content/docs/zh-cn/app/2-add-star-rating.md b/docs/src/content/docs/zh-cn/app/2-add-star-rating.md new file mode 100644 index 0000000..632d019 --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/2-add-star-rating.md @@ -0,0 +1,135 @@ +--- +title: "第 2 课 - 运行第一个智能体会话" +description: "在 GitHub Copilot app 中启动第一个智能体会话，对游戏卡片进行一项小改动，并通过第一个拉取请求合并更改。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +在上一课中，你介绍了工作区并使用了快速聊天。现在可以启动**智能体会话**，对项目进行第一次更改。此次改动很小：游戏数据中已有星级评分，但主页上的游戏卡片尚未显示。你将要求智能体显示评分、审查更改，并通过第一个拉取请求合并更改。 + +本课将介绍如何： + +- 启动智能体会话，并了解会话的结构。 +- 要求智能体对项目进行一项范围明确的小改动。 +- 在工作区差异视图中审查更改。 +- 在本地运行应用，并在浏览器中确认更改。 +- 打开并合并第一个拉取请求。 + +## 场景 + +Tailspin Toys 中的每款游戏都可以有星级评分，该评分已显示在游戏详情页上。但主页的游戏卡片只显示标题、类别、发行商和说明。作为热身，你将让智能体在每张卡片上显示现有评分。这项小型、独立的更改非常适合作为第一个会话任务。 + +## 会话剖析 + +**会话**是与智能体的对话，在独立工作区中运行。每个会话都有**专用的 git 工作树和分支**，因此可以同时运行多个会话，例如一个添加功能，另一个修复 bug，而不会造成更改冲突。会话按存储库分组显示在侧边栏中，选择任一会话即可切换。 + +会话中包含三类内容：与智能体的**对话**、智能体探索和编辑文件时的**工具活动**，以及带有差异的**已更改文件**列表。 + +## 启动会话并请求更改 + +现在启动新会话，探索项目并实现功能。在[上一课][prior-lesson]中，你从 GitHub 存储库添加了项目。接下来为该存储库创建新会话并请求更改。 + +1. 返回（或打开）GitHub Copilot app。 +2. 选择 **Home screen**。 +3. 确保为存储库选择了 `tailspin-toys`。 + + ![GitHub Copilot app 提示框，其中存储库选择器设为 tailspin-toys，提示框下方显示模型选择器](../../_images/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 添加了一项新功能。 + +## 审查差异 + +所有 AI 生成的更改在合并前都应接受审查，即使改动很小。接下来直接在 Copilot app 中探索这些更改。 + +1. 在应用右上角选择 **Toggle review panel**。差异屏幕会打开，显示 Copilot 所做的所有待处理更改。 + + ![GitHub Copilot app 顶部工具栏，箭头指向 Create PR 右侧的 Toggle review panel 按钮](../../_images/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/app-terminal-screenshot.png) + +2. 在终端窗口中输入以下命令，启动 Web 应用的开发服务器： + + ```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。 +5. 准备好后，选择 **Ready to merge**。 +6. 在新对话框窗口中选择 **Merge pull request**，合并拉取请求。 + +现在，新功能已推送到网站。 + +## 总结与后续步骤 + +你已启动第一个智能体会话，并交付了第一次更改。具体而言，你： + +- 启动了智能体会话，并了解了会话的结构。 +- 指示智能体对游戏卡片进行一项范围明确的小改动。 +- 在工作区差异视图中审查了更改。 +- 在本地运行应用，并在浏览器中确认了星级评分。 +- 打开并自行在 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]: ../1-install-copilot-app/#安装并配置-github-copilot-app +[next-lesson]: ../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/docs/src/content/docs/zh-cn/app/3-custom-instructions.md b/docs/src/content/docs/zh-cn/app/3-custom-instructions.md new file mode 100644 index 0000000..3114caa --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/3-custom-instructions.md @@ -0,0 +1,165 @@ +--- +title: "第 3 课 - 使用自定义指令引导 Copilot" +description: "使用 GitHub Copilot app 向存储库添加自定义指令标准，从待办议题开始，并通过拉取请求合并更改。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +使用生成式 AI 时，上下文至关重要。如果任务需要以特定方式完成，或 Copilot 应了解一些背景信息，就应提供这些上下文。[指令文件][instruction-files]是实现此目的最强大的工具之一，它不仅说明需要什么代码，还说明代码应如何组织。本课将向存储库添加文档标准，并采用后续大多数工作的方式：从待办议题开始，让智能体完成更改。 + +本课将介绍如何： + +- 探索存储库指令和路径范围指令文件如何传递给智能体。 +- 从待办事项中的指令议题启动会话。 +- 要求智能体向 `.github/copilot-instructions.md` 添加文档标准。 +- 审查更改，并通过拉取请求合并更改。 + +## 场景 + +与所有优秀的开发团队一样，Tailspin Toys 针对开发实践制定了一组准则和要求，其中包括： + +- 应以 TSDoc 文档注释的形式向代码添加文档。 +- 应记录格式规范，并通过 lint 强制执行。 + +通过指令文件，可以确保 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 始终具有正确的上下文。 + +### 管理指令文件的最佳实践 + +深入讨论如何创建指令文件超出了本研讨会的范围。不过，示例项目提供了具有代表性的方法。总体而言： + +- `copilot-instructions.md` 中的指令应专注于项目级指导，例如所构建内容的说明、项目结构和全局编码标准。 +- 使用 `*.instructions.md` 文件为文件类型（单元测试、Astro 组件、数据层）或特定任务提供具体指令。 +- 使用自然语言。保持指导清晰，并提供代码应采用和不应采用的示例。 + +创建指令文件没有唯一方法，使用 AI 同样如此。通过不断试验，可以找到最适合项目的方式。 + +> [!TIP] +> 每个使用 GitHub Copilot 的项目都应拥有一套完善的指令文件。探索本项目中的文件时，可以看到针对多种代码文件类型的指令文件。 +> +> 要查找模板或起点，请探索 [awesome-copilot][awesome-copilot]，其中包含大量指令文件、自定义智能体和其他资源。 + +## 探索此项目中的自定义指令文件 + +花一点时间阅读此存储库附带的指令文件：一个核心 `copilot-instructions.md`，以及一组用于不同任务的 `*.instructions.md` 文件。在编辑器或 GitHub Web UI 中打开这些文件。 + +1. 如果审查面板尚不可见，请选择右上角的 **Toggle review panel** 将其打开。 + + ![GitHub Copilot app 顶部工具栏，箭头指向 Create PR 右侧的 Toggle review panel 按钮](../../_images/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/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 文档注释和文件注释标头的规则。 + +## 从指令议题开始 + +上一课通过直接提示词启动了会话。不过，大多数工作都从议题开始。接下来，根据用于更新指令文件的议题创建新会话，再请求更新。 + +> [!NOTE] +> 指令文件对 Copilot 生成的代码影响很大，因此应确保它们能清晰地引导 Copilot。让 Copilot 创建第一版（正如本课将要做的），再由你审查更新是否满足要求，是一种有效方法。 + +1. 在侧边栏中选择 **My work**。 +2. 选择标题为 **Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments** 的议题，将其打开。 +3. 选择右上角的 **New session**，根据该议题启动新会话。 + + ![GitHub Copilot app 的议题视图，箭头指向右上角的 New session 按钮](../../_images/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**，打开代码更改。 + + ![GitHub Copilot app 会话面板选项卡，箭头指向 Changes 选项卡](../../_images/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 文档注释和文件标头注释，这正是更新后的指令所要求的内容。 + +现在，你已更新项目中的指令文件，并了解了更新带来的影响。 + +## 打开并合并拉取请求 + +指令文件会成为存储库中的资产，与团队其他成员共享。接下来像处理任何其他资产一样，为此次工作创建 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 文档注释。这是指令影响代码生成的一个虽小但真实的示例。 + +## 总结与后续步骤 + +你探索了应用如何从指令文件获取上下文，然后使用会话添加并合并存储库范围的标准。具体而言，你： + +- 探索了存储库中的 `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]: ../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/github +[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/docs/src/content/docs/zh-cn/app/4-build-filtering.md b/docs/src/content/docs/zh-cn/app/4-build-filtering.md new file mode 100644 index 0000000..653e19d --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/4-build-filtering.md @@ -0,0 +1,186 @@ +--- +title: "第 4 课 - 使用 Autopilot 构建功能" +description: "在 GitHub Copilot app 中使用 Plan 和 Autopilot 模式构建静态客户端筛选功能，观察它如何继承文档标准，并使用智能体技能进行验证。" +authors: + - geektrainer +lastUpdated: 2026-07-13 +--- + +本项目已完成一些小更新。但更复杂的更改需要更完善的流程。GitHub Copilot app 可以配合现有流程，确保以正确的方式构建正确的内容。这是连续三节课程中的第一节，你将遵循典型开发流程：先使用议题生成新功能，再使用智能体技能运行验证测试和 lint。 + +本课将介绍如何： + +- 从筛选议题启动新会话。 +- 使用 **Plan** 模式规划功能，再通过 **Autopilot** 构建功能。 +- 确认生成的代码遵循之前合并的文档标准。 +- 使用项目的 `quality-checks` 技能验证工作。 + +## 场景 + +主页列出了所有游戏，但访问者无法缩小列表范围。筛选议题要求允许用户按**类别**和**发行商**筛选游戏。接下来使用 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**。 + + ![GitHub Copilot app 的议题视图，箭头指向右上角的 New session 按钮](../../_images/app-new-session-from-issue.png) + +4. 选择 Shift+Tab，直到模式显示为 **Plan**。 + + ![GitHub Copilot app 提示框，箭头指向设为 Plan 的模式选择器](../../_images/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**，打开代码更改。 + + ![GitHub Copilot app 会话面板选项卡，箭头指向 Changes 选项卡](../../_images/app-select-changes.png) + +2. 审查更改。应会看到新的 TypeScript、Astro 和测试文件。注意，新辅助函数包含 TSDoc 文档注释和文件标头注释。这是第 3 课中合并的文档标准，无需提示便已自动应用。 +3. 在 Copilot app 右侧的审查面板中选择 **Terminal**。如果没有 **Terminal** 按钮，请选择 **+**（标记为 **Open in panel**），再选择 **Terminal**。 + + ![GitHub Copilot app 审查面板中的 Terminal 按钮](../../_images/app-terminal-screenshot.png) + +4. 在终端窗口中输入以下命令，启动 Web 应用的开发服务器： + + ```shell + npm run dev + ``` + +5. 服务器启动后（只需片刻），打开浏览器窗口。 +6. 转到 [http://localhost:4321](http://localhost:4321)。 +7. 现在应能在主页上看到筛选器。 +8. 如果有任何问题，可以要求 Copilot 进行更新。 +9. 满意后，返回终端窗口。 +10. 选择 Ctrl+C 停止开发服务器。 + +## 使用 quality-checks 技能验证工作 + +可以仅查看差异就认为工作完成，但团队已经定义了质量标准和可重复的检查方式。 + +**智能体技能**可指导 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** 将其打开。 + + ![GitHub Copilot app 顶部工具栏，箭头指向 Create PR 右侧的 Toggle review panel 按钮](../../_images/app-2-review-panel.png) + +2. 选择 **+**，向审查面板添加新项目。 +3. 选择 **File**。 +4. 搜索 `SKILL.md`。 +5. 从文件列表中选择 `SKILL.md .github/skills/quality-checks` 将其打开。 +6. 注意 `name` 和 `description`。说明会告知智能体*何时*使用该技能，即每当代码更改需要在提交、推送或合并前进行测试、lint 或验证时。 +7. 阅读该技能。它记录了哪个脚本运行哪个套件（单元测试、Playwright 端到端测试、ESLint）、运行顺序，以及如何调试常见故障。因此，智能体会按团队规定的方式运行检查，而不是猜测。 + +## 运行检查 + +在同一筛选会话中，要求智能体验证工作。你无需说出技能名称，智能体会根据请求进行匹配。 + +1. 返回 Copilot app。 +2. 使用 slash command `/quality-checks` 直接调用技能，然后选择 Enter。 +3. 智能体按照技能运行单元测试、lint 和端到端测试，并报告结果。如果有任何失败，请要求它修复问题并重新运行检查，直到全部通过。 +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]: ../0-prerequisites/ +[ex2]: ../2-add-star-rating/ +[ex3]: ../3-custom-instructions/ +[next-lesson]: ../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/docs/src/content/docs/zh-cn/app/5-mcp-playwright.md b/docs/src/content/docs/zh-cn/app/5-mcp-playwright.md new file mode 100644 index 0000000..5e28851 --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/5-mcp-playwright.md @@ -0,0 +1,86 @@ +--- +title: "第 5 课 - 使用 Playwright MCP 服务器测试" +description: "将 Playwright MCP 服务器添加到 GitHub Copilot app，并要求智能体在真实浏览器中手动测试筛选功能。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +上一课使用项目的自动化测试套件创建并验证了筛选功能。测试可以自动验证代码，但让智能体确认行为同样很有价值。智能体可以对它在实际 UI 中发现的问题作出响应。接下来探索 MCP 如何让 AI 智能体访问外部功能，并添加 Playwright MCP 服务器，使 Copilot 可以直接与正在构建的网站交互。 + +本课将介绍如何： + +- 了解模型上下文协议 (MCP) 及 GitHub Copilot app 如何使用它。 +- 从应用设置中添加 Playwright MCP 服务器。 +- 要求智能体操控浏览器并探索筛选功能。 + +## 场景 + +单元测试和端到端测试很重要，但验证 UI 更新需要实际与 UI 交互。你希望 Copilot 能像用户一样使用正在开发的网站，以进一步自动执行更改并提高对更新符合预期的信心。 + +## 什么是模型上下文协议 (MCP)？ + +[模型上下文协议 (MCP)][mcp-blog-post] 为 AI 智能体提供了与外部工具和服务通信的方式。借助 MCP，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 registry](https://github.com/mcp)，以提高生态系统的可发现性并促进贡献。 + +> [!CAUTION] +> 应像对待项目中的任何其他依赖项一样对待 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 已像用户一样探索功能，并在浏览器中验证了其行为。 + +## 总结与后续步骤 + +你使用 Playwright MCP 服务器，从 GitHub Copilot app 在真实浏览器中探索了功能。总结来说，你： + +- 了解了模型上下文协议 (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]: ../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/docs/src/content/docs/zh-cn/app/6-agent-merge.md b/docs/src/content/docs/zh-cn/app/6-agent-merge.md new file mode 100644 index 0000000..6001d43 --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/6-agent-merge.md @@ -0,0 +1,67 @@ +--- +title: "第 6 课 - 使用 Agent Merge 合并" +description: "打开筛选功能的拉取请求，在 My work 中进行审查，并让 Agent Merge 修复阻塞项并完成合并，这是合并自动化阶梯的最高一级。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +筛选功能已构建、验证，并确认可以在浏览器中正常工作。最后一步是将其合并。在本学习路径中，你已经合并过两次，每次都是自行打开拉取请求并在 github.com 上合并。这一次将使用 **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 管理 PR 的持续集成 (CI) 流程并完成合并。 + +1. 返回上一课中用于添加筛选功能且仍保持打开的会话。 +2. 在右上角选择 **Create PR** 旁的下拉菜单。 +3. 选择 **Agent merge** 以启用 agent merge。 + + ![GitHub Copilot app 中展开的 Create PR 下拉菜单，箭头指向 Agent merge 选项](../../_images/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 合并拉取请求。 + + ![Agent merge 下拉菜单显示智能体获准执行的操作：Address reviews、Fix CI failures 和 Resolve conflicts，箭头指向 Merge pull request](../../_images/app-agent-merge-merge.png) + +7. 所有 CI 流程变为绿色（表示测试通过）后，Copilot 会合并拉取请求。 + +## 总结与后续步骤 + +你已自动执行开发流程中的多个环节，包括生成代码、测试和验证代码，以及拉取请求流程。你： + +- 了解了 Agent Merge 及其如何自动执行合并生命周期。 +- 在筛选会话中启用了 Agent Merge。 +- 观察了它创建拉取请求、运行 CI，并在所有检查通过后完成合并。 + +接下来，你将探索**画布**，这是一种与智能体共同规划和可视化工作的更丰富方式。继续学习[第 7 课 - 使用画布规划][next-lesson]。 + +## 资源 + +- [使用 GitHub Copilot app 管理议题和拉取请求][managing-issues-prs] +- [关于 GitHub Copilot app][about-copilot-app] + +[next-lesson]: ../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/docs/src/content/docs/zh-cn/app/7-canvases.md b/docs/src/content/docs/zh-cn/app/7-canvases.md new file mode 100644 index 0000000..401bec6 --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/7-canvases.md @@ -0,0 +1,127 @@ +--- +title: "第 7 课 - 使用画布规划" +description: "在 GitHub Copilot app 中创建智能体驱动的共享画布，与智能体共同规划和跟踪工作。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +此前，你通过聊天指挥智能体。但许多工作并不只存在于对话中，而是呈现在看板、文档或检查清单上。借助**画布**，你和智能体可以直接在应用内共享一个适合此类工作的界面。本课将创建一个简单画布，用于规划和跟踪一直在处理的待办事项。 + +本课将介绍如何： + +- 了解画布是什么以及何时使用画布。 +- 创建共享的看板画布以对待办事项进行分类。 +- 将画布保存到存储库，并为团队合并更改。 +- 在新会话中打开画布，并从中开始工作。 + +## 场景 + +即使一切顺利，查看一长串议题也可能让人望而生畏。Tailspin Toys 的开发人员一直在寻找一种工具，用于快速对议题进行分类，并在 Copilot app 中着手处理。 + +## 什么是画布？ + +[画布][canvas-docs]是用于工作工件的共享交互式界面，例如计划、分类看板、发布检查清单、仪表板或文档。聊天非常适合描述意图和分析模糊问题，但大多数工作发生在具体的*界面*上。画布让你可以直接在该界面上与智能体协作。 + +画布支持**双向交互**：智能体可以在工作过程中更新画布，你也可以自行编辑同一个界面。创建画布时，智能体会根据提示词和工作流进行构建；之后，可以要求它添加、删除或修改功能。画布创建后会在应用右侧面板中打开。 + +常见示例包括： + +- 用于规划当天工作以及确定议题和拉取请求优先级的 **Markdown 画布**。 +- 由人员和智能体添加卡片并在列之间移动工作的**智能体看板**。 +- 汇总存储库重要议题和重复出现主题的**议题分类看板**。 + +## 为什么使用画布？ + +当任务需要结构、迭代和验证，且仅靠聊天不足以完成时，可以使用画布。画布让你能够： + +- 让智能体基于符合工作流的实际工件开展工作。 +- 直接在共享界面上引导或纠正工作，再让智能体从更改处继续。 +- 通过工件的可见更改检查进度，而不只是查看聊天回复。 + +## 创建画布来跟踪工作 + +你已经交付了许多内容：星级评分、文档标准和筛选功能都已合并。但待办事项中仍有其他工作。接下来创建画布，以便快速对这些工作进行分类。 + +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/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 合并拉取请求。 + + ![Agent merge 下拉菜单显示智能体获准执行的操作：Address reviews、Fix CI failures 和 Resolve conflicts，箭头指向 Merge pull request](../../_images/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 将开始处理该议题。 + +现在，你已使用自己创建的画布简化了开发流程。 + +## 总结与后续步骤 + +你创建了一个可与智能体协作的共享界面。你： + +- 了解了画布是什么以及何时使用画布。 +- 与智能体共同创建了共享的看板分类画布。 +- 使用 Agent Merge 将画布保存并合并到存储库。 +- 在新会话中打开画布，并使用它开始工作。 + +待办事项现已得到跟踪。接下来回顾已构建的所有内容，并了解后续方向。继续学习[第 8 课 - 回顾与后续步骤][next-lesson]。 + +## 资源 + +- [在 GitHub Copilot app 中使用画布扩展][canvas-docs] +- [Awesome Copilot 上的画布][awesome-copilot-canvases] +- [关于 GitHub Copilot app][about-copilot-app] + +[next-lesson]: ../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/canvases +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/src/content/docs/zh-cn/app/8-review.md b/docs/src/content/docs/zh-cn/app/8-review.md new file mode 100644 index 0000000..c00c5c7 --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "第 8 课 - 回顾与后续步骤" +description: "回顾 GitHub Copilot app 学习路径，自动执行重复性工作，并探索后续方向。" +authors: + - geektrainer +lastUpdated: 2026-07-09 +--- + +在过去几节课程中，你使用 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]：生成会话过程的叙述。 +- [Bring your own key (BYOK)][byok]：使用自己提供商的模型，包括通过 Ollama、Foundry Local 或 LM Studio 使用本地模型。 +- [Cloud sandboxes][sandboxes]：在 GitHub 托管的隔离环境中运行会话。 +- [Deep links][deep-links]：直接在应用中打开存储库、会话或提示词。 + +## 后续步骤 + +熟练使用任何工具的最佳方式都是持续使用。可将它用于生产代码、业余项目，或那个构思多年却始终没有动手构建的小应用。与团队分享经验，也向团队学习。并且一如既往地探索文档。 + +要探索 GitHub Copilot 生态系统的更多内容，请查看 [VS Code 学习路径](../../vscode/)、[Copilot CLI 学习路径](../../cli/)或 [Cloud agent 学习路径](../../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/docs/src/content/docs/zh-cn/app/index.md b/docs/src/content/docs/zh-cn/app/index.md new file mode 100644 index 0000000..0cd3ccb --- /dev/null +++ b/docs/src/content/docs/zh-cn/app/index.md @@ -0,0 +1,57 @@ +--- +title: "GitHub Copilot app" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +[**GitHub Copilot app**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) 是一款基于 Copilot CLI 构建的桌面应用，可将智能体驱动的开发集中到一个专注的工作区。它支持并行智能体会话、可切换的会话模式、共享画布，以及原生的 GitHub 议题和拉取请求管理功能。其中包括 **Agent Merge**，可处理拉取请求的变基、审查反馈、CI 修复与合并。 + +在这些课程中，你将安装应用并设置项目，然后熟悉应用工作区和模板为你创建的待办事项。你会先完成一项小改动，即添加星级评分；再根据议题添加自定义指令标准，在隔离的智能体会话中构建筛选功能，并使用可复用技能进行验证。随后，你将添加 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 或 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]: 0-prerequisites/ +[ex1]: 1-install-copilot-app/ +[ex2]: 2-add-star-rating/ +[ex3]: 3-custom-instructions/ +[ex4]: 4-build-filtering/ +[ex5]: 5-mcp-playwright/ +[ex6]: 6-agent-merge/ +[ex7]: 7-canvases/ +[ex8]: 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/docs/src/content/docs/zh-cn/index.md b/docs/src/content/docs/zh-cn/index.md new file mode 100644 index 0000000..886d3a9 --- /dev/null +++ b/docs/src/content/docs/zh-cn/index.md @@ -0,0 +1,41 @@ +--- +title: "软件开发生命周期 (SDLC) 中的智能体" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +GitHub Copilot 最近新增的功能为开发人员提供了贯穿整个软件开发生命周期 (SDLC) 的强大工具，包括处理 GitHub 上的议题和拉取请求、与外部服务交互，当然也包括创建代码。本实验将探索这些功能，并通过实际用例和技巧，帮助你充分发挥这些工具的价值。 + +> [!CAUTION] +> GitHub Copilot 具有概率性而非确定性，因此生成的具体代码、修改的文件等可能有所不同。因此，实验中的屏幕截图和代码片段可能与你的实际体验略有差异。这是正常现象，也是使用此类工具的固有特点。 +> +> 如果内容似乎有误或无法正常运行，请向导师求助！ + +## 选择操作环境 + +无论在哪里工作，都可以使用 GitHub Copilot。请选择符合开发方式的操作环境，并基于共用的 Tailspin Toys 待办事项完成相应练习。每种操作环境都有专属的设置步骤，可以直接开始所选路径。 + +### 🖥️ [VS Code](../vscode/) + +在 **Visual Studio Code** 和 GitHub Codespaces 中使用 GitHub Copilot。无需离开熟悉的编辑器，即可使用 Copilot Chat 智能体模式、MCP 服务器和自定义智能体。如果希望将 AI 辅助直接融入 IDE，这是理想选择。 + +### 💻 [Copilot CLI](../cli/) + +**GitHub Copilot CLI** 是一款在终端中运行的智能体助手。安装后，可以连接 MCP 服务器、使用计划模式生成代码，还能完全通过命令行构建自己的技能、自定义智能体和斜杠命令。 + +### 🤖 [Copilot App](app/) + +**GitHub Copilot app** 是一款基于 Copilot CLI 构建的桌面应用。它支持并行运行智能体会话、切换会话模式、在画布上协作，以及直接管理 GitHub 议题和拉取请求。其中包括 **Agent Merge**，可引导拉取请求完成变基、处理审查反馈、修复 CI 问题并最终合并。 + +### ☁️ [Copilot Cloud Agent](../cloud/) + +**Copilot 云智能体** 是一位异步结对编程伙伴，可在后台处理 GitHub 议题。可以分配工作、通过自定义智能体提供指导、在智能体仪表板中监控进度，并审查它创建的拉取请求。 + +## 场景 + +你是 Tailspin Toys 的新开发人员。这是一家虚构公司，为开发人员主题的桌游提供众筹服务，而这可是一个巨大的市场！团队的待办事项已经创建为 GitHub 议题，等待处理。其中既有筛选和分页等功能开发，也有无障碍支持和编码标准等质量改进。你将通过迭代完成这些任务，同时探索网站和 Copilot 的功能。 + +## 开始使用 + +选择上述操作环境即可开始。每种环境都会先引导完成所需设置，让你立即开始构建。 \ No newline at end of file