diff --git a/.github/workflows/localization-sync.yml b/.github/workflows/localization-sync.yml new file mode 100644 index 00000000..6ec1f921 --- /dev/null +++ b/.github/workflows/localization-sync.yml @@ -0,0 +1,584 @@ +name: Synchronize workshop localizations + +on: + push: + branches: [main] + paths: + - 'docs/README.md' + - 'docs/first-steps/*.md' + - 'docs/first-steps/**/*.md' + - 'docs/real-world-development/*.md' + - 'docs/real-world-development/**/*.md' + - 'website/astro.config.mjs' + - 'website/src/pages/real-world-development/**/*.astro' + # Locale outputs and sidebar translations are not triggers, preventing sync PRs from looping. + workflow_dispatch: + +permissions: {} + +concurrency: + group: localization-sync-${{ github.ref }} + cancel-in-progress: false + +jobs: + generate: + name: Generate localized workshop content + runs-on: ubuntu-latest + timeout-minutes: 45 + permissions: + contents: read + copilot-requests: write + outputs: + changed: ${{ steps.package.outputs.changed }} + changed_files: ${{ steps.detect.outputs.changed_files }} + steps: + - name: Check out trusted repository + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.11' + + - name: Detect English sources and localization inputs + id: detect + env: + BASE_SHA: ${{ github.event.before }} + EVENT_NAME: ${{ github.event_name }} + REF_NAME: ${{ github.ref }} + HEAD_SHA: ${{ github.sha }} + RUNNER_TEMP: ${{ runner.temp }} + run: | + python3 - <<'PY' + import os + import subprocess + from pathlib import Path + + event_name = os.environ["EVENT_NAME"] + base_sha = os.environ.get("BASE_SHA", "") + head_sha = os.environ["HEAD_SHA"] + + if event_name == "workflow_dispatch" and os.environ["REF_NAME"] != "refs/heads/main": + raise SystemExit("Run a full localization sync from the main branch.") + + full_sync = ( + event_name == "workflow_dispatch" + or not base_sha + or set(base_sha) == {"0"} + ) + changes = [] + if not full_sync: + result = subprocess.run( + ["git", "diff", "--name-status", "--no-renames", base_sha, head_sha], + check=True, + capture_output=True, + text=True, + ) + for line in result.stdout.splitlines(): + status, path = line.split("\t", 1) + changes.append((status, path)) + + full_sync = any( + path == ".github/skills/localizations/SKILL.md" + or path.startswith(".github/skills/localizations/rules/") + for _, path in changes + ) + + def is_source_markdown(path): + return path == "docs/README.md" or ( + path.endswith(".md") + and ( + path.startswith("docs/first-steps/") + or path.startswith("docs/real-world-development/") + ) + ) + + def is_english_redirect(path): + return ( + path.startswith("website/src/pages/real-world-development/") + and path.endswith(".astro") + ) + + if full_sync: + markdown_sources = [("FULL", "docs/README.md")] + for directory in ("docs/first-steps", "docs/real-world-development"): + markdown_sources.extend( + ("FULL", path.as_posix()) + for path in sorted(Path(directory).rglob("*.md")) + ) + redirect_sources = [ + ("FULL", path.as_posix()) + for path in sorted( + Path("website/src/pages/real-world-development").rglob("*.astro") + ) + ] + sidebar_changed = any( + path == "website/astro.config.mjs" for _, path in changes + ) + else: + markdown_sources = [ + (status, path) for status, path in changes if is_source_markdown(path) + ] + redirect_sources = [ + (status, path) for status, path in changes if is_english_redirect(path) + ] + sidebar_changed = any( + path == "website/astro.config.mjs" for _, path in changes + ) + + lines = [] + if full_sync: + lines.append("Synchronization mode: full sync.") + else: + lines.append("Synchronization mode: changed sources only.") + + lines.append("") + lines.append("English Markdown sources:") + lines.extend(f"{status} {path}" for status, path in markdown_sources) + lines.append("") + lines.append("English legacy redirect files:") + lines.extend(f"{status} {path}" for status, path in redirect_sources) + lines.append("") + if full_sync: + lines.append("Sidebar configuration: review existing localized labels.") + else: + lines.append( + "Sidebar configuration changed: " + + ("yes" if sidebar_changed else "no") + ) + + inputs_path = Path(os.environ["RUNNER_TEMP"]) / "localization-inputs.txt" + inputs_path.write_text("\n".join(lines) + "\n", encoding="utf-8") + changed = bool(markdown_sources or redirect_sources or sidebar_changed) + + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output: + output.write(f"changed={'true' if changed else 'false'}\n") + output.write("changed_files</`, following the existing full-HTML redirect pattern. Preserve the site base path, canonical URL, `noindex`, Pagefind exclusion, and correct localized destination. Do not edit English redirect pages. + + Modify only: + - Markdown under supported `docs//` directories. + - Locale-specific redirect pages under `website/src/pages//**/*.astro`. + - Locale-specific sidebar translation values in `website/astro.config.mjs`. + + Do not modify English workshop Markdown, shared images, localization rules, the localization skill, workflow files, or other site code. Do not commit, push, create branches, or create pull requests. Complete the translator and evaluator passes before finishing. + + The changed inputs are: + PROMPT + cat "$RUNNER_TEMP/localization-inputs.txt" + } > "$RUNNER_TEMP/localization-prompt.txt" + + copilot -p "$(cat "$RUNNER_TEMP/localization-prompt.txt")" \ + --allow-tool=read \ + --allow-tool=write \ + --allow-tool=grep \ + --allow-tool=glob \ + --allow-tool='shell(git diff:*)' \ + --allow-tool='shell(git ls-files:*)' \ + --allow-tool='shell(git log:*)' \ + --allow-tool='shell(git rev-parse:*)' \ + --allow-tool='shell(git show:*)' \ + --allow-tool='shell(git status:*)' \ + --no-ask-user + + - name: Guard and package generated changes + id: package + if: steps.detect.outputs.changed == 'true' + env: + RUNNER_TEMP: ${{ runner.temp }} + run: | + python3 - <<'PY' + import os + import subprocess + from pathlib import Path, PurePosixPath + + locales = { + path.stem + for path in Path(".github/skills/localizations/rules").glob("*.md") + } + + def allowed(path): + candidate = PurePosixPath(path) + if candidate.is_absolute() or ".." in candidate.parts: + return False + parts = candidate.parts + if path == "website/astro.config.mjs": + return True + if ( + len(parts) >= 3 + and parts[0] == "docs" + and parts[1] in locales + and candidate.suffix == ".md" + ): + return True + if ( + len(parts) >= 5 + and parts[:3] == ("website", "src", "pages") + and parts[3] in locales + and candidate.suffix == ".astro" + ): + return True + return False + + tracked = subprocess.run( + ["git", "diff", "--name-only", "--no-renames", "HEAD", "--"], + check=True, + capture_output=True, + ).stdout.decode().splitlines() + untracked = subprocess.run( + ["git", "ls-files", "--others", "--exclude-standard", "-z"], + check=True, + capture_output=True, + ).stdout.decode().split("\0") + changed = sorted(set(tracked + [path for path in untracked if path])) + + unexpected = [path for path in changed if not allowed(path)] + if unexpected: + raise SystemExit( + "Localization generated changes outside the allowlist:\n" + + "\n".join(unexpected) + ) + + if not changed: + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output: + output.write("changed=false\n") + print("The localization skill produced no output changes.") + raise SystemExit(0) + + if untracked and any(untracked): + subprocess.run( + ["git", "add", "-N", "--", *[path for path in untracked if path]], + check=True, + ) + + summary = subprocess.run( + [ + "git", "diff", "--summary", "--no-renames", "HEAD", "--", + "docs", "website/astro.config.mjs", "website/src/pages", + ], + check=True, + capture_output=True, + text=True, + ).stdout + if "120000" in summary or "100755" in summary: + raise SystemExit( + "Generated localization output must not contain symlinks or executable files." + ) + + patch = subprocess.run( + [ + "git", "diff", "--binary", "--no-renames", "HEAD", "--", + "docs", "website/astro.config.mjs", "website/src/pages", + ], + check=True, + capture_output=True, + ).stdout + if not patch: + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output: + output.write("changed=false\n") + print("The localization skill produced no patch.") + raise SystemExit(0) + + patch_path = os.path.join(os.environ["RUNNER_TEMP"], "localization.patch") + with open(patch_path, "wb") as patch_file: + patch_file.write(patch) + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output: + output.write("changed=true\n") + print(f"Packaged {len(changed)} localized output files.") + PY + + - name: Upload generated localization patch + if: steps.package.outputs.changed == 'true' + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: localization-patch + path: ${{ runner.temp }}/localization.patch + if-no-files-found: error + retention-days: 1 + + validate: + name: Validate generated localizations + needs: generate + if: needs.generate.outputs.changed == 'true' + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + outputs: + changed: ${{ steps.apply.outputs.changed }} + steps: + - name: Check out trusted repository + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + ref: ${{ github.sha }} + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.11' + + - name: Download generated localization patch + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: localization-patch + path: ${{ runner.temp }}/localization-artifact + + - name: Apply allowlisted localization patch + id: apply + env: + RUNNER_TEMP: ${{ runner.temp }} + run: | + python3 - <<'PY' + import os + import subprocess + from pathlib import Path, PurePosixPath + + locales = { + path.stem + for path in Path(".github/skills/localizations/rules").glob("*.md") + } + patch_path = os.path.join( + os.environ["RUNNER_TEMP"], "localization-artifact", "localization.patch" + ) + + def allowed(path): + candidate = PurePosixPath(path) + if candidate.is_absolute() or ".." in candidate.parts: + return False + parts = candidate.parts + if path == "website/astro.config.mjs": + return True + if ( + len(parts) >= 3 + and parts[0] == "docs" + and parts[1] in locales + and candidate.suffix == ".md" + ): + return True + if ( + len(parts) >= 5 + and parts[:3] == ("website", "src", "pages") + and parts[3] in locales + and candidate.suffix == ".astro" + ): + return True + return False + + numstat = subprocess.run( + ["git", "apply", "--numstat", patch_path], + check=True, + capture_output=True, + text=True, + ).stdout + paths = [line.split("\t", 2)[-1] for line in numstat.splitlines()] + unexpected = [path for path in paths if not allowed(path)] + if unexpected: + raise SystemExit( + "Localization artifact contains paths outside the allowlist:\n" + + "\n".join(unexpected) + ) + + summary = subprocess.run( + ["git", "apply", "--summary", patch_path], + check=True, + capture_output=True, + text=True, + ).stdout + if "120000" in summary or "100755" in summary: + raise SystemExit( + "Localization artifact must not contain symlinks or executable files." + ) + subprocess.run(["git", "apply", "--check", patch_path], check=True) + subprocess.run(["git", "apply", patch_path], check=True) + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output: + output.write("changed=true\n") + PY + + - name: Set up Node.js + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: '22' + cache: npm + cache-dependency-path: website/package-lock.json + + - name: Install site dependencies + working-directory: website + run: npm ci + + - name: Type-check generated site + working-directory: website + run: npm run check:all + + - name: Build generated site + working-directory: website + run: npm run build + + - name: Prepare Lychee root + run: | + mkdir -p "$RUNNER_TEMP/lychee-root" + ln -s "$GITHUB_WORKSPACE/website/dist" "$RUNNER_TEMP/lychee-root/copilot-workshops" + shell: bash + + - name: Check generated links with Lychee + uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.6.1 + with: + args: >- + --offline + --no-progress + --root-dir ${{ runner.temp }}/lychee-root + 'website/dist/**/*.html' + fail: true + + publish: + name: Publish localization review pull request + needs: [generate, validate] + if: needs.validate.outputs.changed == 'true' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + pull-requests: write + steps: + - name: Check out base branch + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + ref: main + fetch-depth: 0 + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.11' + + - name: Download validated localization patch + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: localization-patch + path: ${{ runner.temp }}/localization-artifact + + - name: Apply validated localization patch + env: + RUNNER_TEMP: ${{ runner.temp }} + run: | + python3 - <<'PY' + import os + import subprocess + from pathlib import Path, PurePosixPath + + locales = { + path.stem + for path in Path(".github/skills/localizations/rules").glob("*.md") + } + patch_path = os.path.join( + os.environ["RUNNER_TEMP"], "localization-artifact", "localization.patch" + ) + + def allowed(path): + candidate = PurePosixPath(path) + if candidate.is_absolute() or ".." in candidate.parts: + return False + parts = candidate.parts + if path == "website/astro.config.mjs": + return True + if ( + len(parts) >= 3 + and parts[0] == "docs" + and parts[1] in locales + and candidate.suffix == ".md" + ): + return True + if ( + len(parts) >= 5 + and parts[:3] == ("website", "src", "pages") + and parts[3] in locales + and candidate.suffix == ".astro" + ): + return True + return False + + numstat = subprocess.run( + ["git", "apply", "--numstat", patch_path], + check=True, + capture_output=True, + text=True, + ).stdout + paths = [line.split("\t", 2)[-1] for line in numstat.splitlines()] + unexpected = [path for path in paths if not allowed(path)] + if unexpected: + raise SystemExit( + "Localization artifact contains paths outside the allowlist:\n" + + "\n".join(unexpected) + ) + summary = subprocess.run( + ["git", "apply", "--summary", patch_path], + check=True, + capture_output=True, + text=True, + ).stdout + if "120000" in summary or "100755" in summary: + raise SystemExit( + "Localization artifact must not contain symlinks or executable files." + ) + subprocess.run(["git", "apply", "--check", patch_path], check=True) + subprocess.run(["git", "apply", patch_path], check=True) + PY + + - name: Create localization review pull request + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 + with: + token: ${{ github.token }} + add-paths: | + docs/ + website/astro.config.mjs + website/src/pages/ + branch: automation/localization-sync + base: main + delete-branch: true + title: 'docs: synchronize localized workshop content' + commit-message: 'docs: synchronize localized workshop content' + body: | + GitHub Copilot CLI ran the repository localization skill for these source and route inputs: + + ``` + ${{ needs.generate.outputs.changed_files }} + ``` + + The generated changes were restricted to locale Markdown, localized route redirects, and localized sidebar labels, then validated with the site checks and offline link validation. Please review translation quality and route mappings before merging. diff --git a/docs/ko-kr/README.md b/docs/ko-kr/README.md index f2bd7d80..24cbbe2a 100644 --- a/docs/ko-kr/README.md +++ b/docs/ko-kr/README.md @@ -40,4 +40,4 @@ GitHub Copilot CLI, GitHub Copilot 앱, GitHub Copilot 클라우드 에이전트 [first-steps-app]: first-steps/copilot-app/ [first-steps-cli]: first-steps/copilot-cli/ [first-steps-vscode]: first-steps/vscode/ -[real-world-development]: ../real-world-development/ +[real-world-development]: real-world-development/ diff --git a/docs/ko-kr/first-steps/copilot-app/12-deploy-pages.md b/docs/ko-kr/first-steps/copilot-app/12-deploy-pages.md new file mode 100644 index 00000000..5b078218 --- /dev/null +++ b/docs/ko-kr/first-steps/copilot-app/12-deploy-pages.md @@ -0,0 +1,48 @@ +--- +title: "레슨 12 - GitHub Pages로 사이트 배포하기" +description: "GitHub Copilot app을 사용해 Pages 워크플로를 구성하고, 풀 리퀘스트를 검토한 뒤, 게시된 Space Quiz를 확인합니다." +authors: + - jamesmontemagno +lastUpdated: 2026-10-12 +--- + +Space Quiz를 GitHub Pages에 배포하여 공개적으로 이용할 수 있도록 합니다. Copilot은 워크플로를 준비하고 배포 과정을 안내할 수 있지만, 변경 사항을 검토하고 사이트가 게시되었는지 확인하는 책임은 사용자에게 있습니다. + +이 레슨에서는 다음을 수행합니다. + +- Copilot에 GitHub Pages 배포 구성을 요청합니다. +- 병합하기 전에 워크플로와 풀 리퀘스트를 검토합니다. +- 배포 과정을 따라가고 게시된 사이트를 확인합니다. + +## 시나리오 + +Space Quiz는 이미 GitHub 리포지토리에 있지만, 누구나 간단히 이용할 수 있는 방법은 아직 없습니다. 서버나 런타임 종속성을 추가하지 않고 GitHub Pages로 단일 파일 사이트를 게시하면 공개 URL에서 이용할 수 있습니다. + +## Copilot에 사이트 배포 요청하기 + +`space-quiz`의 Copilot app 세션에서 다음 프롬프트를 보냅니다. + +```plaintext +이 리포지토리에서 GitHub Pages를 활성화해 주세요. 필요한 경우 웹사이트를 빌드하고 GitHub Pages에 배포하는 GitHub Actions 워크플로를 만들어 주세요. 아직 README가 없다면 앱 소개와 로컬 실행 방법을 설명하는 README를 추가해 주세요. 변경 사항으로 풀 리퀘스트를 만들고 필수 검사가 통과하면 병합해 주세요. 배포가 성공할 때까지 모니터링한 다음 실제 웹사이트의 최종 URL을 알려 주세요. Pages를 활성화하거나 병합할 권한이 없다면 제가 무엇을 승인하거나 해야 하는지 정확히 알려 주세요. 사이트가 실제로 게시되기 전까지 성공했다고 보고하지 마세요. +``` + +![Space Quiz 풀 리퀘스트 병합, Build website·Upload artifact·Deploy to Pages 단계가 성공한 GitHub Actions 배포 실행, yourname.github.io/space-quiz/에서 열린 Space Quiz를 보여 주는 3단계 다이어그램](../../../_images/first-steps-app-pages-deploy.svg) + +> [!WARNING] +> 이 프롬프트는 에이전트에 풀 리퀘스트 생성 및 병합과 리포지토리의 Pages 설정 변경을 요청합니다. 진행하기 전에 diff, 배포 권한, GitHub의 승인 요청을 검토합니다. + +## 워크플로 검토 및 배포 확인하기 + +1. 리포지토리에 README가 없는 경우에만 추가되었는지 확인합니다. +2. 워크플로의 빌드 및 배포 단계를 포함해 풀 리퀘스트 변경 사항을 검토합니다. +3. 필수 풀 리퀘스트 검사가 통과한 뒤에만 병합합니다. +4. GitHub Actions 배포 실행이 성공할 때까지 확인합니다. +5. 보고된 URL을 열어 Space Quiz가 로드되는지 확인합니다. + +에이전트가 Pages를 활성화하거나 풀 리퀘스트를 병합할 수 없다면 제공된 구체적인 지침을 따릅니다. 배포가 성공하고 실제 사이트가 로드될 때까지 작업이 완료된 것으로 처리하지 않습니다. + +## 요약 및 다음 단계 + +Space Quiz를 실제 사이트로 게시하고 에이전트의 보고에 의존하지 않고 배포를 확인했습니다. 다음으로 [레슨 13: 검토 및 다음 단계][next-lesson]를 진행합니다. + +[next-lesson]: ../13-review/ diff --git a/docs/ko-kr/real-world-development/README.md b/docs/ko-kr/real-world-development/README.md new file mode 100644 index 00000000..6822c1f1 --- /dev/null +++ b/docs/ko-kr/real-world-development/README.md @@ -0,0 +1,38 @@ +--- +title: "실제 개발" +slug: ko-kr/real-world-development +authors: + - geektrainer +lastUpdated: 2026-09-16 +--- + +현실적인 시나리오와 완성된 애플리케이션, 공유 백로그를 바탕으로 소프트웨어 개발 수명 주기 전반에서 GitHub Copilot을 살펴봅니다. 반복적으로 변경을 계획하고 코드를 작성하고 동작을 테스트하며 풀 리퀘스트를 검토하고 에이전트로 작업을 관리합니다. + +## 시나리오 + +개발자 테마의 보드게임 크라우드 펀딩을 제공하는 가상의 회사 Tailspin Toys에서 새 개발자로 일한다고 가정합니다. 팀의 백로그는 GitHub 이슈로 등록되어 있어 바로 작업을 시작할 수 있습니다. 백로그에는 필터링 및 페이지 매김과 같은 기능 작업과 접근성 및 코딩 표준과 같은 품질 개선 작업이 포함되어 있습니다. + +## 작업 환경 선택하기 + +GitHub Copilot은 다양한 작업 환경에서 사용할 수 있습니다. 원하는 개발 방식에 맞는 환경을 선택합니다. 각 워크숍은 자체 설정 절차로 시작하며 동일한 Tailspin Toys 시나리오를 사용합니다. + +### [GitHub Copilot CLI][cli] + +터미널에서 에이전트형 도우미를 사용합니다. Plan 및 Autopilot 모드, 지침, 스킬, 사용자 지정 에이전트, Playwright MCP, Agent Merge, 실용적인 슬래시 명령을 살펴봅니다. + +### [GitHub Copilot app][app] + +병렬 에이전트 세션을 실행하고 세션 모드를 전환하며 캔버스에서 협업하고 데스크톱 앱에서 GitHub 이슈와 풀 리퀘스트를 관리합니다. + +### [GitHub Copilot cloud agent][cloud] + +GitHub 이슈를 비동기 에이전트에 할당하고 작업을 안내하며 진행 상황을 모니터링하고 에이전트가 여는 풀 리퀘스트를 검토합니다. + +### [Visual Studio Code][vscode] + +Visual Studio Code와 GitHub Codespaces에서 GitHub Copilot을 사용합니다. 편집기를 벗어나지 않고 Copilot Chat 에이전트 모드, MCP 서버, 사용자 지정 에이전트를 활용합니다. + +[cli]: cli/ +[app]: app/ +[cloud]: cloud/ +[vscode]: vscode/ diff --git a/docs/ko-kr/real-world-development/cli/0-prerequisites.md b/docs/ko-kr/real-world-development/cli/0-prerequisites.md index a51eff7a..0b299336 100644 --- a/docs/ko-kr/real-world-development/cli/0-prerequisites.md +++ b/docs/ko-kr/real-world-development/cli/0-prerequisites.md @@ -1,71 +1,66 @@ --- -title: "연습 0: 사전 준비" +title: "레슨 0 - 사전 준비" +description: "Tailspin Toys의 복사본을 만들고 Copilot CLI 워크숍에 사용할 GitHub Codespace를 준비합니다." authors: - geektrainer -lastUpdated: 2026-06-30 +lastUpdated: 2026-09-18 --- -Copilot CLI 연습을 시작하기 전에 모든 것을 준비해야 합니다. Tailspin Toys 리포지토리(Repository)의 복사본을 만들고 [코드스페이스][codespaces]를 시작합니다. 다음 연습에서는 해당 코드스페이스의 통합 터미널을 사용해 Copilot CLI를 설치하고 실행합니다. +Copilot CLI 레슨을 시작하기 전에 필요한 사항을 준비합니다. Tailspin Toys 리포지토리의 복사본을 만들고 [Codespace][codespaces]를 시작합니다. 다음 레슨에서는 통합 터미널을 사용해 Copilot CLI를 설치하고 실행합니다. -## 실습용 리포지토리 설정 +이 레슨에서는 다음을 수행합니다. -앞으로 작성할 코드를 위한 리포지토리 복사본을 만들기 위해 [template][template-repository]에서 새 인스턴스(Instance)를 만듭니다. 새 인스턴스에는 실습에 필요한 파일이 모두 포함되며, 연습을 진행하는 동안 이 리포지토리를 사용합니다. +- 템플릿에서 Tailspin Toys 프로젝트의 복사본을 만듭니다. +- Codespace를 만들고 프로젝트가 준비되었는지 확인합니다. -1. 새 브라우저 창에서 이 실습의 GitHub 리포지토리로 이동합니다: `https://github.com/github-samples/tailspin-toys`. -2. 실습용 리포지토리 페이지에서 **Use this template** 버튼을 선택해 리포지토리 복사본을 만듭니다. 그런 다음 **Create a new repository**를 선택합니다. +## 실습용 리포지토리 설정하기 - ![Use this template 버튼](../../../_images/ex0-use-template.png) +Tailspin Toys 프로젝트의 복사본을 사용해 작업합니다. 지금 [템플릿 리포지토리][tailspin-template]에서 복사본을 만듭니다. 새 리포지토리에는 실습에 필요한 파일이 모두 포함되어 있습니다. -3. GitHub 또는 Microsoft가 진행하는 행사에서 이 워크숍을 수행하는 경우에는 멘토가 제공하는 안내를 따릅니다. 그렇지 않다면 GitHub Copilot에 액세스할 수 있는 조직에 새 리포지토리를 만들어도 됩니다. - - ![리포지토리 템플릿 설정 입력 화면](../../../_images/ex0-repository-settings.png) - -4. 이후 실습에서 참조할 수 있도록 생성한 리포지토리 경로(**organization-or-user-name/repository-name**)를 기록해 둡니다. +1. 새 브라우저 창에서 [Tailspin Toys 템플릿][tailspin-template]으로 이동합니다. +2. **Use this template**를 선택한 다음 **Create a new repository**를 선택하여 리포지토리 복사본을 만듭니다. +3. GitHub 또는 Microsoft가 진행하는 행사에서 워크숍을 수행하는 경우 멘토의 안내를 따릅니다. 그렇지 않다면 GitHub Copilot을 사용할 수 있는 조직에 새 리포지토리를 만듭니다. +4. 나중에 참조할 수 있도록 생성한 리포지토리 경로(`organization-or-user-name/repository-name`)를 기록해 둡니다. > [!NOTE] -> **백로그가 준비되었습니다** -> -> template에서 리포지토리를 만들면 GitHub issue 백로그가 자동으로 생성됩니다. 워크숍 내내 이 issue를 바탕으로 작업하므로 직접 등록할 내용은 없습니다. - -## 코드스페이스 만들기 +> 템플릿에서 리포지토리를 만들면 GitHub 이슈 백로그가 자동으로 생성됩니다. 워크숍 전체에서 해당 이슈를 사용하므로 직접 등록할 필요가 없습니다. -이제 코드스페이스를 사용해 실습을 진행합니다. - -[GitHub Codespaces][codespaces]는 브라우저에서 직접 코드를 작성하고, 실행하고, 디버그할 수 있는 클라우드 기반 개발 환경입니다. 여러 프로그래밍 언어, 확장, 도구를 지원하는 완전한 기능의 IDE를 제공합니다. - -1. 방금 만든 리포지토리로 이동합니다. -2. 초록색 **Code** 버튼을 선택합니다. +새 워크숍 템플릿 복사본을 사용합니다. 여기에는 리포지토리 지침, 애플리케이션 코드, 테스트, `quality-checks` 스킬, 실습에 사용할 백로그가 포함되어 있습니다. 이전 복사본을 사용한다면 필요한 파일이 있는지 진행자에게 확인합니다. - ![Code 버튼 선택 화면](../../../_images/ex0-code-button.png) +## Codespace 만들기 -3. **Codespaces** 탭을 선택한 다음 **+** 버튼을 선택해 새 Codespace를 만듭니다. +이제 Codespace에서 워크숍을 진행합니다. - ![새 codespace 만들기](../../../_images/ex0-create-codespace.png) +[GitHub Codespaces][codespaces]는 브라우저에서 코드를 작성하고 실행하고 디버그할 수 있는 클라우드 기반 개발 환경입니다. 여러 프로그래밍 언어, 확장, 도구를 지원하는 완전한 기능의 편집기를 제공합니다. -코드스페이스를 만드는 데는 몇 분 정도 걸리지만, 모든 서비스를 수동으로 설치하는 것보다 훨씬 빠릅니다. 기다리는 동안에는 GitHub Copilot의 다른 기능을 살펴볼 수 있으며, 다음 단계에서 그 부분을 이어서 알아봅니다. +1. 방금 만든 리포지토리로 이동합니다. +2. **Code**를 선택합니다. +3. **Codespaces** 탭을 선택한 다음 **Create codespace on main**을 선택합니다. +4. Codespace 설정이 완료될 때까지 기다립니다. 템플릿에서 프로젝트 종속성, Playwright Chromium, 로컬 데이터베이스를 설치합니다. +5. **Do you trust the authors of the files in this folder?**라는 메시지가 표시되면 **Trust Folder & Continue**를 선택합니다. +6. 리포지토리 루트에서 터미널을 열고 애플리케이션을 시작합니다. -> [!CAUTION] -> 이후 연습에서 다시 코드스페이스로 돌아옵니다. 지금은 브라우저 탭에서 그대로 열어 둡니다. + ```bash + npm run dev + ``` -> [!NOTE] -> 이 워크숍은 코드스페이스 또는 로컬 [dev container][dev-containers] 안에서 실행하도록 설계되었습니다. 두 환경 모두 원활한 진행에 필요한 사전 요구 사항이 모두 설치된 상태를 보장합니다. 로컬에서 실행하고 싶다면 복제한 리포지토리를 VS Code에서 열고, 메시지가 표시되면 **Reopen in Container**를 선택합니다. 그러면 코드스페이스에서 사용하는 것과 동일한 dev container를 VS Code가 빌드합니다. +7. Codespaces에서 포트 `4321`을 사용할 수 있다고 표시되면 **Open in Browser**를 선택하고 Tailspin Toys 사이트가 로드되는지 확인합니다. +8. 터미널로 돌아가 Ctrl+C를 눌러 개발 서버를 중지합니다. -[codespaces]: https://github.com/features/codespaces -[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers -## 요약 +## 요약 및 다음 단계 -축하합니다! 실습용 리포지토리 복사본을 만들었습니다. 또한 Copilot CLI 작업을 시작할 때 사용할 코드스페이스 생성도 시작했습니다. +준비가 끝났습니다. 이 레슨에서는 템플릿에서 Tailspin Toys 프로젝트의 복사본을 만들고 Codespace를 준비했습니다. -## 다음 단계 - -Copilot CLI를 설치하고 GitHub 계정으로 인증해 보겠습니다. [연습 1 - GitHub Copilot CLI 설치][next-lesson]로 계속 진행합니다. +다음으로 Codespace에 [GitHub Copilot CLI를 설치][next-lesson]하고 GitHub 계정으로 인증합니다. ## 리소스 - [GitHub Codespaces 개요][codespaces] - [템플릿에서 리포지토리 만들기][template-repository] -- [Codespaces 빠른 시작][codespaces-quickstart] +- [Codespaces 시작하기][codespaces-quickstart] +[tailspin-template]: https://github.com/github-samples/tailspin-toys [template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository [codespaces-quickstart]: https://docs.github.com/codespaces/getting-started/quickstart [next-lesson]: ../1-install-copilot-cli/ +[codespaces]: https://github.com/features/codespaces diff --git a/docs/ko-kr/real-world-development/cli/1-install-copilot-cli.md b/docs/ko-kr/real-world-development/cli/1-install-copilot-cli.md index 97f81415..6c91de81 100644 --- a/docs/ko-kr/real-world-development/cli/1-install-copilot-cli.md +++ b/docs/ko-kr/real-world-development/cli/1-install-copilot-cli.md @@ -1,58 +1,50 @@ --- -title: "연습 1 - GitHub Copilot CLI 설치" +title: "레슨 1 - GitHub Copilot CLI 설치하기" +description: "Codespace에 Copilot CLI를 설치하고 인증한 뒤 기본 사용법을 익히고 미리 등록된 필터링 이슈를 찾습니다." authors: - geektrainer -lastUpdated: 2026-06-30 +lastUpdated: 2026-09-18 --- -[GitHub Copilot CLI][about-copilot-cli]는 터미널에서 실행되는 강력한 에이전트형 코딩 도우미입니다. 코드베이스를 탐색하고, 코드를 생성하고, 명령을 실행하고, 외부 도구와 상호 작용하는 작업을 모두 명령줄에서 수행할 수 있습니다. 작업을 위임하고, 변경을 요청하고, 흐름을 유지할 수 있습니다. 예상할 수 있듯 첫 단계는 도구를 설치하는 일입니다. 다행히 이미 익숙한 도구로 설치할 수 있습니다. +[GitHub Copilot CLI][about-copilot-cli]는 터미널에서 실행되는 강력한 에이전트형 코딩 도우미입니다. 코드베이스를 살펴보고 코드를 생성하고 명령을 실행하며 외부 도구와 상호 작용하는 작업을 모두 명령줄에서 수행합니다. 작업을 위임하고 변경을 요청하면서 개발 흐름을 이어 갈 수 있습니다. 먼저 도구를 설치해야 합니다. 다행히 이미 익숙한 도구를 사용해 설치할 수 있습니다. -이 연습에서는 다음을 학습합니다. +이 레슨에서는 다음을 수행합니다. - npm을 사용해 GitHub Copilot CLI를 설치합니다. - GitHub 계정으로 인증합니다. -- 설치를 확인합니다. +- 워크숍 리포지토리를 신뢰하고 간단한 대화를 시도합니다. +- 기본 제공 GitHub MCP 서버를 사용해 필터링 이슈를 찾습니다. ## 시나리오 -팀에서는 늘어나는 백로그를 처리하기 위해 AI agent를 사용하기 시작했습니다. Copilot CLI는 많은 개발자가 주로 작업하는 터미널 안으로 그 기능을 가져옵니다. 이 연습을 마치면 설치와 인증이 완료되어, 워크숍의 나머지 단계를 진행할 준비가 됩니다. +팀은 늘어나는 백로그를 처리하기 위해 AI 에이전트를 사용하기 시작했습니다. Copilot CLI는 많은 개발자가 주로 사용하는 터미널에서 이러한 기능을 제공합니다. 이 레슨에서는 도구를 설치하고 인증하여 워크숍의 나머지 부분에 사용할 준비를 합니다. -## 코드스페이스에서 터미널 열기 +## Copilot CLI 설치하기 -Copilot CLI를 설치하기 전에 코드스페이스에서 터미널 창을 열어야 합니다. +Copilot CLI는 [npm][install-cli], WinGet, Homebrew로 설치할 수 있습니다. GitHub Codespaces에는 Node.js가 이미 설치되어 있으므로 npm을 사용합니다. -1. 아직 열지 않았다면 코드스페이스로 돌아갑니다. -2. Ctrl+`를 눌러 터미널 창을 엽니다. -3. VS Code 창 하단에 터미널 패널이 나타나는지 확인합니다. - -## Copilot CLI 설치 - -Copilot CLI는 [npm][install-npm], [WinGet][install-winget], [Homebrew][install-homebrew]로 설치할 수 있습니다. GitHub Codespaces에는 Node.js가 이미 설치되어 있으므로 npm을 사용해 Copilot CLI를 설치합니다. - -1. 터미널에서 Node.js가 설치되어 있고 버전 요구 사항을 충족하는지 확인합니다. +1. Codespace로 돌아가 터미널을 엽니다. +2. Node.js가 설치되어 있고 필요한 버전을 충족하는지 확인합니다. ```bash node --version ``` - 버전 22 이상(예: `v22.x.x`)이 표시되어야 합니다. + 버전 24 이상이 표시되어야 합니다. -2. npm을 사용해 코드스페이스에 Copilot CLI를 전역 설치합니다. +3. Copilot CLI를 전역으로 설치합니다. ```bash npm install -g @github/copilot ``` -3. 버전을 확인해 설치를 검증합니다. +4. 설치를 확인합니다. ```bash copilot --version ``` - 버전 번호(예: `v1.0.XX`)가 표시되어야 합니다. - -> [!TIP] -> 권한 오류가 발생하면 일부 시스템에서는 `sudo npm install -g @github/copilot`를 사용해야 할 수 있습니다. 하지만 GitHub Codespaces에서는 일반적으로 필요하지 않습니다. + 버전 번호가 표시되어야 합니다. ## GitHub로 인증하기 @@ -64,66 +56,85 @@ Copilot CLI를 처음 실행하면 GitHub 계정으로 인증하라는 메시지 copilot ``` -2. 현재 로그인되어 있지 않다면 인증 프롬프트가 표시됩니다. Copilot CLI는 device code를 보여 주고 URL로 이동하라고 안내합니다. -3. 화면의 안내를 따릅니다. - - 제공된 URL을 브라우저에서 엽니다. - - 메시지가 표시되면 device code를 입력합니다. - - Copilot CLI가 GitHub 계정에 액세스하도록 승인합니다. -4. 인증이 완료되면 질문과 명령을 받을 준비가 된 Copilot CLI 프롬프트가 표시됩니다. +2. 메시지가 표시되면 디바이스 코드 안내에 따라 인증하고 Copilot CLI를 승인합니다. +3. Copilot CLI에 다음 메시지가 표시됩니다. + + ```plaintext + Copilot can read files in this folder and, with your permission, edit them or run code and shell commands. It will remember your permissions for the rest of this session. + + Do you trust the files in this folder? + ``` + +4. 경로가 Tailspin Toys 리포지토리인지 확인한 다음 **Yes, and remember this folder for future sessions**를 선택합니다. > [!NOTE] -> 코드스페이스에서는 GitHub 세션을 통해 이미 인증되어 있을 수 있습니다. Copilot CLI가 인증 메시지 없이 시작되면 바로 진행하면 됩니다. +> Codespace에서는 GitHub 세션으로 이미 인증되어 있을 수 있습니다. Copilot CLI가 인증 메시지 없이 시작되면 계속 진행하면 됩니다. -## 디렉터리를 신뢰하고 모든 것이 작동하는지 확인하기 +## 기본 사용법 익히기 -이제 처음으로 Copilot CLI 프롬프트가 열렸으니, 이 워크숍 리포지토리를 신뢰하도록 설정하고 Copilot CLI가 제대로 설치되어 연결되었는지 확인해 보겠습니다. +일반 셸 프롬프트에서 명령을 입력하면 Codespace에서 바로 실행됩니다. Copilot CLI가 시작된 뒤 자연어 프롬프트는 에이전트에 전달되고, 슬래시 명령은 대화를 제어합니다. -1. Copilot CLI가 이 폴더의 파일을 신뢰하는지 확인해 달라고 요청하면 세 가지 옵션이 표시됩니다. - - **Yes, proceed**: 이번 세션에만 신뢰 - - **Yes, and remember this folder for future sessions**: 영구적으로 신뢰 - - **No, exit (Esc)**: 파일 액세스 허용 안 함 -2. 이 워크숍에서는 계속 이 리포지토리에서 작업하므로 **Yes, and remember this folder for future sessions**를 선택합니다. -3. 간단한 질문을 해 Copilot이 작동하는지 확인합니다. +1. `/model`을 입력하고 화살표 키로 **Auto**를 선택한 뒤 Enter를 누릅니다. 다시 Enter를 눌러 확인합니다. +2. `/help`를 입력해 설치된 버전에서 사용할 수 있는 명령을 확인한 다음 Esc를 눌러 도움말 화면을 닫습니다. +3. 다음 질문을 입력해 모든 항목이 작동하는지 확인합니다. - ``` - What files are in this project? + ```plaintext + 이 프로젝트에서 중요한 파일은 무엇인가요? ``` -4. Copilot이 리포지토리를 탐색하고 프로젝트 구조 요약을 제공해야 합니다. -5. `/help` 명령으로 사용 가능한 slash commands를 확인합니다. +4. 응답을 읽고 Copilot이 답변 전에 리포지토리를 살펴보는지 확인합니다. +5. `/mcp list`를 입력하고 기본 제공 GitHub MCP 서버를 사용할 수 있는지 확인합니다. +6. Copilot에 필터링 이슈를 찾아 달라고 요청합니다. - ``` - /help + ```plaintext + GitHub MCP를 사용해 이 리포지토리에서 "Allow users to filter games by category and publisher"라는 제목의 이슈를 찾아 주세요. URL과 간단한 요약을 알려 주세요. 아무것도 변경하지 마세요. ``` -6. 터미널에서 다음 명령을 입력해 Copilot CLI를 종료합니다. 이후 연습에서 다시 Copilot CLI로 돌아옵니다. +7. URL을 열어 이슈를 읽습니다. 간단한 변경을 완료한 뒤 이 이슈를 사용합니다. +> [!TIP] +> 일반적인 Copilot CLI 세션은 터미널에서 현재 체크아웃한 브랜치에서 작업하며, 자동으로 워크트리를 만들지 않습니다. 각 변경 작업 전에 기능 브랜치를 만듭니다. + +## 워크숍 단축 옵션 사용하기 + +Copilot CLI는 기본적으로 허용된 권한 밖의 도구를 사용하기 전에 확인을 요청합니다. 이 워크숍에서는 Codespace 안에서 승인 요청을 줄여 실습에 집중할 수 있도록 사용자가 승인한 단축 옵션 `--yolo`를 사용합니다. + +> [!CAUTION] +> `--yolo`는 전체 자동 권한(`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`)을 활성화합니다. Codespace나 VM 같은 격리된 환경에서만 사용하고, 일상적인 개발을 위한 기본 별칭으로는 절대 설정하지 않습니다. 자세한 내용은 [도구 사용 허용 및 거부][allow-all-warning]를 참조합니다. + +이 워크숍에서 `--enable-all-github-mcp-tools`는 이후 레슨에서 이슈와 풀 리퀘스트를 처리하는 데 필요한 읽기/쓰기 GitHub MCP 도구를 활성화합니다. Codespace는 로컬 컴퓨터에 대한 액세스를 제한하지만 인증된 GitHub 리소스에는 실제로 접근합니다. 게시하거나 병합하기 전에 변경 사항을 검토합니다. + +1. `/exit`로 Copilot CLI를 종료합니다. +2. 리포지토리 루트에서 다시 시작합니다. + + ```bash + copilot --yolo --enable-all-github-mcp-tools ``` - exit - ``` + +3. 프로젝트에 관한 간단한 질문을 다시 입력해 대화가 작동하는지 확인한 다음 `/exit`로 종료합니다. + +Copilot은 대화를 자동으로 저장합니다. 이후 지침을 바꾸거나 에이전트를 추가한 뒤에는 `copilot --resume`을 사용해 동일한 기능 대화와 브랜치로 돌아옵니다. ## 요약 및 다음 단계 -축하합니다! GitHub Copilot CLI를 성공적으로 설치하고 인증했습니다. 다음을 학습했습니다. +이 레슨에서는 다음을 수행했습니다. -- npm을 사용해 Copilot CLI를 설치합니다. -- GitHub 계정으로 인증합니다. -- Copilot CLI가 작업할 디렉터리를 신뢰하도록 설정합니다. -- 설치가 올바르게 작동하는지 확인합니다. +- npm을 사용해 GitHub Copilot CLI를 설치했습니다. +- GitHub 계정으로 인증했습니다. +- 워크숍 리포지토리를 신뢰하고 간단한 대화를 시도했습니다. +- 기본 제공 GitHub MCP 서버를 사용해 필터링 이슈를 찾았습니다. -이제 Copilot CLI가 설치되었으니, Copilot에 프로젝트 컨텍스트를 제공해 보겠습니다. [연습 2 - CLI로 커스텀 지침 사용하기][next-lesson]로 계속 진행합니다. +다음으로 [첫 번째 변경 작업][next-lesson]을 시작해 Copilot CLI로 게임 카드에 별점을 표시합니다. ## 리소스 -- [GitHub Copilot CLI 설치][install-copilot-cli] -- [Copilot CLI 소개][about-copilot-cli] -- [Copilot CLI 사용하기][using-copilot-cli] +- [GitHub Copilot CLI 설치][install-cli] +- [GitHub Copilot CLI 정보][about-copilot-cli] +- [Copilot CLI 명령 참조][cli-reference] [previous-lesson]: ../0-prerequisites/ -[next-lesson]: ../2-custom-instructions/ -[install-copilot-cli]: https://docs.github.com/copilot/how-tos/set-up/install-copilot-cli -[install-npm]: https://docs.github.com/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli#installing-with-npm-all-platforms -[install-winget]: https://docs.github.com/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli#installing-with-winget-windows -[install-homebrew]: https://docs.github.com/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli#installing-with-homebrew-macos-and-linux +[next-lesson]: ../2-add-star-rating/ +[install-cli]: https://docs.github.com/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli [about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli -[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli +[cli-reference]: https://docs.github.com/copilot/reference/copilot-cli-reference/cli-command-reference +[allow-all-warning]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli#allowing-and-denying-tool-use diff --git a/docs/ko-kr/real-world-development/cli/10-review.md b/docs/ko-kr/real-world-development/cli/10-review.md new file mode 100644 index 00000000..2448b837 --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/10-review.md @@ -0,0 +1,74 @@ +--- +title: "레슨 10 - 마무리 및 다음 단계" +description: "Copilot CLI 작업 흐름, 풀 리퀘스트 두 개, 재사용 가능한 사용자 지정 기능, 추가 리소스를 돌아봅니다." +authors: + - geektrainer +lastUpdated: 2026-09-29 +--- + +하나로 이어지는 Tailspin Toys 작업 흐름에서 GitHub Copilot CLI를 사용했습니다. 이 레슨에서는 다음을 수행했습니다. + +- Codespace를 준비하고 Copilot CLI를 설치해 프로젝트를 살펴본 뒤 미리 등록된 필터링 이슈를 찾았습니다. +- 별점을 추가하고 포워딩된 브라우저에서 결과를 확인한 뒤 첫 풀 리퀘스트(PR)를 직접 병합했습니다. +- 필터링 이슈에서 시작해 Plan 모드로 접근 방식을 정하고 Autopilot 모드로 구현한 뒤 Interactive 모드에서 검토했습니다. +- 사용자 지정 지침으로 에이전트를 안내하고 `quality-checks` 스킬을 사용자 지정해 단위 테스트, 린트, 타입 검사를 실행했습니다. +- Playwright Model Context Protocol(MCP) 서버를 추가하고 실제 브라우저에서 필터링 기능을 살펴봤습니다. +- 품질 보증(QA) 사용자 지정 에이전트를 만들고 선택하여 요구 사항, 테스트 범위, 스킬 결과, 브라우저 검증 근거를 확인했습니다. +- 필터링 변경 사항 전체를 검토하고 Agent Merge를 승인해 필터링 PR을 병합했습니다. +- 컨텍스트, 모델, 공유, cloud agent에 선택적으로 위임하기 위한 슬래시 명령을 살펴봤습니다. + +## 전달한 결과 + +워크숍에서는 업데이트된 `main`에서 시작하는 브랜치 두 개를 사용해 PR 두 개를 완료합니다. + +1. **별점:** 기존 `starRating`과 별점이 없는 상태를 게임 카드에 표시합니다. +2. **필터링 및 품질 작업 흐름:** 필터링을 구현하고 지침을 업데이트해 기능에 적용하고 `quality-checks` 보고서를 사용자 지정하고 QA 프로필을 만들고 관련 테스트를 추가합니다. + +필터링을 계획하는 단계부터 PR을 여는 단계까지 동일한 대화와 브랜치를 사용했습니다. 워크숍을 간소화하기 위해 해당 작업을 하나의 PR에 포함했습니다. + +## 다양한 방식으로 검증하기 + +자동 테스트, 브라우저에서 직접 확인, MCP를 사용한 Copilot의 브라우저 탐색 등 여러 방법으로 코드를 검증했습니다. `quality-checks` 스킬은 단위 테스트, 린트, 타입 검사를 실행하고 새 형식에 따라 결과를 보고했습니다. QA는 PR 전에 요구 사항과 테스트 범위를 검토하고 해당 결과를 함께 정리했습니다. + +테스트는 실제로 부족한 범위를 보완해야 합니다. QA 실행에서 테스트를 추가하지 않아도 되는 경우가 있을 수 있습니다. 병합을 승인하기 전에 코드와 근거를 검토하고 변경 사항이 있으면 관련 근거를 다시 확인합니다. + +## 모범 사례 + +Copilot에 제공하는 컨텍스트와 도구가 결과에 영향을 줍니다. 이 워크숍에서는 지침을 업데이트하고 스킬을 사용자 지정하고 QA 프로필을 만들고 MCP 서버를 구성했습니다. 대화 전반에서 이러한 사용자 지정 기능을 재사용하고 팀의 요구 사항에 맞게 조정합니다. 지침은 표준을 정하고, 스킬은 반복 작업을 안내하고, 사용자 지정 에이전트는 전문 역할을 정의하고, MCP 서버는 외부 도구를 연결합니다. 에이전트의 요약뿐 아니라 실제 변경 사항과 도구 결과를 검토합니다. + +작업에 맞게 **모드와 모델**을 선택합니다. **Plan**은 구현 전에 접근 방식을 검토할 때, **Interactive**는 범위가 명확한 변경에서 과정을 함께 진행할 때, **Autopilot**은 범위가 명확한 작업을 맡길 때 사용합니다. 일반적인 편집에는 더 빠른 모델을, 복잡한 작업에는 더 강력한 모델을 선택합니다. + +인프라만큼 컨텍스트도 중요합니다. 무엇을, 왜, 어떻게 만들지 명확하게 설명하면 결과가 달라집니다. + +## 더 살펴보기 + +핵심 작업 흐름을 마쳤습니다. Copilot CLI의 추가 기능도 살펴볼 수 있습니다. + +- `/review`를 사용해 코드 검토 에이전트에 변경 사항을 분석하도록 요청합니다. +- `/rubber-duck`을 사용해 문제를 논의하고 다른 관점을 얻습니다. +- `/fleet`으로 독립적인 하위 작업을 병렬로 조율합니다. +- `/worktree`로 별도 작업을 격리합니다. +- `/delegate`로 Copilot cloud agent에 작업을 보냅니다. + +## 다음 단계 + +어떤 도구든 계속 사용해야 더 잘 활용할 수 있습니다. 프로덕션 코드나 취미 프로젝트, 또는 오래전부터 만들고 싶었던 작은 앱에서 도구를 사용해 봅니다. 팀과 배운 내용을 공유하고 서로의 경험에서 배웁니다. 문서도 계속 살펴봅니다. + +터미널에서 Tailspin Toys를 확장하려면 선택 사항인 [Foundry Backer Concierge 시리즈][foundry]를 진행합니다. 다른 환경을 비교하려면 [VS Code 워크숍][vscode], [GitHub Copilot app 워크숍][app], [Copilot cloud agent 워크숍][cloud]을 살펴봅니다. + +## 리소스 + +- [GitHub Copilot CLI 정보][about-cli] +- [Copilot CLI 명령 참조][cli-reference] +- [Copilot CLI 사용자 지정][customize-cli] +- [Copilot CLI로 풀 리퀘스트 관리][manage-prs] + +[previous-lesson]: ../9-cli-power-tools/ +[foundry]: ../8-foundry-agent/ +[vscode]: ../../vscode/ +[app]: ../../app/ +[cloud]: ../../cloud/ +[about-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli +[cli-reference]: https://docs.github.com/copilot/reference/copilot-cli-reference/cli-command-reference +[customize-cli]: https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot +[manage-prs]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests diff --git a/docs/ko-kr/real-world-development/cli/2-add-star-rating.md b/docs/ko-kr/real-world-development/cli/2-add-star-rating.md new file mode 100644 index 00000000..13aab12c --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/2-add-star-rating.md @@ -0,0 +1,123 @@ +--- +title: "레슨 2 - 빠른 성과로 별점 추가하기" +description: "Copilot CLI로 게임 카드에 작은 변경을 적용하고, 포워딩된 브라우저에서 검토한 뒤, 첫 풀 리퀘스트로 병합합니다." +authors: + - geektrainer +lastUpdated: 2026-09-18 +--- + +Copilot CLI를 설치하고 대화를 시도했으니 이제 프로젝트를 처음으로 변경합니다. 범위는 작게 유지합니다. 게임 데이터에는 별점이 있지만 홈페이지의 게임 카드에는 표시되지 않습니다. 에이전트에 별점을 표시하도록 요청하고 변경 내용을 검토한 뒤 첫 풀 리퀘스트로 병합합니다. + +이 레슨에서는 다음을 수행합니다. + +- 기능 브랜치에서 Copilot과 새 대화를 시작합니다. +- 에이전트에 프로젝트를 작게 변경하도록 요청합니다. +- `/diff`로 변경 사항을 검토합니다. +- 앱을 실행하고 포워딩된 브라우저에서 변경 내용을 확인합니다. +- 첫 풀 리퀘스트를 만들고 병합합니다. + +## 시나리오 + +Tailspin Toys의 각 게임에는 별점이 있을 수 있으며, 별점은 이미 게임 상세 페이지에 표시됩니다. 하지만 홈페이지의 게임 카드에는 제목, 카테고리, 퍼블리셔, 설명만 표시됩니다. 워밍업으로 에이전트에 각 카드의 별점을 표시하도록 요청합니다. 첫 세션에 적합한 작고 독립적인 변경입니다. + +## 대화의 구성 + +**대화(conversation)**는 Copilot CLI로 작업을 수행하는 곳입니다. Copilot app과 달리 일반적인 CLI 대화는 터미널에서 현재 체크아웃한 리포지토리와 Git 브랜치에서 진행되며 전용 워크트리를 만들지 않습니다. 저장된 대화를 이어서 사용할 수 있으며, 파일과 브랜치는 일반적인 Git 상태로 디스크에 남습니다. + +대화에는 세 가지 요소가 표시됩니다. 프롬프트와 에이전트 응답, 파일을 살펴보고 편집하는 동안의 도구 활동, `/diff`로 확인할 수 있는 변경 사항입니다. + +## 대화를 시작하고 변경 요청하기 + +새 대화를 시작하고 기능을 구현합니다. + +1. Codespace로 돌아갑니다. +2. 터미널이 열려 있지 않다면 Mac에서는 Control+\`를, Windows/Linux에서는 Ctrl+\`를 누릅니다. +3. 아직 Copilot CLI를 시작하지 않았다면 다음 명령을 실행합니다. + + ```bash + copilot --yolo + ``` + +4. `/new` 슬래시 명령을 입력하고 Enter를 눌러 새 세션을 시작합니다. +5. 다음 프롬프트로 변경을 요청합니다. + + ```plaintext + 목록 페이지의 게임 카드에 각 게임의 starRating을 5점 만점으로 표시해 주세요. 별점이 null이면 "No rating yet"를 표시합니다. 카드 레이아웃은 그대로 유지하고 테스트를 추가한 뒤 관련 검사를 실행해 주세요. + ``` + +Copilot은 프로젝트를 살펴보고 게임 세부 정보를 표시하는 파일을 찾아 필요한 코드를 작성합니다. Copilot CLI로 새 기능을 추가했습니다. + +## diff 검토하기 + +작은 변경이라도 AI가 생성한 모든 변경 사항은 병합하기 전에 검토해야 합니다. Copilot CLI에서 변경 내용을 살펴봅니다. + +1. `/diff`를 입력하고 변경된 파일을 모두 살펴봅니다. +2. 별점이 있는 경우 게임 카드에 숫자 값이 표시되고 `starRating`이 `null`인 경우 `No rating yet`가 표시되는지 확인합니다. +3. 두 가지 상태를 테스트하는지 확인합니다. +4. Copilot이 실행한 검사 결과를 검토하고 실패한 항목이 있으면 수정하도록 요청합니다. +5. 검토가 끝나면 Esc를 눌러 diff 화면을 닫습니다. + +> [!NOTE] +> 모든 생성형 AI 도구와 마찬가지로 Copilot은 결정론적이 아니라 확률적으로 작동하므로 정확한 코드는 다를 수 있습니다. 한 가지 구현을 그대로 기대하기보다 동작을 검토합니다. + +## 변경 내용 확인하기 + +코드를 읽고 작동한다고 가정하지 말고, Codespaces에서 포워딩된 브라우저로 업데이트된 UI를 확인하도록 Copilot에 요청합니다. + +1. Copilot에 앱을 시작하도록 요청합니다. + + ```plaintext + 브라우저에서 별점 변경을 확인할 수 있도록 앱을 시작해 주세요. URL을 알려 주고 서버는 계속 실행 상태로 두세요. + ``` + +2. Codespaces에서 포트 `4321`을 사용할 수 있다고 표시되면 **Open in Browser**를 선택합니다. +3. 게임 카드에 별점이 5점 만점으로 표시되는지 확인합니다. +4. Copilot으로 돌아가 시작한 서버를 중지하도록 요청합니다. + + ```plaintext + 시작한 개발 서버를 중지해 주세요. + ``` + +## 첫 풀 리퀘스트 열기 및 병합하기 + +기능을 만들었으니 새 코드를 프로젝트에 병합할 풀 리퀘스트(PR)를 만듭니다. + +1. 기본 에이전트에 변경 사항을 커밋하도록 요청합니다. + + ```plaintext + 검토한 별점 변경 사항을 적절한 커밋 메시지로 커밋해 주세요. + ``` + +2. `/pr create`를 입력합니다. Copilot CLI는 PR을 만들 때 기존 커밋을 푸시하고 PR URL을 표시합니다. +3. Command(Mac) 또는 Ctrl(Windows/Linux)을 누른 상태에서 Copilot CLI에 표시된 URL을 선택해 PR을 엽니다. +4. 변경된 파일과 검사를 검토합니다. +5. 준비가 되면 **Merge pull request**를 선택한 뒤 병합을 확인합니다. +6. Codespace로 돌아가 `/exit`로 Copilot CLI를 종료합니다. +7. 로컬 `main`을 업데이트합니다. + + ```bash + git checkout main + git pull + ``` + +## 요약 및 다음 단계 + +GitHub Copilot CLI를 사용해 첫 변경 사항을 전달했습니다. 이 레슨에서는 다음을 수행했습니다. + +- 기능 브랜치에서 Copilot 대화를 시작했습니다. +- 에이전트에 게임 카드를 작게 변경하도록 요청했습니다. +- `/diff`로 변경 사항을 검토했습니다. +- 앱을 실행하고 포워딩된 브라우저에서 별점을 확인했습니다. +- 첫 풀 리퀘스트를 열고 병합했습니다. + +다음으로 [필터링 이슈에서 시작해 Plan 및 Autopilot 모드][next-lesson]를 사용하여 더 큰 기능을 만듭니다. + +## 리소스 + +- [GitHub Copilot CLI 정보][about-copilot-cli] +- [Copilot CLI 명령 참조][cli-reference] + +[previous-lesson]: ../1-install-copilot-cli/ +[next-lesson]: ../3-agent-modes/ +[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli +[cli-reference]: https://docs.github.com/copilot/reference/copilot-cli-reference/cli-command-reference diff --git a/docs/ko-kr/real-world-development/cli/2-custom-instructions.md b/docs/ko-kr/real-world-development/cli/2-custom-instructions.md deleted file mode 100644 index 6603b934..00000000 --- a/docs/ko-kr/real-world-development/cli/2-custom-instructions.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: "연습 2 - 커스텀 지침(Copilot CLI)" -authors: - - geektrainer -lastUpdated: 2026-06-30 ---- - -[← 이전 연습: Copilot CLI 설치][previous-lesson] · [다음 연습: CLI로 코드 생성하기 →][next-lesson] - -생성형 AI로 작업할 때는 컨텍스트가 핵심입니다. 작업을 특정 방식으로 수행해야 하거나 Copilot이 알아야 할 배경 정보가 있다면, 그 컨텍스트를 사용할 수 있게 해야 합니다. Copilot을 돕는 여러 도구가 있으며, 이 워크숍 전반에서 이를 살펴봅니다. 먼저 [instruction files][instruction-files]부터 시작합니다. Instruction files는 일반적으로 코드 자체를 어떻게 구성해야 하는지에 초점을 맞춥니다. 이를 통해 Copilot은 원하는 코드가 *무엇인지*뿐 아니라 *어떻게* 구조화되어야 하는지도 이해할 수 있습니다. - -이 연습에서는 다음을 수행합니다. - -- 리포지토리 커스텀 지침과 경로 범위 지침 파일을 통해 프로젝트별 컨텍스트, 코딩 가이드라인, 문서화 표준이 Copilot에 전달되는 방식을 살펴봅니다. -- 현재 지침이 적용된 상태에서 필터링을 위한 첫 번째 데이터 조각인 publishers helper를 생성합니다. -- `.github/copilot-instructions.md`에 새로운 리포지토리 전체 표준을 추가합니다. -- 후속 프롬프트를 실행하고 재생성된 코드가 새 표준을 따르는 모습을 확인합니다. -- 다음 연습에서 이어서 사용할 수 있도록 지침 업데이트와 helper를 커밋합니다. - -> [!CAUTION] -> 생성된 코드는 설정한 표준 일부와 다를 수 있습니다. Copilot은 비결정적입니다. 목표는 출력이 문자 단위로 완전히 일치하는 것이 아니라, 지침을 업데이트한 뒤 동작 경향이 어떻게 바뀌는지 확인하는 것입니다. - -## 지침 파일 - -### 시나리오 - -훌륭한 개발 조직답게 Tailspin Toys에는 개발 관행에 대한 가이드라인과 요구 사항이 있습니다. 여기에는 다음이 포함됩니다. - -- 데이터 계층에는 항상 단위 테스트가 필요합니다. -- UI는 dark mode여야 하며 현대적인 느낌을 제공해야 합니다. -- 코드 문서는 TSDoc doc comments 형태로 추가해야 합니다. -- 각 파일의 맨 앞에는 파일의 역할을 설명하는 주석 블록을 추가해야 합니다. - -Instruction files를 사용하면 Copilot이 이러한 관행에 맞춰 작업을 수행하는 데 필요한 정보를 갖추도록 할 수 있습니다. - -### 커스텀 지침 - -커스텀 지침을 사용하면 Copilot에 컨텍스트와 선호 사항을 제공하여 코딩 스타일과 요구 사항을 더 잘 이해하도록 도울 수 있습니다. 이 기능은 더 관련성 높은 제안과 코드 스니펫을 얻도록 Copilot의 방향을 조정하는 강력한 방법입니다. 선호하는 코딩 규칙, 라이브러리, 코드에 포함하고 싶은 주석 유형까지 지정할 수 있습니다. 전체 리포지토리에 대한 지침을 만들 수도 있고, 작업 수준 컨텍스트를 위해 특정 파일 형식에 대한 지침을 만들 수도 있습니다. - -지침 파일에는 두 가지 유형이 있습니다. - -- `.github/copilot-instructions.md`는 리포지토리에 대한 **모든** 요청에서 Copilot으로 전송되는 단일 지침 파일입니다. 이 파일에는 프로젝트 수준 정보, 즉 Copilot에 보내는 대부분의 채팅 또는 CLI 요청에 공통으로 관련된 컨텍스트를 담아야 합니다. 사용 중인 기술 스택, 빌드 중인 내용의 개요, 모범 사례, 기타 전역 가이드라인이 여기에 포함될 수 있습니다. -- `.github/instructions/*.instructions.md` 파일은 특정 작업이나 파일 형식을 위해 만들 수 있습니다. TypeScript나 Astro 같은 특정 언어에 대한 지침을 제공하거나, UI 컴포넌트 또는 새로운 단위 테스트 세트 생성 같은 작업에 대한 지침을 제공할 수 있습니다. - -> [!NOTE] -> IDE에서 작업할 때 지침 파일은 Copilot Chat의 코드 생성에만 사용되며, code completions나 next-edit suggestions에는 사용되지 않습니다. -> -> Copilot Chat, Copilot CLI, Copilot cloud agent는 코드를 생성할 때 리포지토리 수준 지침과 `applyTo` front matter가 있는 `*.instructions.md` 파일을 모두 사용합니다. -> -> 또한 Copilot은 AGENTS.md와 CLAUDE.md를 포함한 [다른 표준의 지침 파일도 지원합니다][custom-instructions-support]. - -### 지침 파일 관리 모범 사례 - -지침 파일을 만드는 방법 전체를 이 워크숍에서 모두 다루지는 않습니다. 하지만 샘플 프로젝트에 포함된 예시는 대표적인 접근 방식을 보여 줍니다. 높은 수준에서 보면 다음과 같습니다. - -- `copilot-instructions.md`의 지침은 빌드 중인 내용의 설명, 프로젝트 구조, 전역 코딩 표준처럼 프로젝트 수준 가이드에 집중합니다. -- `*.instructions.md` 파일은 파일 형식(단위 테스트, Astro 컴포넌트, 데이터 계층)이나 특정 작업에 대한 구체적인 지침을 제공하는 데 사용합니다. -- 자연어를 사용합니다. 가이드는 명확하게 유지합니다. 코드가 어떻게 보여야 하는지와 어떻게 보이면 안 되는지에 대한 예시를 제공합니다. - -AI를 사용하는 방법이 하나로 정해져 있지 않듯, 지침 파일을 만드는 방법도 하나로 정해져 있지 않습니다. 실험을 통해 프로젝트에 가장 잘 맞는 방식을 찾게 됩니다. - -> [!TIP] -> GitHub Copilot을 사용하는 모든 프로젝트에는 탄탄한 instruction files 모음이 있어야 합니다. 이 프로젝트의 instruction files를 살펴보면 [UI 업데이트][ui-instructions]와 [Astro][astro-instructions]를 포함해 다양한 작업 유형에 대한 파일이 있다는 점을 확인할 수 있습니다. -> -> Copilot은 instruction files 생성도 도와줄 수 있습니다. 각 표면마다 노출 방식은 다르지만(예: VS Code의 **Configure Chat → Generate Agent Instructions**, Copilot CLI의 `/init`) 관련이 있는 경우 현재 사용 중인 표면의 연습에서 이를 안내합니다. -> -> 템플릿이나 시작점을 찾고 있나요? Instruction files, custom agents, 기타 리소스를 모아 둔 리포지토리인 [awesome-copilot][awesome-copilot]을 살펴봅니다. - -[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md -[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md -[awesome-copilot]: https://github.com/github/awesome-copilot -[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support -## 이 프로젝트의 커스텀 지침 파일 살펴보기 - -잠시 시간을 내어 이 리포지토리에 포함된 지침 파일을 읽어 봅니다. 핵심 `copilot-instructions.md` 하나와 다양한 작업을 위한 `*.instructions.md` 파일 모음이 있습니다. 편집기 또는 GitHub 웹 UI에서 열어 봅니다. - -1. `.github/copilot-instructions.md`를 엽니다. -2. 파일을 살펴보면서 프로젝트의 간단한 설명과 **Agent notes**, **Code standards**, **Scripts**, **Repository Structure** 같은 섹션을 확인합니다. **Code standards** 아래에 중첩된 **GitHub Actions Workflows** 가이드가 있다는 점에 주목합니다. 이 내용은 Copilot과 상호 작용할 때 전반적으로 적용됩니다. -3. `.github/instructions` 폴더를 열어 둘러봅니다. Astro 파일, Drizzle 데이터 계층, 테스트 등 다양한 지침이 있는지 확인합니다. -4. `.github/instructions/unit-tests.instructions.md`를 엽니다. 상단의 `applyTo` 필드를 확인합니다. 이 필드는 지침이 적용될 파일을 결정하는 glob(리포지토리 루트 기준)을 설정합니다. 여기서는 모든 TypeScript test 파일(예: `**/*.test.ts`와 일치하는 파일)에 적용됩니다. -5. 이 프로젝트에서 단위 테스트를 만들 때 적용되는 구체적인 지침을 확인합니다. -6. 마지막으로 `.github/instructions/drizzle.instructions.md`를 열고 맨 아래로 스크롤합니다. 다른 지침 파일(`unit-tests.instructions.md` 등)과 프로젝트의 기존 파일에 대한 링크가 있는지 확인합니다. 이렇게 하면 더 큰 지침 세트를 더 작고 재사용 가능한 파일로 나눌 수 있고, 코드 생성 시 Copilot이 따를 예시를 가리킬 수 있습니다. (해당 경로는 리포지토리 루트가 아니라 지침 파일 기준 상대 경로입니다.) - -> [!NOTE] -> `copilot-instructions.md`의 **Code formatting requirements** 섹션에는 프로젝트 코딩 표준이 문서화되어 있지만, 아직 코드 내부 문서화는 요구하지 않습니다. 다음 단계에서 TSDoc doc comments와 파일 주석 헤더에 대한 규칙을 추가합니다. - -## 브랜치 만들기 - -코드를 변경할 예정이므로 작업용 브랜치를 만듭니다. - -1. 코드스페이스 터미널에서 새 브랜치를 만들고 전환합니다. - - ```bash - git checkout -b update-custom-instructions - ``` - -2. Copilot CLI가 설치 및 인증되었는지 확인합니다. - - ```bash - copilot --version - ``` - - 명령을 찾을 수 없거나 아직 로그인하지 않았다면 [연습 1 - GitHub Copilot CLI 설치](../1-install-copilot-cli/)로 돌아갑니다. - -## 지침을 업데이트하기 *전*에 Copilot CLI 사용하기 - -커스텀 지침의 영향을 확인하려면 먼저 현재 지침이 적용된 상태에서 코드를 생성합니다. 이후 파일을 업데이트하고 후속 프롬프트를 실행합니다. - -> [!TIP] -> **Copilot CLI 세션 시작하기** -> -> 아래 연습을 시작하기 전에 코드스페이스로 돌아가 터미널을 엽니다(이미 열려 있지 않다면 Ctrl+`). 그런 다음 `--yolo`와 `--enable-all-github-mcp-tools`를 사용해 Copilot CLI를 시작합니다. -> -> ```bash -> copilot --yolo --enable-all-github-mcp-tools -> ``` -> -> 이 프로젝트의 가장 최근 세션을 새로 시작하지 않고 이어서 사용하려면 `copilot --yolo --enable-all-github-mcp-tools --continue`를 실행합니다. 이전 연습에서 Copilot CLI가 이미 실행 중이라면 `/clear`를 보내 새 대화를 시작합니다. -> -> `--enable-all-github-mcp-tools`는 현재 세션에서 읽기/쓰기 GitHub MCP 도구를 활성화하므로, 워크숍 흐름 중 Copilot이 백로그를 읽고 pull request를 열 수 있습니다. - -> [!CAUTION] -> `--yolo`는 전체 자동 권한(`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`)을 활성화합니다. Codespace나 VM 같은 격리된 환경에서만 사용하고, 일상적인 개발을 위한 기본 별칭으로는 절대 설정하지 않습니다. 자세한 내용은 [Allowing and denying tool use][allow-all-warning]를 참고합니다. - -[allow-all-warning]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools -1. Copilot CLI 세션이 **repository root**에서 실행 중인지 확인합니다. 그래야 `.github/copilot-instructions.md`를 자동으로 불러옵니다. -2. Copilot CLI 프롬프트에서 필터링 UI가 사용할 publishers helper를 생성해 달라고 요청합니다. - - ```plaintext - Create a new data-access helper at src/lib/publishers.ts to return a list of all publishers. It should return the name and id for all publishers. Do not run the tests yet. - ``` - -3. Copilot CLI는 프로젝트를 탐색하고, 계획을 제안하고, 이 `--yolo` 세션에서 파일을 작성합니다. 터미널 출력의 변경 내용을 확인한 뒤 편집기에서 검토합니다. -4. 편집기에서 생성된 `src/lib/publishers.ts`를 엽니다. -5. helper가 첫 번째 인수로 `db` client를 받고, publisher의 typed array를 반환하는 typed function이라는 점을 확인합니다. 이는 `src/lib/*.ts`에 적용되는 `.github/instructions/drizzle.instructions.md`의 데이터 계층 규칙에서 비롯됩니다. -6. 생성된 코드에 TSDoc doc comments와 파일 수준 주석 헤더가 **없다**는 점을 확인합니다. - -> [!CAUTION] -> Copilot은 확률적으로 동작하므로, 지시하지 않았더라도 doc comments를 추가할 가능성이 있습니다. 그런 경우에도 괜찮습니다. 지침 업데이트 후 *일관성*이 향상되는 점이 핵심입니다. - -## 새로운 리포지토리 표준 추가하기 - -앞서 설명했듯이 `.github/copilot-instructions.md`는 Copilot에 프로젝트 수준 정보를 제공하도록 설계되었습니다. 이제 리포지토리 코딩 표준을 문서화해 코드 제안을 개선해 보겠습니다. - -1. `.github/copilot-instructions.md`를 다시 엽니다. -2. **Code formatting requirements** 섹션을 찾습니다. 대략 27번째 줄 근처에 있을 것입니다. 이 섹션이 프로젝트의 코딩 표준을 문서화하고 있지만, 아직 코드 내부 문서화 규칙이 없기 때문에 생성된 helper에 doc comments가 없었다는 점을 확인합니다. -3. 기존 표준 바로 아래에 다음 markdown 줄을 추가해 Copilot이 파일 주석 헤더와 TSDoc doc comments를 넣도록 지시합니다. - - ```markdown - - Every exported function should have a TSDoc comment describing its purpose, parameters, and return value. - - Before imports or any code, add a comment block to the file that explains its purpose. - ``` - -4. `copilot-instructions.md`를 저장합니다. - -> [!TIP] -> 이전 연습에서 본 것처럼 지침 파일은 전역 가이드를 위한 리포지토리 수준(`.github/copilot-instructions.md`)으로 만들 수도 있고, 특정 언어, 파일 형식, 작업을 위한 `*.instructions.md` 파일로 만들 수도 있습니다. 방금 추가한 doc comment 규칙처럼 프로젝트 전반에 적용되는 표준은 리포지토리 수준 파일에 두는 것이 적절합니다. - -## 프롬프트를 다시 실행하고 변화를 관찰하기 - -이제 지침에 doc comment 규칙이 추가되었으므로 방금 생성한 publishers 파일을 Copilot CLI로 업데이트해 보겠습니다. 동일한 표준 지시가 다시 작성된 코드에도 적용됩니다. - -1. Copilot CLI 세션에서 `/clear`를 보내 새 대화를 시작합니다. -2. 다음 프롬프트를 보냅니다. - - ```plaintext - Update src/lib/publishers.ts to follow the latest documentation conventions in .github/copilot-instructions.md. - ``` - -3. 편집이 완료되면 `src/lib/publishers.ts`를 다시 엽니다. -4. 이제 파일 맨 앞에 다음과 비슷한 주석 블록이 추가된 점을 확인합니다. - - ```typescript - /** - * Publisher data-access helpers for the Tailspin Toys Crowd Funding platform. - * Provides functions to retrieve publisher information from the database. - */ - ``` - -5. 생성된 함수에 이제 다음과 비슷한 TSDoc doc comment가 포함된 점을 확인합니다. - - ```typescript - /** - * Returns a list of all publishers with their id and name. - * - * @param db - The Drizzle database client. - * @returns A promise that resolves to an array of publisher objects. - */ - ``` - -6. 업데이트된 파일은 그대로 유지합니다. 다음 연습에서 이 파일을 기반으로 첫 번째 데이터 조각을 확장합니다. - -## 첫 번째 필터링 조각 커밋 및 푸시하기 - -1. 터미널에서 변경된 파일을 확인합니다. - - ```bash - git status - ``` - -2. 지침 업데이트와 helper를 stage합니다. - - ```bash - git add .github/copilot-instructions.md src/lib/publishers.ts - ``` - -3. 변경 사항을 커밋합니다. - - ```bash - git commit -m "Add doc comment standards and publishers helper foundation" - ``` - -4. 브랜치를 푸시합니다. - - ```bash - git push -u origin update-custom-instructions - ``` - -## 요약 및 다음 단계 - -이 프로젝트의 지침 파일을 통해 Copilot이 어떻게 컨텍스트를 받아들이는지 살펴본 다음, Copilot CLI를 사용해 다음을 수행했습니다. - -- 기존 지침을 바탕으로 필터링용 publishers data-access helper 기반을 생성했습니다. -- `.github/copilot-instructions.md`에 새로운 리포지토리 전체 표준을 추가했습니다. -- 후속 프롬프트를 실행하고 재생성된 코드가 새 표준을 따르는 모습을 확인했습니다. -- 지침 업데이트와 helper 기반을 모두 커밋하고 푸시했습니다. - -다음으로는 [코드 생성 연습][next-lesson]에서 백로그 작업을 구현하면서 이 지침을 적용합니다. - -## 리소스 - -- [GitHub Copilot 사용자 지정을 위한 instruction files][instruction-files] -- [커스텀 지침 작성 모범 사례][instructions-best-practices] -- [Copilot용 더 나은 커스텀 지침을 작성하는 5가지 팁][copilot-instructions-five-tips] -- [Instruction files와 기타 리소스를 모아 둔 Awesome Copilot][awesome-copilot] - -[previous-lesson]: ../1-install-copilot-cli/ -[next-lesson]: ../3-generating-code/ -[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses -[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository -[copilot-instructions-five-tips]: https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/ diff --git a/docs/ko-kr/real-world-development/cli/3-agent-modes.md b/docs/ko-kr/real-world-development/cli/3-agent-modes.md new file mode 100644 index 00000000..40664fa8 --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/3-agent-modes.md @@ -0,0 +1,159 @@ +--- +title: "레슨 3 - 에이전트 모드: Plan 및 Autopilot" +description: "Plan으로 접근 방식을 정하고 Autopilot으로 이슈의 필터링 기능을 구현한 뒤 Interactive 모드에서 결과를 검토합니다." +authors: + - geektrainer +lastUpdated: 2026-09-18 +--- + +프로젝트에 작은 기능을 추가했습니다. 더 큰 변경에는 더 체계적인 프로세스가 필요합니다. GitHub Copilot CLI는 조직의 기존 작업 흐름에 맞춰 동작하므로 올바른 방식으로 필요한 기능을 구현할 수 있습니다. 이 레슨은 이슈를 바탕으로 기능을 만들고 코드가 유효한지 확인하고 동작을 테스트한 뒤 성공적으로 병합하는 일반적인 에이전트 기반 개발 과정을 다룹니다. + +> [!NOTE] +> 기능 작업을 이어 가는 동안 동일한 대화와 브랜치를 사용합니다. 일반적으로 파일 유형에 따라 브랜치나 PR을 나누지만, 핵심 개념에 집중할 수 있도록 이 워크숍에서는 일부 단계를 간소화합니다. + +이 레슨에서는 다음을 수행합니다. + +- GitHub 이슈에서 Copilot 대화를 시작합니다. +- Plan 모드에서 요구 사항을 정합니다. +- Autopilot 모드로 새 기능을 구현합니다. +- 코드를 검토합니다. +- 포워딩된 브라우저에서 기능을 직접 확인합니다. + +이후 레슨에서는 리포지토리 지침을 업데이트하고 기존 `quality-checks` 스킬을 사용자 지정하고 MCP 검증을 추가하고 QA 에이전트를 만든 뒤 기능 PR을 엽니다. + +## 시나리오 + +Tailspin Toys의 카탈로그가 커지면서 방문자가 카테고리와 퍼블리셔를 기준으로 게임을 좁힐 수 있어야 합니다. 백로그 이슈에 기능 요구 사항이 있지만 카테고리를 조합하는 방식 등은 코딩 전에 합의해야 합니다. Plan 모드에서 세부 사항을 결정한 뒤 Autopilot으로 범위가 명확한 구현을 승인합니다. + +## 배경 + +AI 코딩 에이전트를 개발 작업 흐름에 추가해도 기본 원칙은 바뀌지 않습니다. 오히려 더 중요해집니다. 대부분의 개발자는 다음과 비슷한 과정을 따릅니다. + +1. 수행할 작업을 설명하는 등록된 이슈에서 시작합니다. +2. 구현할 작업을 계획합니다. +3. 코드를 작성하고 검토합니다. +4. 테스트를 실행해 코드를 검증합니다. +5. 새 기능을 직접 확인합니다. +6. 풀 리퀘스트(PR)를 만듭니다. +7. 코드 검토를 마치고 지속적 통합 검사가 성공하면 코드를 병합합니다. + +> [!NOTE] +> 구체적인 절차는 팀과 조직에 따라 다를 수 있지만 대체로 위 과정과 비슷합니다. + +이러한 표준 접근 방식을 따르면 AI가 생성한 코드가 요구 사항을 충족하고 사람이 작성한 코드와 동일한 검토 과정을 거치게 됩니다. + +## 대화 모드 + +**대화 모드**는 에이전트의 자율성 수준을 제어합니다. Shift+Tab을 눌러 모드를 전환합니다. + +- **Interactive**: 사용자와 에이전트가 함께 작업합니다. 에이전트는 변경을 제안하고 사용자의 입력을 기다립니다. +- **Plan**: 에이전트가 먼저 계획을 작성하며 프로젝트 파일은 편집할 수 없습니다. +- **Autopilot**: 에이전트가 코드를 작성하고 테스트를 실행하며 작업이 완료될 때까지 자율적으로 반복합니다. + +Plan 모드에서 시작해 계획을 검토한 뒤 Autopilot으로 구현합니다. + +## 이슈에서 시작하기 + +필터링 작업을 시작하기 전에 Codespace로 돌아가 리포지토리와 터미널이 준비되었는지 확인합니다. + +1. Codespace로 돌아갑니다. 중지된 상태라면 다시 시작합니다. +2. 별점 PR이 병합되었는지 확인합니다. +3. 터미널이 열려 있지 않으면 Control+\`(Mac) 또는 Ctrl+\`(Windows/Linux)을 누릅니다. +4. `main`을 업데이트하고 필터링 작업을 위한 브랜치를 만듭니다. + + ```bash + git checkout main + git pull --ff-only + git checkout -b game-filters-cli + ``` + +5. Copilot CLI를 시작합니다. + + ```bash + copilot --yolo + ``` + +6. Tab을 두 번 눌러 **Issues** 탭을 엽니다. +7. A를 눌러 모든 이슈를 표시합니다. +8. 화살표 키로 **Allow users to filter games by category and publisher** 이슈를 선택합니다. +9. C를 눌러 이슈를 프롬프트에 추가하고 **Session** 탭으로 돌아갑니다. + +이제 프롬프트가 `#7` 또는 비슷한 번호로 시작합니다. `#`을 사용하면 GitHub의 이슈나 풀 리퀘스트(PR)를 컨텍스트에 포함할 수 있습니다. + +## 필터링 기능 계획하기 + +계획을 세우면 Copilot에 넘기기 전에 기능 구현 또는 작업 수행 방식을 정할 수 있습니다. 복잡한 작업은 계획을 세우는 것이 좋습니다. Plan 모드로 전환한 뒤 Copilot에 계획을 요청합니다. + +1. Shift+Tab을 눌러 Plan 모드로 전환합니다. 프롬프트 아래의 모드 표시기가 **Plan**인지 확인합니다. +2. 이전 단계에서 추가한 이슈 참조 뒤에 다음 프롬프트를 입력합니다. + + ```plaintext + 이 기능을 구현하기 위한 계획을 작성해 주세요. + ``` + +Copilot은 프로젝트를 살펴본 다음 가장 적절한 접근 방식을 결정해 계획을 작성합니다. + +3. 필터링 기능의 동작 방식에 관한 질문을 받으면 원하는 방식으로 답합니다. 정답은 하나가 아닙니다. +4. 계획이 완성되면 Control+E(Mac) 또는 Ctrl+E(Windows/Linux)를 눌러 계획을 펼칩니다. +5. 계획을 위아래로 이동하며 검토합니다. +6. 결정한 내용과 맞지 않는 부분이 있으면 Copilot에 계획을 수정하도록 요청합니다. + +## Autopilot 승인하기 + +계획을 작성하고 검토했으니 이제 구현합니다. Autopilot을 사용해 Copilot이 작업을 수행하도록 합니다. + +Autopilot 모드에서는 Copilot이 작업을 완료했다고 판단할 때까지 반복합니다. + +1. **Accept plan and build on autopilot (recommended)** 또는 설치된 버전에서 같은 의미로 표시되는 옵션을 선택합니다. +2. 프롬프트 아래의 모드 표시기가 **Autopilot**인지 확인합니다. +3. Copilot이 계획에 따라 코드를 작성하고 테스트를 실행하며 작업을 반복하는 과정을 살펴봅니다. + +> [!NOTE] +> 계획을 승인하면 구현이 바로 시작될 수 있으므로 먼저 계획을 검토합니다. Copilot이 종속성 누락이나 포트 충돌을 보고하면 검사가 완료된 것으로 처리하기 전에 설정 문제를 해결합니다. + +## 구현 검토 및 확인하기 + +코드를 병합하기 전에 다른 코드와 마찬가지로 검토해야 합니다. 코드를 검토하고 사이트를 실행해 모든 것이 제대로 표시되는지 확인합니다. + +1. Shift+Tab을 눌러 Interactive 모드로 전환합니다. 모드 표시기에 **Plan** 또는 **Autopilot**이 표시되지 않는지 확인합니다. +2. `/diff`를 입력하고 필터링 구현과 테스트를 살펴봅니다. +3. 결과를 이슈와 계획 중에 결정한 내용과 비교합니다. +4. 코드를 검토한 뒤 Esc를 눌러 diff 보기를 닫습니다. +5. 프로젝트 검사 결과를 검토하고 실패한 항목이 있으면 Copilot에 해결하도록 요청합니다. + +## 새 기능 살펴보기 + +코드는 괜찮아 보입니다. 이제 앱을 시작하고 Codespaces 포워딩 포트로 사이트를 열어 동작을 확인합니다. + +1. Copilot에 앱을 시작하도록 요청합니다. + + ```plaintext + 브라우저에서 필터링 기능을 확인할 수 있도록 앱을 시작해 주세요. URL을 알려 주고 서버는 계속 실행 상태로 두세요. + ``` + +2. Codespaces에서 포트 `4321`을 사용할 수 있다고 표시되면 **Open in Browser**를 선택합니다. +3. 계획에서 합의한 카테고리 필터, 퍼블리셔 필터, 조합을 시험합니다. +4. 초기화와 결과 없음 상태가 이슈 및 결정 내용에 맞게 동작하는지 확인합니다. +5. Codespace로 돌아가 Copilot에 시작한 개발 서버를 중지하도록 요청합니다. + +## 요약 및 다음 단계 + +다양한 대화 모드를 사용하여 기능을 만들고 검토했습니다. 이 레슨에서는 다음을 수행했습니다. + +- GitHub 이슈에서 Copilot 대화를 시작했습니다. +- Plan 모드에서 요구 사항을 정했습니다. +- Autopilot 모드로 기능을 구현했습니다. +- 코드를 검토했습니다. +- 포워딩된 브라우저에서 기능을 직접 확인했습니다. + +다음으로 [사용자 지정 지침][next-lesson]을 사용해 코드를 문서화된 방식으로 작성하도록 안내합니다. + +## 리소스 + +- [GitHub Copilot CLI의 Autopilot][autopilot] +- [Copilot CLI 명령 참조][cli-reference] + +[autopilot]: https://docs.github.com/copilot/concepts/agents/copilot-cli/autopilot +[cli-reference]: https://docs.github.com/copilot/reference/copilot-cli-reference/cli-command-reference +[previous-lesson]: ../2-add-star-rating/ +[next-lesson]: ../4-custom-instructions/ diff --git a/docs/ko-kr/real-world-development/cli/3-generating-code.md b/docs/ko-kr/real-world-development/cli/3-generating-code.md deleted file mode 100644 index 4dfa4c62..00000000 --- a/docs/ko-kr/real-world-development/cli/3-generating-code.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "연습 3 - GitHub Copilot CLI로 프로젝트 기능 추가하기" -authors: - - geektrainer -lastUpdated: 2026-06-30 ---- - -예상할 수 있듯이 GitHub Copilot CLI로 수행하는 핵심 작업은 프로젝트에 기능, 동작, 코드를 추가하는 일입니다. 이제 백로그의 issue 중 하나를 가져와 Copilot이 구현을 도와주도록 해보겠습니다. - -## 시나리오 - -이제 프로젝트의 필터링 작업을 마무리할 차례입니다. 백로그에는 이미 필터링 issue가 있고, 이전 연습에서 foundation helper도 만들었습니다. Copilot이 issue 세부 정보를 가져오고, 기존 작업을 고려한 뒤, 남은 기능을 구현하도록 해보겠습니다. - -이 연습에서는 다음을 수행합니다. - -- Plan mode를 사용해 필터링 기능 구현 계획을 생성합니다. -- Copilot으로 웹 사이트에 필터링을 추가하는 데 필요한 코드를 생성합니다. - -이 연습이 끝나면 프로젝트에 새로운 기능이 추가됩니다. - -## Plan mode 활용하기 - -AI의 가장 뛰어난 활용 방식 중 하나는 계획 수립입니다. 무엇을 만들고 싶은지 대략적인 개념은 있지만 아이디어를 정리할 대상이 필요할 때가 많습니다. AI 도구는 후속 질문을 하고, 빠진 구성 요소나 잠재적인 함정을 함께 검토하면서 생각을 구체화하도록 도와줍니다. Copilot CLI는 이 과정을 지원하기 위해 plan mode를 제공합니다. 또한 계획 수립에 들인 시간은 Copilot이 요구 사항에 더 잘 맞는 코드를 생성하는 데 도움이 됩니다. - -Copilot CLI의 plan mode를 사용해 새 기능 생성 과정을 시작합니다. - -> [!TIP] -> **Copilot CLI 세션 시작하기** -> -> 아래 연습을 시작하기 전에 코드스페이스로 돌아가 터미널을 엽니다(이미 열려 있지 않다면 Ctrl+`). 그런 다음 `--yolo`와 `--enable-all-github-mcp-tools`를 사용해 Copilot CLI를 시작합니다. -> -> ```bash -> copilot --yolo --enable-all-github-mcp-tools -> ``` -> -> 이 프로젝트의 가장 최근 세션을 새로 시작하지 않고 이어서 사용하려면 `copilot --yolo --enable-all-github-mcp-tools --continue`를 실행합니다. 이전 연습에서 Copilot CLI가 이미 실행 중이라면 `/clear`를 보내 새 대화를 시작합니다. -> -> `--enable-all-github-mcp-tools`는 현재 세션에서 읽기/쓰기 GitHub MCP 도구를 활성화하므로, 워크숍 흐름 중 Copilot이 백로그를 읽고 pull request를 열 수 있습니다. - -> [!CAUTION] -> `--yolo`는 전체 자동 권한(`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`)을 활성화합니다. Codespace나 VM 같은 격리된 환경에서만 사용하고, 일상적인 개발을 위한 기본 별칭으로는 절대 설정하지 않습니다. 자세한 내용은 [Allowing and denying tool use][allow-all-warning]를 참고합니다. - -[allow-all-warning]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools -1. Copilot CLI에 다음 프롬프트를 입력해 필터링 issue를 바탕으로 계획을 생성합니다. - - ``` - /plan Retrieve the issue on the repository related to adding filtering. We already added a publishers helper in src/lib/publishers.ts, so treat that as existing work and plan the remaining updates (games filtering logic, UI, and tests). - ``` - -2. Copilot이 계획을 세우는 동안 후속 질문을 할 수 있습니다. 질문이 나오면 원하는 구현 방식에 맞게 답변합니다. -3. 계획이 생성되면 설계 청사진을 검토합니다. 데이터 계층과 UI 전반의 남은 변경 사항, 그리고 테스트 생성이 권장되는 것을 확인할 수 있습니다. -4. Copilot CLI는 계획에 대한 추가 피드백을 제공할 수 있는 기능도 제공합니다. 안내된 영역으로 커서를 이동한 뒤 제안을 입력하면 Copilot이 이를 반영한 새 버전의 계획을 제시합니다. -5. 계획이 만족스럽다면 Copilot이 제공하는 옵션을 선택해 새 기능 구현을 시작합니다. - -> [!NOTE] -> Copilot은 확률적으로 동작하므로, 정확한 텍스트와 제공되는 옵션은 달라질 수 있습니다. 하지만 구현을 시작하는 옵션이 표시되며 대체로 다음과 비슷한 문구를 보게 됩니다. -> -> `Yes, and switch to autopilot mode`. -> -> Copilot은 위 예시처럼 [autopilot mode](https://docs.github.com/copilot/concepts/agents/copilot-cli/autopilot)를 활성화하는 옵션을 제안할 수 있습니다. Autopilot mode를 사용하면 Copilot CLI가 각 단계마다 입력을 기다리지 않고 작업을 진행합니다. 처음 지시를 주면 Copilot CLI가 작업이 완료되었다고 판단할 때까지 각 단계를 자율적으로 처리합니다. 현재는 격리된 환경에서 작업하므로 autopilot을 실행하고 모든 도구를 허용해도 괜찮습니다. - -6. Copilot이 파일 생성을 시작합니다. - -> [!NOTE] -> 이 작업은 몇 분 정도 걸릴 수 있습니다. Copilot이 파일을 수정하고 생성하며, 테스트를 업데이트 및 생성하고, 모든 테스트를 실행해 성공 여부를 확인하는 모습을 보게 됩니다. 지금까지 살펴본 내용을 되돌아보거나 잠시 음료를 즐기기 좋은 시간입니다. - -## 코드 검토하기 - -AI가 생성한 코드는 운영 환경에 병합하기 전에 반드시 검토해야 합니다. 이제 Copilot이 기능 구현 과정에서 생성하거나 수정한 파일을 살펴보겠습니다. - -1. Copilot CLI에서 다음 명령을 사용해 "diff" 또는 코드 변경 사항을 표시합니다. - - ``` - /diff - ``` - -2. 변경된 파일을 확인합니다. 화살표 키로 좌우 이동하면서 서로 다른 파일을 볼 수 있습니다. 새 필터 컨트롤과 클라이언트 측 필터링이 들어간 게임 목록 페이지, `src/lib/games.ts`, `games.test.ts` 같은 테스트 파일이 업데이트된 것을 확인할 수 있습니다. Copilot이 전체 구현에 맞춰 기존 helper를 조정했다면 `publishers.ts`가 수정된 경우도 있을 수 있습니다. - -## 요약 및 다음 단계 - -이제 Copilot CLI의 도움으로 웹 사이트에 필터링 기능을 추가했습니다. 구체적으로 다음을 수행했습니다. - -- Plan mode를 사용해 필터링 기능 구현 계획을 생성했습니다. -- Copilot을 사용해 웹 사이트에 필터링을 추가하는 데 필요한 코드를 생성했습니다. - -물론 다음 단계는 실제로 동작하는지 확인하는 것입니다. Pull request를 열기 전에 [Playwright MCP server로 기능 테스트하기][next-lesson]로 이동해 검증해 보겠습니다. - -## 리소스 - -- [Copilot CLI 사용하기][using-copilot-cli] -- [Copilot CLI 소개][about-copilot-cli] -- [Copilot CLI의 컨텍스트 관리][context-management] - -[previous-lesson]: ../2-custom-instructions/ -[next-lesson]: ../4-mcp/ -[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli -[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli -[context-management]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#context-management diff --git a/docs/ko-kr/real-world-development/cli/4-custom-instructions.md b/docs/ko-kr/real-world-development/cli/4-custom-instructions.md new file mode 100644 index 00000000..184e3e6e --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/4-custom-instructions.md @@ -0,0 +1,106 @@ +--- +title: "레슨 4 - 사용자 지정 지침으로 Copilot 안내하기" +description: "리포지토리 지침을 살펴보고 문서 표준을 추가한 뒤 필터링 코드에 적용합니다." +authors: + - geektrainer +lastUpdated: 2026-09-18 +--- + +생성형 AI를 사용할 때 컨텍스트가 중요합니다. 특정 방식으로 작업해야 한다면 Copilot이 해당 지침을 사용할 수 있어야 합니다. [지침 파일][instruction-files]은 원하는 코드뿐 아니라 코드 구성 방식도 설명합니다. 필터링 기능을 만든 뒤 Copilot이 사용한 지침을 살펴보고 문서 표준을 추가해 코드에 적용합니다. + +이 레슨에서는 다음을 수행합니다. + +- 리포지토리 지침 및 경로 범위 지침 파일이 에이전트에 전달되는 방식을 살펴봅니다. +- 코딩 표준을 지키도록 지침 파일을 업데이트합니다. +- 지침 파일이 코드에 미치는 영향을 확인합니다. + +## 시나리오 + +Tailspin Toys에는 개발 관행을 위한 지침과 요구 사항이 있습니다. + +- 주석은 코드 내용을 반복하지 않고 의도나 명확하지 않은 결정을 설명해야 합니다. +- `db/`와 `src/lib/`에서 내보내는 함수에는 목적, 매개 변수, 반환 값이 포함된 TSDoc/JSDoc을 작성해야 합니다. `db`를 인수로 전달할 수 있다면 문서에 이를 포함해야 합니다. +- 재사용 가능한 Astro 컴포넌트에는 `Props` 계약을 설명해야 하며, 관련 코드가 바뀌면 주석도 최신 상태로 유지해야 합니다. +- 기존 서식 및 린트 지침을 유지해야 합니다. + +지침 파일을 사용해 Copilot이 이러한 관행에 맞게 작업하도록 안내합니다. + +## 지침 파일 + +사용자 지정 지침은 Copilot에 컨텍스트와 선호 사항을 제공하여 코딩 스타일과 요구 사항을 더 잘 이해하도록 합니다. 코딩 규칙, 라이브러리, 포함하려는 주석 유형을 지정할 수 있습니다. 리포지토리 전체 또는 특정 파일 유형에 적용되는 작업별 지침 파일을 만들 수 있습니다. + +지침 파일에는 두 가지 유형이 있습니다. + +- `.github/copilot-instructions.md`는 리포지토리의 **모든** 요청에 Copilot이 사용하는 단일 지침 파일입니다. 대부분의 요청에 관련된 프로젝트 수준 정보를 작성합니다. +- `.github/instructions/*.instructions.md` 파일은 특정 언어, 파일 유형, 작업에 대한 지침을 제공합니다. + +> [!NOTE] +> 지침 파일 형식과 지원 범위는 환경에 따라 다를 수 있습니다. 특정 형식에 의존하기 전에 [사용자 지정 지침 지원 참조][custom-instructions-support]를 확인합니다. + +## 이 프로젝트의 사용자 지정 지침 파일 살펴보기 + +시작을 돕기 위해 스타터 프로젝트에 지침 파일 모음이 포함되어 있습니다. 변경 전에 기존 파일을 살펴보고 지침의 영향을 확인합니다. + +1. Codespace로 돌아갑니다. +2. Codespaces 편집기에서 터미널이 아니라 `.github/copilot-instructions.md`를 엽니다. +3. 프로젝트에 대한 간단한 설명과 코딩 지침을 살펴봅니다. 이 지침은 리포지토리에서 Copilot과 상호 작용할 때마다 적용됩니다. +4. `.github/instructions` 폴더를 열어 파일을 살펴봅니다. Astro 파일, Drizzle 데이터 계층, 테스트 등에 대한 지침이 있습니다. +5. `.github/instructions/unit-tests.instructions.md`를 엽니다. 맨 위의 `applyTo` 필드는 지침을 적용할 파일을 결정하는 glob을 지정합니다. +6. `.github/instructions/drizzle.instructions.md`를 열고 다른 지침 파일 및 기존 프로젝트 파일을 가리키는 링크를 살펴봅니다. 이를 활용하면 큰 지침 모음을 작고 재사용 가능한 파일로 나누고 Copilot이 참고할 예제를 지정할 수 있습니다. + +## 팀 지침에 맞게 지침 파일 업데이트하기 + +이미 포함된 파일은 좋은 출발점이지만 보완할 부분이 있습니다. 새 TypeScript 코드에 TSDoc 주석을 추가하도록 핵심 `copilot-instructions.md` 파일을 수정합니다. + +1. `.github/copilot-instructions.md`에서 35행 근처에 있는 **Code formatting guidance** 섹션을 찾습니다. +2. 마지막 항목으로 다음을 추가합니다. + + ```markdown + - 새 TypeScript 코드에는 문서화를 위한 TSDoc 주석을 작성합니다. + ``` + +파일이 자동으로 저장됩니다. + +## 업데이트한 지침 적용하기 + +Copilot CLI는 대화를 시작할 때 리포지토리 지침을 불러옵니다. 지침을 저장한 뒤 필터링 대화를 종료하고 다시 시작하면 기능 컨텍스트를 유지하면서 새 지침을 불러올 수 있습니다. + +1. 필터링 대화가 아직 열려 있으면 Copilot CLI에서 `/exit`를 입력해 종료합니다. Copilot CLI는 대화를 자동으로 저장합니다. +2. `game-filters-cli` 브랜치의 리포지토리 루트에서 저장된 대화를 다시 시작합니다. + + ```bash + copilot --resume + ``` + + 세션 선택 화면이 표시되면 필터링 대화를 선택하고 `game-filters-cli` 브랜치가 체크아웃되어 있는지 확인합니다. +3. 다음 프롬프트로 Copilot에 업데이트된 지침을 적용하도록 요청합니다. + + ```plaintext + 방금 지침과 코드 작성 지침을 업데이트했습니다. 생성한 코드에 새 지침을 적용해 주시겠어요? + ``` + +4. `/diff`를 입력하고 변경된 TypeScript 파일을 확인합니다. 새로 생성된 TSDoc 주석이 코드 동작을 정확히 설명하는지 살펴봅니다. + +## 요약 및 다음 단계 + +Copilot이 지침 파일을 적용하는 방식을 살펴보고 새 프로젝트 표준을 추가했습니다. 이 레슨에서는 다음을 수행했습니다. + +- 리포지토리 지침 및 경로 범위 지침 파일이 에이전트에 전달되는 방식을 살펴봤습니다. +- 코딩 표준을 지키도록 지침 파일을 업데이트했습니다. +- 지침 파일이 코드에 미치는 영향을 확인했습니다. + +다음으로 [재사용 가능한 quality-checks 스킬을 사용자 지정하고 실행][next-lesson]하여 린트와 테스트를 일관되게 실행합니다. + +## 리소스 + +- [GitHub Copilot 사용자 지정 지침 파일][instruction-files] +- [사용자 지정 지침 지원][custom-instructions-support] +- [사용자 지정 지침 작성 모범 사례][instructions-best-practices] +- [Awesome Copilot — 지침 파일 및 기타 리소스 모음][awesome-copilot] + +[instruction-files]: https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions +[instructions-best-practices]: https://docs.github.com/copilot/concepts/prompting/response-customization#writing-effective-custom-instructions +[awesome-copilot]: https://awesome-copilot.github.com/ +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +[previous-lesson]: ../3-agent-modes/ +[next-lesson]: ../5-agent-skills/ diff --git a/docs/ko-kr/real-world-development/cli/4-mcp.md b/docs/ko-kr/real-world-development/cli/4-mcp.md deleted file mode 100644 index e696b6b8..00000000 --- a/docs/ko-kr/real-world-development/cli/4-mcp.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: "연습 4 - Playwright MCP server로 기능 테스트하기" -authors: - - geektrainer -lastUpdated: 2026-06-30 ---- - -방금 Copilot CLI로 필터링 기능을 생성했습니다. Pull request를 열기 전에 브라우저에서 실제로 동작하는지 확인해야 합니다. 직접 앱을 눌러 보며 확인하는 대신 **Playwright MCP server**를 연결해 Copilot이 실제 브라우저를 제어하면서 기능을 테스트하도록 해보겠습니다. - -이 연습에서는 다음을 수행합니다. - -- Model Context Protocol(MCP)이 무엇인지 이해하고, MCP server가 Copilot CLI를 어떻게 확장하는지 살펴봅니다. -- Playwright MCP server를 Copilot CLI에 추가합니다. -- 브라우저에서 필터링 기능을 수동 테스트하도록 Copilot에 요청합니다. - -## Model Context Protocol(MCP)이란 무엇인가요? - -[Model Context Protocol(MCP)](https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/)은 AI agent가 외부 도구 및 서비스와 통신할 수 있는 방법을 제공합니다. MCP를 사용하면 AI agent는 외부 도구와 서비스를 실시간으로 사용할 수 있습니다. 이를 통해 최신 정보에 접근하고(resources 사용), 작업을 대신 수행하도록(tools 사용) 할 수 있습니다. - -이러한 도구와 리소스는 MCP server를 통해 접근합니다. MCP server는 AI agent와 외부 도구 및 서비스 사이의 브리지 역할을 합니다. MCP server는 AI agent와 외부 도구(기존 API 또는 NPM package 같은 로컬 도구 등) 간의 통신을 관리합니다. 각 MCP server는 AI agent가 접근할 수 있는 서로 다른 도구와 리소스 집합을 나타냅니다. - -널리 사용되는 MCP server 예시는 다음과 같습니다. - -- **[GitHub MCP Server](https://github.com/github/github-mcp-server)**: GitHub 리포지토리를 관리하기 위한 API 집합에 접근할 수 있게 해줍니다. 새 리포지토리 생성, 기존 리포지토리 업데이트, issue 및 pull request 관리 같은 작업을 AI agent가 수행할 수 있습니다. -- **[Playwright MCP Server](https://github.com/microsoft/playwright-mcp)**: Playwright를 사용한 브라우저 자동화 기능을 제공합니다. 웹 페이지 탐색, 양식 입력, 버튼 선택 같은 작업을 AI agent가 수행할 수 있습니다. - -서로 다른 도구와 리소스에 접근할 수 있게 해주는 다른 MCP server도 많이 있습니다. GitHub는 검색성과 생태계 기여를 높이기 위해 [MCP registry](https://github.com/mcp)를 제공합니다. - -> [!CAUTION] -> 보안 측면에서 MCP server는 프로젝트의 다른 dependency와 동일하게 취급해야 합니다. MCP server를 사용하기 전에 소스 코드를 신중히 검토하고, 게시자를 확인하며, 보안 영향을 고려합니다. 신뢰할 수 있는 MCP server만 사용하고, 민감한 리소스나 작업에 대한 액세스를 부여할 때는 특히 주의합니다. - -> [!NOTE] -> [GitHub MCP server][github-mcp-server]는 Copilot CLI에 **기본 내장**되어 있습니다. 별도 설정 없이 바로 사용할 수 있으며, 워크숍 전반에서 Copilot이 리포지토리를 읽고 쓰고 있었던 것도 이 서버 덕분입니다. 이 연습에서는 Copilot에 브라우저를 제공하기 위해 두 번째 서버인 Playwright를 추가합니다. - -## Playwright MCP server 추가하기 - -서버를 추가하는 가장 빠른 방법은 대화형 `/mcp add` 명령입니다. Copilot이 제어할 수 있는 브라우저를 제공하는 [Playwright MCP server][playwright-mcp-server]를 등록합니다. - -> [!TIP] -> **Copilot CLI 세션 시작하기** -> -> 아래 연습을 시작하기 전에 코드스페이스로 돌아가 터미널을 엽니다(이미 열려 있지 않다면 Ctrl+`). 그런 다음 `--yolo`와 `--enable-all-github-mcp-tools`를 사용해 Copilot CLI를 시작합니다. -> -> ```bash -> copilot --yolo --enable-all-github-mcp-tools -> ``` -> -> 이 프로젝트의 가장 최근 세션을 새로 시작하지 않고 이어서 사용하려면 `copilot --yolo --enable-all-github-mcp-tools --continue`를 실행합니다. 이전 연습에서 Copilot CLI가 이미 실행 중이라면 `/clear`를 보내 새 대화를 시작합니다. -> -> `--enable-all-github-mcp-tools`는 현재 세션에서 읽기/쓰기 GitHub MCP 도구를 활성화하므로, 워크숍 흐름 중 Copilot이 백로그를 읽고 pull request를 열 수 있습니다. - -> [!CAUTION] -> `--yolo`는 전체 자동 권한(`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`)을 활성화합니다. Codespace나 VM 같은 격리된 환경에서만 사용하고, 일상적인 개발을 위한 기본 별칭으로는 절대 설정하지 않습니다. 자세한 내용은 [Allowing and denying tool use][allow-all-warning]를 참고합니다. - -[allow-all-warning]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools -1. Copilot CLI 세션에서 다음을 입력합니다. - - ```text - /mcp add - ``` - -2. 구성 양식이 나타나면 Tab으로 필드 사이를 이동하면서 다음과 같이 입력합니다. - - - **Server Name**: `playwright` - - **Server Type**: **Local**(또는 **STDIO**로 표시됨)을 선택합니다. - - **Command**: `npx @playwright/mcp@latest --headless` - - **Tools**: 서버의 모든 도구를 허용하기 위해 `*` 그대로 둡니다. - -3. Ctrl+S를 눌러 저장합니다. 서버가 추가되고 즉시 사용할 수 있습니다. 재시작은 필요하지 않습니다. - -`--headless` 플래그는 Playwright가 표시 창 없이 브라우저를 실행하도록 지정합니다. 데스크톱을 표시할 수 없는 코드스페이스 안에서는 이 설정이 필요합니다. 내부적으로는 다음 내용이 `~/.copilot/mcp-config.json` 파일에 기록됩니다. - -```json -{ - "mcpServers": { - "playwright": { - "type": "local", - "command": "npx", - "args": ["@playwright/mcp@latest", "--headless"], - "tools": ["*"] - } - } -} -``` - -4. MCP server 목록을 확인해 서버가 등록되어 활성 상태인지 검증합니다. - - ```text - /mcp show - ``` - -5. 기본 제공 `github` server와 함께 `playwright`가 표시되어야 합니다. - -> [!NOTE] -> Tailspin Toys 프로젝트는 이미 end-to-end 테스트에 Playwright를 사용하므로, Playwright에 필요한 브라우저가 대체로 이미 설치되어 있습니다. 나중에 Copilot이 브라우저가 없다고 보고하면 `npx playwright install chromium`를 실행하도록 요청한 뒤 다시 시도합니다. - -## 웹 사이트 시작하기 - -Playwright MCP server가 테스트를 수행하려면 실행 중인 앱이 필요합니다. Copilot CLI에서 작업하는 동안 계속 실행되도록 **별도의** 터미널에서 Astro dev server를 시작합니다. - -1. Ctrl+`를 선택해 코드스페이스에서 새 터미널을 엽니다. -2. 웹 사이트를 시작합니다. - - ```bash - npm run dev - ``` - -3. 이 터미널은 계속 실행된 상태로 둡니다. `Astro server: http://localhost:4321` 배너가 표시되면 앱이 준비된 것입니다. - -## 필터링 기능 테스트하기 - -Copilot CLI 세션으로 돌아가 Copilot에 기능 테스트를 요청합니다. - -[Playwright MCP server][playwright-mcp-server]는 Copilot이 실제 브라우저를 제어할 수 있게 해줍니다. 직접 앱을 눌러 보며 작업을 확인하는 대신, agent가 페이지를 열고, 탐색하고, 필터를 적용하고, 결과를 다시 읽어 준 다음, 본 내용을 요약할 수 있습니다. 대화를 벗어나지 않고 기능이 기대대로 동작하는지 확인하는 가장 빠른 방법입니다. - -내부적으로 Playwright MCP server는 스크린샷이 아니라 페이지의 [accessibility tree][playwright-mcp-server]를 기반으로 동작합니다. 즉, agent는 보조 기술이 처리하는 방식과 유사하게 구조화되고 레이블이 지정된 요소(버튼, 링크, 목록 항목)를 기준으로 추론합니다. 따라서 빠른 기능 점검이 가벼운 접근성 sanity check 역할도 함께 합니다. - -서버가 연결되고 앱이 실행 중인 상태에서 Copilot에게 방금 만든 필터링 기능을 검증해 달라고 요청합니다. - -```text -Using the Playwright MCP server, open a browser to the running app at http://localhost:4321 and verify the new game filtering feature: - -1. Go to the games page and note how many games are listed. -2. Apply a category filter and confirm the list updates to only show games in that category. -3. Clear it, then apply a publisher filter and confirm the list updates to that publisher. -4. Combine a category and a publisher filter and confirm the results respect both. - -Report what you observe at each step, and call out anything that does not behave as expected. -``` - -Copilot은 Playwright MCP server를 통해 브라우저를 실행하고, 각 단계를 수행한 뒤, 확인한 내용을 보고합니다. 요약 내용을 issue의 acceptance criteria와 비교해 보고, 어긋나는 부분이 있으면 후속 질문을 하거나 pull request를 열기 전에 코드를 수정하도록 다시 요청합니다. - -> [!NOTE] -> 이 테스트를 수행하려면 앱이 `http://localhost:4321`에서 실행 중이어야 합니다. Dev server를 중지했다면 프롬프트를 보내기 전에 다시 시작합니다. Copilot이 처음으로 Playwright MCP server를 사용할 때 브라우저를 다운로드해야 할 수도 있습니다. 브라우저가 없다고 보고하면 `npx playwright install chromium`를 실행하도록 요청한 뒤 다시 시도합니다. - -[playwright-mcp-server]: https://github.com/microsoft/playwright-mcp -## 요약 및 다음 단계 - -축하합니다. Copilot CLI에서 Playwright MCP server를 사용해 기능을 수동으로 테스트했습니다. 정리하면 다음을 수행했습니다. - -- Model Context Protocol(MCP)이 무엇인지 학습하고, MCP server가 Copilot CLI를 어떻게 확장하는지 살펴보았습니다. -- `/mcp add`로 Playwright MCP server를 추가했습니다. -- 기능을 배포하기 전에 Copilot에게 브라우저를 제어해 필터링 기능을 검증하도록 요청했습니다. - -이제 기능이 동작함을 확인했으니, 다음 연습으로 이동해 [에이전트 스킬의 도움을 받아 pull request를 열 수 있습니다][next-lesson]. - -## 리소스 - -- [MCP가 대체 무엇이고 왜 모두가 이야기할까요?][mcp-blog-post] -- [Microsoft Playwright MCP Server][playwright-mcp-server] -- [Copilot CLI용 MCP server 추가하기][cli-add-mcp] -- [GitHub MCP Server][github-mcp-server] - -[previous-lesson]: ../3-generating-code/ -[next-lesson]: ../5-agent-skills/ -[mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/ -[github-mcp-server]: https://github.com/github/github-mcp-server -[cli-add-mcp]: https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers diff --git a/docs/ko-kr/real-world-development/cli/5-agent-skills.md b/docs/ko-kr/real-world-development/cli/5-agent-skills.md index 48c8f6bb..c6f71eec 100644 --- a/docs/ko-kr/real-world-development/cli/5-agent-skills.md +++ b/docs/ko-kr/real-world-development/cli/5-agent-skills.md @@ -1,119 +1,113 @@ --- -title: "연습 5 - 에이전트 스킬 사용하기" +title: "레슨 5 - quality-checks 스킬 사용자 지정 및 사용하기" +description: "기존 quality-checks 스킬을 살펴보고 결과 보고 형식을 사용자 지정한 뒤 필터링 기능을 검증하는 데 사용합니다." authors: - geektrainer -lastUpdated: 2026-06-30 +lastUpdated: 2026-09-29 --- -앱 개발에는 빌드 생성, 테스트 실행, pull request 작성처럼 반복 가능한 작업이 자주 포함됩니다. **에이전트 스킬(Agent Skills)**을 사용하면 Copilot과 다른 AI agent에 이러한 작업을 수행하는 방법에 대한 가이드를 제공할 수 있습니다. 스킬은 agent가 필요할 때 불러올 수 있는 지침, 스크립트, 리소스 폴더입니다. [Agent Skills는 오픈 표준][agent-skills-repo]이며, 여러 agent에서 사용됩니다. 따라서 동일한 스킬을 Copilot Chat in agent mode, Copilot cloud agent, Copilot CLI, GitHub Copilot app 전반에서 사용할 수 있습니다. +코드 작성은 개발 작업의 일부일 뿐입니다. 코드를 직접 검증하고 지침 파일로 코딩 표준을 적용했습니다. 이제 테스트, 린트, 지속적 통합(CI)의 다른 부분을 살펴봅니다. -스킬은 프로젝트의 `.github/skills` 폴더 또는 전역 `~/.copilot/skills`에 저장됩니다. 각 스킬은 YAML frontmatter(`name`과 `description`)가 포함된 `SKILL.md` 파일과 그 뒤에 이어지는 markdown 지침으로 구성된 폴더입니다. +이런 작업에는 **에이전트 스킬**이 적합합니다. 스킬을 사용하면 Copilot이 작업을 올바르게 실행하는 방법을 알 수 있습니다. -```yaml ---- -name: make-contribution -description: All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly. ---- -``` +이 레슨에서는 다음을 수행합니다. -스킬에는 스크립트, asset, 참고 자료를 담은 하위 폴더도 포함될 수 있습니다. 전체 구조는 [agent skills specification][agent-skills-spec]에서 다룹니다. +- 기존 `quality-checks` 스킬을 살펴봅니다. +- 결과 보고 형식을 사용자 지정합니다. +- 스킬을 새로 불러오고 실행합니다. -> [!TIP] -> 스킬은 동적으로 로드됩니다. 어떤 스킬이 적용되는지는 agent가 `description` 필드를 기준으로 판단합니다. 시나리오별로 명확한 설명이 있어야 실제로 사용되는 스킬이 되고, 그렇지 않으면 무시될 수 있습니다. +## 시나리오 -[agent-skills-repo]: https://github.com/agentskills/agentskills -[agent-skills-spec]: https://agentskills.io/specification -이제 스킬이 팀의 사양에 맞는 pull request를 보장하는 방법을 살펴보겠습니다. +Tailspin Toys는 단위 테스트, 린트, 타입 검사를 위해 `quality-checks` 스킬을 사용합니다. 팀은 결과를 더 쉽게 읽을 수 있도록 보고 형식을 개선하려고 합니다. -## 시나리오 +## 지침, 스크립트, 리소스 + +에이전트 스킬은 재사용할 수 있는 작업 지침, 실행 가능한 스크립트, 지원 리소스를 패키지로 제공합니다. 스킬은 기본적으로 이름이 같은 폴더에 있는 `SKILL.md` 파일로 구성됩니다. Markdown 파일에는 스킬의 이름과 설명, 역할을 소개하고 사용할 시점을 안내하는 frontmatter와 지침이 포함됩니다. 폴더에 스크립트와 기타 리소스를 넣을 수도 있습니다. -팀에는 pull request(PR)에 대한 다음 요구 사항이 있습니다. +> [!NOTE] +> 스킬에 추가 파일이나 폴더가 꼭 필요한 것은 아닙니다. Tailspin Toys의 `quality-checks` 스킬은 프로젝트에서 기존 명령을 사용하므로 `SKILL.md` 파일만 포함합니다. -- 명확한 커밋 메시지를 사용하고, 파일은 논리적으로 그룹화해야 합니다. -- PR을 만들기 전에 모든 테스트가 통과해야 합니다. -- 각 PR에는 다음 섹션이 포함되어야 합니다. - - 변경이 필요한 이유에 대한 설명 - - 변경된 파일 개요 - - 중요한 코드 블록 스니펫 - - 수행한 변경 사항을 묶어 설명하는 세부 내용 +스킬을 프로젝트의 `.github/skills` 폴더에 저장하면 팀에서 공유하고 재사용할 수 있는 리포지토리 자산이 됩니다. 사용자 스킬 폴더인 `~/.copilot/skills`에 저장할 수도 있습니다. -팀은 Copilot으로 코드와 PR을 생성하고 있으므로, AI 도구가 이러한 요구 사항을 따르도록 보장하고 싶어 합니다. +## 스킬 살펴보기 -이 연습에서는 다음을 수행합니다. +Tailspin Toys 팀이 단위 테스트, 린트, 타입 검사를 실행하기 위해 만든 `quality-checks` 스킬을 살펴봅니다. -- Pull request 생성을 위한 기존 스킬을 살펴봅니다. -- AI agent가 스킬을 활용하는 방식을 학습합니다. -- 스킬의 도움으로 가이드라인에 맞는 PR을 만듭니다. +1. Codespace로 돌아갑니다. Codespaces 편집기에서 `.github/skills/quality-checks/SKILL.md`를 엽니다. +2. 맨 위의 `name` 및 `description`을 읽습니다. 설명은 Copilot이 스킬을 언제 사용할지 판단하는 데 도움을 줍니다. +3. 지침을 읽고 Copilot이 테스트와 린트 작업을 진행하도록 안내하는 방식을 살펴봅니다. +4. 아직 **결과 보고 형식** 섹션이 없다는 점을 확인합니다. -## 스킬 실행하기 +## 변경 전에 스킬 실행하기 -스킬은 agent가 필요하다고 판단할 때 동적으로 로드됩니다. 어떤 스킬을 사용할지는 `SKILL.md` 파일의 설명에 따라 결정됩니다. 따라서 스킬의 사용 사례를 정의하는 명확한 설명을 작성하는 것이 중요합니다. +Copilot CLI에서 스킬을 직접 호출하거나 자연어로 요청할 수 있습니다. Copilot에 세 가지 검사를 실행하도록 요청합니다. -## PR 스킬 살펴보기 +1. Interactive 모드의 필터링 대화로 돌아갑니다. +2. 다음 프롬프트를 입력합니다. -Tailspin Toys에는 PR 생성에 대한 요구 사항이 있으므로, AI 도구가 이러한 가이드라인을 따르는 PR을 생성할 수 있도록 도와주는 스킬을 만들었습니다. 이 스킬이 무엇을 하는지 이해하기 위해 내용을 살펴보겠습니다. + ```plaintext + quality-checks 스킬을 실행해 단위 테스트, 린트, 타입 검사를 수행해 주세요. + ``` -1. `.github/skills/make-contribution/SKILL.md`를 엽니다. -2. 이름과 설명을 확인합니다. 설명이 pull request 생성 또는 코드 커밋 요청이 있을 때 사용해야 하는 시나리오를 어떻게 강조하는지 확인합니다. -3. 스킬 내용을 읽어 봅니다. 브랜치 생성 방식, 커밋 생성 방식, pull request 내용에 관한 규칙이 정의되어 있음을 확인합니다. +3. 마지막에 표시되는 보고서를 살펴봅니다. -## 스킬 사용하기 +## 결과 보고 형식 사용자 지정하기 -앞서 강조했듯이 스킬은 Copilot CLI가 자동으로 호출합니다. 따라서 Copilot에게 PR 생성을 요청하기만 하면 됩니다. +무엇을 실행했는지, 성공했는지, 도구에서 어떤 결과를 받았는지 알려 주는 보고서를 작성하도록 스킬을 업데이트합니다. -> [!TIP] -> **Copilot CLI 세션 시작하기** -> -> 아래 연습을 시작하기 전에 코드스페이스로 돌아가 터미널을 엽니다(이미 열려 있지 않다면 Ctrl+`). 그런 다음 `--yolo`와 `--enable-all-github-mcp-tools`를 사용해 Copilot CLI를 시작합니다. -> -> ```bash -> copilot --yolo --enable-all-github-mcp-tools -> ``` -> -> 이 프로젝트의 가장 최근 세션을 새로 시작하지 않고 이어서 사용하려면 `copilot --yolo --enable-all-github-mcp-tools --continue`를 실행합니다. 이전 연습에서 Copilot CLI가 이미 실행 중이라면 `/clear`를 보내 새 대화를 시작합니다. -> -> `--enable-all-github-mcp-tools`는 현재 세션에서 읽기/쓰기 GitHub MCP 도구를 활성화하므로, 워크숍 흐름 중 Copilot이 백로그를 읽고 pull request를 열 수 있습니다. +1. `.github/skills/quality-checks/SKILL.md`로 돌아갑니다. +2. 파일 끝에 다음 섹션을 추가합니다. -> [!CAUTION] -> `--yolo`는 전체 자동 권한(`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`)을 활성화합니다. Codespace나 VM 같은 격리된 환경에서만 사용하고, 일상적인 개발을 위한 기본 별칭으로는 절대 설정하지 않습니다. 자세한 내용은 [Allowing and denying tool use][allow-all-warning]를 참고합니다. + ```markdown + ## 결과 보고 형식 -[allow-all-warning]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools -1. 다음 프롬프트를 사용해 Copilot에게 PR 생성을 요청합니다. + 작업이 끝나면 실행한 각 명령과 통과, 실패, 차단 여부를 보고합니다. 도구에서 보고한 경우에만 테스트 수, 실행 시간, 오류, 경고, 기타 측정값을 포함합니다. 실패 또는 차단된 항목에 대한 다음 조치를 제시하고, 건너뛰거나 완료되지 않은 검사를 통과한 것으로 설명하지 않습니다. + ``` - ``` - Can you please create a pull request for me! - ``` +3. 파일이 자동으로 저장됩니다. -2. Copilot이 요청을 확인합니다. 잠시 후 Copilot이 **make-contribution** 스킬을 사용 중이라고 표시하는 것을 확인할 수 있습니다. +## 업데이트한 스킬 실행하기 -3. Copilot은 이어서 스킬의 지침을 따릅니다. 먼저 테스트를 실행한 뒤 브랜치, 커밋, 그리고 최종적으로 PR을 생성합니다. -4. PR이 생성되면 리포지토리로 돌아가 PR을 엽니다. 섹션이 스킬에 정의된 가이드라인을 따르고 있으며, 팀이 제시한 요구 사항과 일치하는지 확인합니다. -5. 다음 연습으로 넘어가기 전에 이 필터링 PR과 접근성 작업을 분리하기 위해 로컬 작업 공간을 `main`에서 새 브랜치로 초기화합니다. +변경 사항이 실제 실행 결과에 반영되는지 확인합니다. Copilot CLI는 대화를 다시 시작하지 않아도 편집된 스킬을 새로 불러올 수 있습니다. - ```bash - git checkout main - git pull - git checkout -b accessibility-cli - ``` +1. 다음을 입력합니다. + + ```plaintext + /skills reload + ``` + +2. 이전과 동일한 프롬프트를 입력합니다. + + ```plaintext + quality-checks 스킬을 실행해 단위 테스트, 린트, 타입 검사를 수행해 주세요. + ``` + +3. 마지막에 표시되는 보고서를 살펴보고 첫 번째 보고서와 비교합니다. ## 요약 및 다음 단계 -에이전트 스킬의 도움으로 문서화된 요구 사항을 충족하는 새로운 PR을 만들었습니다. 다음을 수행했습니다. +기존 에이전트 스킬을 사용자 지정하고 사용했습니다. 이 레슨에서는 다음을 수행했습니다. + +- 단위 테스트, 린트, 타입 검사를 위한 `quality-checks` 스킬을 살펴봤습니다. +- 결과 보고 형식을 사용자 지정했습니다. +- 스킬을 새로 불러오고 실행했습니다. -- Pull request 생성을 위한 기존 스킬을 살펴보았습니다. -- AI agent가 스킬을 활용하는 방식을 학습했습니다. -- 스킬의 도움으로 가이드라인에 맞는 PR을 만들었습니다. +이 변경 사항은 필터링 기능 PR에 포함됩니다. 다음으로 [Playwright MCP 서버][next-lesson]를 사용해 Copilot이 사이트와 상호 작용하도록 합니다. -스킬은 특정 작업에 적합하지만, 더 강력한 작업을 수행하려면 [custom agents][next-lesson]를 활용해야 합니다. 다음으로 이를 살펴보겠습니다. +## 추가 스킬 예제 -## 리소스 +다음 커뮤니티 예제는 참고 자료이며 추가 실습은 아닙니다. -- [에이전트 스킬 소개][about-agent-skills] -- [Agent Skills Specification][agent-skills-spec] -- [Agent Skills Repository][agent-skills-repo] -- [Awesome-copilot의 Agent Skills][awesome-copilot-skills] +- [Agent Skills 사양][skill-spec] +- [기여 워크플로: `make-repo-contribution`][contribution-example] +- [요구 사항 문서: `prd`][prd-example] +- [다이어그램 및 내보내기 스크립트: `drawio`][drawio-example] +- [브라우저 테스트: `webapp-testing`][browser-example] -[previous-lesson]: ../4-mcp/ -[next-lesson]: ../6-custom-agents/ -[about-agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills -[awesome-copilot-skills]: https://github.com/github/awesome-copilot/tree/main/skills +[previous-lesson]: ../4-custom-instructions/ +[next-lesson]: ../6-mcp-playwright/ +[skill-spec]: https://agentskills.io/specification +[contribution-example]: https://github.com/github/awesome-copilot/tree/main/skills/make-repo-contribution +[prd-example]: https://github.com/github/awesome-copilot/tree/main/skills/prd +[drawio-example]: https://github.com/github/awesome-copilot/tree/main/skills/drawio +[browser-example]: https://github.com/github/awesome-copilot/tree/main/skills/webapp-testing diff --git a/docs/ko-kr/real-world-development/cli/6-custom-agents.md b/docs/ko-kr/real-world-development/cli/6-custom-agents.md deleted file mode 100644 index ddb510e4..00000000 --- a/docs/ko-kr/real-world-development/cli/6-custom-agents.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "연습 6 - GitHub Copilot CLI로 커스텀 에이전트 사용하기" -authors: - - geektrainer -lastUpdated: 2026-06-30 ---- - -## 커스텀 에이전트란 무엇인가요? - -GitHub Copilot의 [커스텀 에이전트][custom-agents-concept]를 사용하면 개발 워크플로 안의 특정 작업이나 도메인에 맞춘 전문 AI 도우미를 만들 수 있습니다. 리포지토리의 `.github/agents` 폴더 안에 있는 markdown 파일로 agent를 정의하면, 특정 종류의 작업을 더 효과적으로 수행하도록 Copilot을 이끄는 집중된 지침, 모범 사례, 코딩 패턴, 도메인별 지식을 제공할 수 있습니다. 팀은 전문성을 재사용 가능한 agent로 체계화할 수 있습니다. 예를 들어 [WCAG][wcag] 준수를 강제하는 접근성 agent, 보안 코딩 관행을 따르는 보안 agent, 일관된 테스트 패턴을 유지하는 테스트 agent 등을 만들 수 있습니다. - -커스텀 에이전트는 프로젝트의 `.github/agents` 폴더 또는 전역 `~/.copilot/agents`의 markdown 파일로 정의합니다. 각 파일에는 최소한 `name`과 `description`이 포함된 YAML frontmatter가 있고, 그 뒤에 agent의 동작, 전문성, 지침을 정의하는 markdown 프롬프트가 이어집니다. - -### 커스텀 에이전트와 에이전트 스킬 비교하기 - -커스텀 에이전트와 [에이전트 스킬][agent-skills-concept] 사이에는 개념적으로 겹치는 부분이 있습니다. 둘 다 주로 markdown 파일로 정의되며 AI에게 작업 수행 방법을 알려 줍니다. 가장 깔끔하게 구분하면 **커스텀 에이전트**는 작업자이고, **스킬**은 도구입니다. - -커스텀 에이전트는 자체 컨텍스트 창을 가지며, 작업을 수행하는 과정에서 스킬(심지어 다른 agent까지도)을 오케스트레이션하도록 설계됩니다. 이 실습에서 접근성 커스텀 에이전트는 접근성 가이드라인을 기준으로 사이트를 검토하고 업데이트합니다. 이 과정에서 pull request 워크플로 스킬이나 테스트 실행 및 관리를 담당하는 스킬 같은 도구를 호출할 수도 있습니다. - -> [!NOTE] -> 커스텀 에이전트를 작성하는 유일한 "정답"은 없습니다. AI의 다른 작업과 마찬가지로, 환경과 시나리오에 가장 잘 맞는 방식을 찾기 위해 테스트하고 반복해 보아야 합니다. - -[custom-agents-concept]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents -[agent-skills-concept]: https://docs.github.com/copilot/concepts/agents/about-agent-skills -[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/ -## 시나리오 - -많은 웹 애플리케이션이 모든 사용자에게 접근 가능하지 못하며, 지금 작업 중인 웹 사이트도 예외는 아닙니다. 커스텀 에이전트를 사용해 접근성 문제를 식별하고 해결해 보겠습니다. - -Tailspin Toys는 시각 능력이나 선호도와 관계없이 모든 사용자가 crowdfunding platform을 이용할 수 있도록 보장하는 데 전념하고 있습니다. 최근 사용자 피드백에 따르면 현재 dark theme는 텍스트와 배경색 사이의 대비가 충분하지 않아 일부 사용자가 읽기 어렵다고 느끼고 있습니다. 이 접근성 문제를 해결하기 위해 디자인 팀은 사용자가 켜고 끌 수 있는 high-contrast mode 구현을 요청했습니다. - -접근성은 매우 중요하므로 가능한 한 빠르게 구현하고 싶습니다. 커스텀 에이전트를 활용해 이 기능을 생성합니다. -이 연습에서는 다음을 수행합니다. - -- 커스텀 에이전트를 살펴봅니다. -- 커스텀 에이전트를 활성화하고 Copilot CLI를 사용해 작업을 할당합니다. - -## 접근성 커스텀 에이전트 검토하기 - -접근성을 위해 이미 커스텀 에이전트가 준비되어 있습니다. Copilot을 어떻게 안내하는지 이해하기 위해 내용을 검토해 보겠습니다. - -1. `.github/agents/accessibility.md`를 엽니다. -2. `name`과 `description` 필드가 포함된 YAML frontmatter를 확인합니다. - -> [!CAUTION] -> `name`과 `description`이 포함된 frontmatter는 커스텀 에이전트에 필수입니다. - -3. 이어지는 섹션을 훑어보며 다음 내용을 확인합니다. - - 접근 가능한 웹 사이트를 위한 코드를 생성할 때의 핵심 책임 - - 접근성 모범 사례 - - HTML, CSS, JavaScript용 코드 예시 - - 흔한 함정과 실수 목록 - -## Copilot CLI에서 커스텀 에이전트 사용하기 - -Copilot CLI에서는 `/agent` 명령으로 커스텀 에이전트를 시작할 수 있습니다. 이제 웹 사이트에 접근성 점검을 수행해 보겠습니다. - -> [!TIP] -> **Copilot CLI 세션 시작하기** -> -> 아래 연습을 시작하기 전에 코드스페이스로 돌아가 터미널을 엽니다(이미 열려 있지 않다면 Ctrl+`). 그런 다음 `--yolo`와 `--enable-all-github-mcp-tools`를 사용해 Copilot CLI를 시작합니다. -> -> ```bash -> copilot --yolo --enable-all-github-mcp-tools -> ``` -> -> 이 프로젝트의 가장 최근 세션을 새로 시작하지 않고 이어서 사용하려면 `copilot --yolo --enable-all-github-mcp-tools --continue`를 실행합니다. 이전 연습에서 Copilot CLI가 이미 실행 중이라면 `/clear`를 보내 새 대화를 시작합니다. -> -> `--enable-all-github-mcp-tools`는 현재 세션에서 읽기/쓰기 GitHub MCP 도구를 활성화하므로, 워크숍 흐름 중 Copilot이 백로그를 읽고 pull request를 열 수 있습니다. - -> [!CAUTION] -> `--yolo`는 전체 자동 권한(`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`)을 활성화합니다. Codespace나 VM 같은 격리된 환경에서만 사용하고, 일상적인 개발을 위한 기본 별칭으로는 절대 설정하지 않습니다. 자세한 내용은 [Allowing and denying tool use][allow-all-warning]를 참고합니다. - -[allow-all-warning]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools -1. Copilot CLI의 프롬프트 창에 `/agent`를 입력하고 Enter를 눌러 agent 목록을 엽니다. -2. 사용 가능한 agent 목록에서 **Accessibility agent**를 선택합니다. -3. 다음 프롬프트를 사용해 접근성 agent에게 접근성 백로그 항목을 검토하고 수정 사항을 생성해 달라고 요청합니다. - - ``` - Perform an accessibility review of the site. Pull the related issue down from the repository for details. Implement a high-contrast mode toggle that persists the user's preference across page reloads. Ensure there are e2e tests for any updates made to the project. Then create a PR with the updates. - ``` - -4. Copilot이 작업을 시작합니다. 먼저 issue를 가져오고, 검토를 수행하고, 업데이트를 생성하고, 마지막으로 PR을 만듭니다. PR을 만들 때 프로젝트의 PR 전용 스킬을 사용하는 점도 확인할 수 있습니다. - -> [!NOTE] -> 이 과정은 몇 분 정도 걸릴 수 있습니다. 지금까지 학습한 내용을 되돌아보거나, 음료를 즐기거나, Copilot CLI에서 사용할 수 있는 추가 명령을 다루는 다음 모듈을 미리 살펴보기에 좋은 시간입니다. - -## 요약 및 다음 단계 - -이 연습에서는 GitHub Copilot의 [커스텀 에이전트][custom-agents]를 살펴보았습니다. 커스텀 에이전트는 특정 작업과 도메인에 맞춘 전문 AI 도우미입니다. 커스텀 에이전트를 사용하면 팀의 전문성과 표준을 재사용 가능한 agent로 체계화해 Copilot이 특정 유형의 작업을 더 효과적으로 수행하도록 안내할 수 있습니다. - -다음 개념을 살펴보았습니다. - -- 커스텀 에이전트가 어떻게 정의되는지 -- Copilot CLI에서 커스텀 에이전트를 사용하는 방법 - -다음으로는 [몇 가지 slash commands][next-lesson]를 살펴보며 Copilot CLI의 추가 팁을 알아보겠습니다. - -## 리소스 - -- [커스텀 에이전트][custom-agents] -- [리포지토리용 커스텀 에이전트 만들기][creating-custom-agents] -- [Awesome-copilot의 커스텀 에이전트][awesome-copilot-agents] -- [조직에서 커스텀 에이전트를 사용하기 위한 준비][org-custom-agents] -- [엔터프라이즈에서 커스텀 에이전트를 사용하기 위한 준비][enterprise-custom-agents] - -[previous-lesson]: ../5-agent-skills/ -[next-lesson]: ../7-slash-commands/ -[custom-agents]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents -[creating-custom-agents]: https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/create-custom-agents -[awesome-copilot-agents]: https://github.com/github/awesome-copilot/tree/main/agents -[org-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents -[enterprise-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents diff --git a/docs/ko-kr/real-world-development/cli/6-mcp-playwright.md b/docs/ko-kr/real-world-development/cli/6-mcp-playwright.md new file mode 100644 index 00000000..c2044ebd --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/6-mcp-playwright.md @@ -0,0 +1,102 @@ +--- +title: "레슨 6 - Playwright MCP로 기능 검증하기" +description: "Copilot CLI에서 Playwright MCP를 확인하거나 구성하고 브라우저에서 필터링 기능을 살펴봅니다." +authors: + - geektrainer +lastUpdated: 2026-09-18 +--- + +앞서 살펴봤듯이 코드를 작성하는 일만으로는 충분하지 않습니다. 데이터와 외부 서비스를 다루고 Copilot에서 자동화 작업을 사용할 수 있도록 해야 합니다. MCP 서버를 사용하면 Copilot CLI에 기본 제공되는 기능을 넘어 도구와 서비스를 추가할 수 있습니다. + +이 레슨에서는 다음을 수행합니다. + +- Model Context Protocol(MCP)이 무엇이며 Copilot CLI에서 어떻게 사용하는지 알아봅니다. +- 아직 사용할 수 없는 경우 Playwright MCP 서버를 추가합니다. +- 에이전트가 브라우저를 조작해 필터링 기능을 살펴보도록 요청합니다. + +## 시나리오 + +단위 테스트와 엔드투엔드 테스트도 중요하지만, UI 업데이트를 검증하려면 실제로 UI와 상호 작용해야 합니다. Copilot이 사용자처럼 작업 중인 웹사이트를 사용하도록 하여 변경 사항이 예상대로 작동하는지 더 확실히 확인할 수 있습니다. + +## Model Context Protocol(MCP)이란? + +[Model Context Protocol(MCP)][mcp-blog-post]은 AI 에이전트가 외부 도구 및 서비스와 통신할 수 있도록 합니다. MCP를 사용하면 최신 정보를 확인하고 사용자를 대신해 작업을 수행할 수 있습니다. + +에이전트는 MCP 서버를 통해 도구와 리소스에 접근합니다. MCP 서버는 에이전트와 외부 도구 및 서비스 사이의 연결 역할을 합니다. 각 MCP 서버에서 에이전트가 사용할 수 있는 도구와 리소스가 제공됩니다. + +널리 사용되는 MCP 서버의 예시는 다음과 같습니다. + +- **[GitHub MCP Server][github-mcp]**: GitHub 리포지토리, 이슈, 풀 리퀘스트를 관리하는 API에 접근할 수 있습니다. +- **[Playwright MCP Server][playwright-mcp-server]**: Playwright를 사용한 브라우저 자동화 기능을 제공합니다. + +다양한 MCP 서버가 있으며, GitHub는 생태계의 검색 및 기여를 돕기 위해 [MCP 레지스트리][mcp-registry]를 운영합니다. + +> [!CAUTION] +> MCP 서버도 프로젝트의 다른 종속성과 마찬가지로 취급합니다. 사용하기 전에 소스 코드를 검토하고 게시자를 확인하며 보안에 미치는 영향을 고려합니다. + +## Playwright MCP 서버 추가하기 + +Playwright MCP 서버를 아직 사용할 수 없다면 추가하여 Copilot이 사용자처럼 사이트와 상호 작용하도록 합니다. + +> [!NOTE] +> Copilot CLI에서 Playwright MCP를 이미 사용할 수 있다면 아래 설정 단계는 건너뛰고 다음 섹션으로 진행합니다. + +1. Codespace로 돌아갑니다. +2. Copilot CLI에서 다음 명령을 입력해 MCP 서버 추가 대화 상자를 엽니다. + + ```plaintext + /mcp add + ``` + +3. 이름으로 `playwright`를 입력하고 Tab을 누릅니다. +4. Enter를 눌러 서버 유형으로 **STDIO**를 확인한 다음 Tab을 누릅니다. +5. **Command** 대화 상자에 다음을 붙여 넣습니다. + + ```plaintext + npx -y @playwright/mcp@latest --headless --no-sandbox + ``` + +6. Control+S(Mac) 또는 Ctrl+S(Windows/Linux)를 눌러 새 MCP 서버를 저장합니다. +7. Esc를 눌러 MCP 대화 상자를 닫습니다. + +## Playwright를 사용해 Copilot이 기능을 살펴보도록 요청하기 + +앞서 기능이 제대로 작동하는지 직접 확인했습니다. 이제 Copilot이 사용할 수 있는 Playwright MCP 서버로 같은 검증을 수행합니다. + +1. 다음 프롬프트로 Copilot에 Playwright MCP 서버를 사용해 기능을 검증하도록 요청합니다. + + ```plaintext + 앱을 시작하고 Playwright MCP로 이슈와 계획에 따라 필터링 기능을 확인해 주세요. 변경하지 말고 무엇이 작동하고 작동하지 않는지 알려 주세요. 작업이 끝나면 시작한 서버를 중지해 주세요. + ``` + +> [!NOTE] +> 일반적으로 Copilot이 알아서 MCP 서버를 사용하므로 서버 이름을 직접 요청할 필요는 없습니다. 하지만 사용할 서버를 알고 있다면 명시적으로 알려 주는 편이 좋습니다. 일관성이 높아지고 토큰을 조금 절약할 수 있습니다. + +2. Copilot이 브라우저에서 기능을 확인하는 여러 단계를 표시하는지 살펴봅니다. +3. 보고서를 읽고 모든 동작이 예상과 일치하는지 확인합니다. + +Copilot은 서버를 시작하고 Playwright로 사이트를 조작한 다음 서버를 중지하고 결과를 보고합니다. + +## 요약 및 다음 단계 + +이 레슨에서는 다음을 수행했습니다. + +- Model Context Protocol(MCP)이 무엇이며 MCP 서버가 Copilot에 도구를 추가하는 방식을 알아봤습니다. +- Playwright MCP 서버를 사용할 수 있는지 확인하고, 필요한 경우 추가했습니다. +- 에이전트가 브라우저를 조작해 필터링 기능을 살펴보도록 요청했습니다. + +사용 가능한 Playwright MCP 서버로 기능을 *테스트*했습니다. 하지만 MCP는 Copilot을 확장하는 여러 방법 중 하나입니다. 다음으로 [사용자 지정 에이전트][next-lesson]를 만들어 접근성 검토와 같은 작업을 간소화합니다. + +## 리소스 + +- [MCP란 무엇이며 왜 주목받고 있나요?][mcp-blog-post] +- [Microsoft Playwright MCP Server][playwright-mcp-server] +- [Copilot CLI에 MCP 서버 추가하기][add-mcp] + +[previous-lesson]: ../5-agent-skills/ +[next-lesson]: ../7-qa-agent/ +[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 +[github-mcp]: https://github.com/github/github-mcp-server +[mcp-registry]: https://github.com/mcp +[add-mcp]: https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers diff --git a/docs/ko-kr/real-world-development/cli/7-qa-agent.md b/docs/ko-kr/real-world-development/cli/7-qa-agent.md new file mode 100644 index 00000000..a8754699 --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/7-qa-agent.md @@ -0,0 +1,92 @@ +--- +title: "레슨 7 - QA 에이전트 만들고 사용하기" +description: "이슈 요구 사항, quality-checks 스킬, Playwright MCP를 결합하는 QA 사용자 지정 에이전트를 만듭니다." +authors: + - geektrainer +lastUpdated: 2026-09-18 +--- + +`quality-checks` 스킬로 자동 검사를 실행하고 Playwright MCP로 브라우저에서 필터링 경험을 확인했습니다. 이제 명확한 QA 절차를 정의하는 사용자 지정 에이전트로 두 기능을 함께 사용합니다. + +이 레슨에서는 다음을 수행합니다. + +- 사용자 지정 에이전트가 지침, 스킬, MCP 도구를 함께 사용하는 방식을 살펴봅니다. +- 재사용 가능한 품질 보증 프로필을 만들고 검토합니다. +- QA 에이전트를 선택하고 필터링 이슈에 따라 결과를 검토합니다. + +## 시나리오 + +Tailspin Toys는 풀 리퀘스트(PR)를 열기 전에 요구 사항, 코드 품질, 자동 검사, 테스트 범위, 브라우저 동작을 일관되게 검토하려고 합니다. 사용자 지정 에이전트를 사용하면 QA 절차를 조율하고 재사용 가능한 보고서를 만들 수 있습니다. + +## 사용자 지정 에이전트란? + +사용자 지정 에이전트는 Markdown 프로필로 정의하는 특화된 Copilot입니다. 프로필에는 에이전트의 목적, 지침, 사용할 수 있는 도구가 포함됩니다. 이 워크숍에서는 `.github/agents/qa.agent.md`에 QA 역할을 정의하고 Copilot CLI에서 선택합니다. + +지금까지 사용한 사용자 지정 기능은 각각 다른 역할을 합니다. 리포지토리 지침은 팀 표준을 설명합니다. `quality-checks` 스킬은 반복 가능한 검사를 제공합니다. Playwright MCP는 브라우저 도구를 제공합니다. QA 프로필은 Copilot에 해당 기능을 사용해 요구 사항을 평가하고 결과를 보고하는 방법을 알려 줍니다. 다른 기능을 대체하거나 별도의 대화를 요구하지 않습니다. + +## QA 프로필 만들기 + +기능 PR을 열기 전에 Copilot에 재사용 가능한 QA 프로필을 만들어 달라고 요청합니다. 프로필에는 QA가 수행할 검사와 반드시 지켜야 할 경계가 모두 포함됩니다. + +1. Codespace로 돌아가 필터링 대화가 Interactive 모드인지 확인합니다. +2. 기본 에이전트에 새 사용자 지정 에이전트를 만들도록 요청합니다. + + ```plaintext + .github/agents/qa.agent.md에 QA라는 사용자 지정 에이전트를 만들어 주세요. 이 에이전트는 이슈와 합의된 요구 사항에 따라 기능을 확인하고, 리포지토리 지침을 따르고, quality-checks 스킬을 실행하고, Playwright MCP로 동작을 검증하고, 테스트 범위가 부족하면 테스트를 추가해야 합니다. + + 각 요구 사항을 근거와 함께 통과, 실패, 차단으로 보고해야 합니다. 구현 코드를 변경하기 전에 먼저 물어봐야 하며, 변경 사항을 커밋하거나 풀 리퀘스트를 열어서는 안 됩니다. + + 지금은 검토할 프로필만 만들어 주세요. + ``` + +## 프로필 검토하기 + +새 에이전트를 사용하기 전에 프로필을 검토하여 의도한 QA 작업 흐름과 경계가 반영되었는지 확인합니다. 확인만 요청했는데 에이전트가 기능을 변경하거나 범위가 지나치게 넓어지는 일을 방지합니다. + +1. `/diff`를 입력하고 `.github/agents/qa.agent.md`를 엽니다. +2. frontmatter를 읽습니다. `description`은 필수이며 `name`은 선택 사항입니다. `name`을 지정하면 에이전트를 명확하게 표시할 수 있습니다. +3. 프로필 지침을 읽고 QA가 요구 사항에서 시작하고 리포지토리 지침을 따르고 `quality-checks` 스킬을 실행하고 Playwright MCP를 사용하는지 확인합니다. +4. QA가 근거를 보고하고 구현 코드를 변경하기 전에 확인을 요청하며 변경 사항을 커밋하거나 PR을 만들지 않는지 확인합니다. +5. 프로필에서 이러한 책임이나 경계가 빠져 있다면 계속하기 전에 기본 에이전트에 수정을 요청합니다. + +## 이슈를 기준으로 QA 실행하기 + +Copilot CLI는 대화가 시작될 때 프로젝트 에이전트를 불러옵니다. 프로필을 만든 뒤 동일한 필터링 대화를 다시 시작하고 QA를 선택하여 기존 이슈와 계획의 결정 사항을 사용하게 합니다. + +1. 다음 프롬프트를 입력해 에이전트를 활성화합니다. + + ```plaintext + /agent QA + ``` + +> [!NOTE] +> 방금 에이전트를 만들었기 때문에 사용 가능한 에이전트 목록에 표시되지 않을 수 있습니다. 에이전트는 존재하며 위 명령으로 활성화할 수 있습니다. + +2. 다음 프롬프트로 QA 에이전트에 기능을 검토하도록 요청합니다. + + ```plaintext + 이슈와 계획에서 결정한 내용에 따라 필터링 기능을 검토해 주세요. PR을 열 준비가 되었나요? + ``` + +3. QA 에이전트가 작업하는 과정을 살펴봅니다. +4. 작업이 끝나면 결과 보고서를 읽습니다. + +## 요약 및 다음 단계 + +재사용 가능한 전문 역할을 작업 흐름에 추가하고 그 결과를 검토했습니다. 이 레슨에서는 다음을 수행했습니다. + +- 사용자 지정 에이전트가 지침, 스킬, MCP 도구를 함께 사용하는 방식을 살펴봤습니다. +- 재사용 가능한 QA 프로필을 만들고 검토했습니다. +- QA 에이전트를 선택하고 필터링 이슈에 따라 결과를 검토했습니다. + +이제 구현, 스킬 업데이트, QA 프로필, 테스트, 검증 보고서를 검토할 준비가 되었습니다. 다음으로 [기능 PR을 만들고 Agent Merge를 사용합니다][next-lesson]. + +## 리소스 + +- [Copilot CLI용 사용자 지정 에이전트 만들기][create-agents] +- [사용자 지정 에이전트 구성][agent-config] + +[previous-lesson]: ../6-mcp-playwright/ +[next-lesson]: ../8-create-pull-request/ +[create-agents]: https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli +[agent-config]: https://docs.github.com/copilot/reference/custom-agents-configuration diff --git a/docs/ko-kr/real-world-development/cli/7-slash-commands.md b/docs/ko-kr/real-world-development/cli/7-slash-commands.md deleted file mode 100644 index ce75d611..00000000 --- a/docs/ko-kr/real-world-development/cli/7-slash-commands.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: "연습 7 - GitHub Copilot CLI의 슬래시 명령" -authors: - - geektrainer -lastUpdated: 2026-06-30 ---- - -좋은 CLI 도구라면 그렇듯 GitHub Copilot CLI에도 다양한 slash commands가 포함되어 있습니다. 이 명령은 고급 기능, "내부 동작" 정보, 추가 구성 옵션을 제공합니다. 이미 `/clear`로 컨텍스트를 지우고 `/mcp`로 MCP server를 검사하는 방법을 살펴보았습니다. 이제 `/context`, `/model`, `/share`, `/delegate`를 포함한 몇 가지 강력한 명령을 더 살펴보겠습니다. - -## 시나리오 - -이제 핵심 CLI 흐름은 모두 살펴보았습니다. 이번에는 세션 공유, 모델 전환, [Copilot cloud agent][about-cloud-agent]에 작업 위임 같은 추가 기능을 알아보겠습니다. - -이 연습에서는 다음을 사용합니다. - -- `/share`로 세션을 팀과 공유할 수 있도록 GitHub gist를 만듭니다. -- `/context`로 Copilot CLI가 현재 사용 중인 컨텍스트를 확인합니다. -- `/model`로 사용 가능한 모델 목록을 확인하고 원한다면 다른 모델을 선택합니다. -- `/delegate`로 선택적으로 작업을 cloud agent에 넘깁니다. 이 기능을 사용하려면 cloud agent가 필요하며, Copilot Student, Pro, Pro+, Business, Enterprise에서 사용할 수 있습니다. 즉 Copilot Free를 제외한 모든 플랜에서 사용할 수 있습니다. - -## 세션 공유하기 - -AI 도구를 포함해 어떤 도구든 잘 활용하는 것은 하나의 기술입니다. 팀으로 함께 작업하면서 서로의 학습 내용을 공유하는 것은 모두의 경험을 개선하고 더 높은 품질의 코드를 생성하는 가장 좋은 방법입니다. 이를 지원하기 위해 Copilot CLI는 `/share` 명령을 제공합니다. `/share` 명령은 세션에서 사용한 프롬프트와 Copilot이 따랐던 로직을 포함해 세션 세부 정보를 담은 markdown 파일이나 GitHub gist를 생성할 수 있습니다. - -이제 팀과 공유할 수 있는 GitHub gist를 만들어 보겠습니다. - -> [!TIP] -> **Copilot CLI 세션 시작하기** -> -> 아래 연습을 시작하기 전에 코드스페이스로 돌아가 터미널을 엽니다(이미 열려 있지 않다면 Ctrl+`). 그런 다음 `--yolo`와 `--enable-all-github-mcp-tools`를 사용해 Copilot CLI를 시작합니다. -> -> ```bash -> copilot --yolo --enable-all-github-mcp-tools -> ``` -> -> 이 프로젝트의 가장 최근 세션을 새로 시작하지 않고 이어서 사용하려면 `copilot --yolo --enable-all-github-mcp-tools --continue`를 실행합니다. 이전 연습에서 Copilot CLI가 이미 실행 중이라면 `/clear`를 보내 새 대화를 시작합니다. -> -> `--enable-all-github-mcp-tools`는 현재 세션에서 읽기/쓰기 GitHub MCP 도구를 활성화하므로, 워크숍 흐름 중 Copilot이 백로그를 읽고 pull request를 열 수 있습니다. - -> [!CAUTION] -> `--yolo`는 전체 자동 권한(`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`)을 활성화합니다. Codespace나 VM 같은 격리된 환경에서만 사용하고, 일상적인 개발을 위한 기본 별칭으로는 절대 설정하지 않습니다. 자세한 내용은 [Allowing and denying tool use][allow-all-warning]를 참고합니다. - -[allow-all-warning]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools -1. Copilot CLI 프롬프트 창에서 다음 명령을 보냅니다. - - ``` - /share gist - ``` - -2. 잠시 후 Copilot이 gist를 만들고 링크를 표시합니다. -3. 링크 텍스트를 복사합니다. -4. 새 브라우저 탭에 링크를 붙여 넣어 gist를 살펴봅니다. gist에 전송된 프롬프트, 사용한 스킬과 agent, Copilot의 사고 과정, 로컬에서 실행한 명령의 코드와 결과까지 강조되어 있는 점을 확인합니다. - -`/share`가 생성하는 gist와 markdown 파일은 코드가 어떻게 생성되었는지 문서화하거나, 원하는 결과를 얻기 위해 Copilot으로 어떤 작업을 수행했는지 팀과 공유하는 용도로 사용할 수 있습니다. - -## Copilot CLI의 컨텍스트 살펴보기 - -더 크거나 복잡한 작업을 수행할 때는 모델의 최대 context window에 도달할 수 있습니다. 창의 정확한 크기는 사용 중인 모델과 Copilot CLI 버전에 따라 달라집니다. Context window가 가득 차면 Copilot CLI는 이를 자동으로 compact하여 정보를 요약하고 현재 작업과 관련이 없다고 판단한 항목을 제거합니다. Slash commands를 사용하면 현재 컨텍스트 상태를 확인할 수도 있고 수동으로 compact할 수도 있습니다. 이제 context window를 살펴보겠습니다. - -1. Copilot CLI 프롬프트 창에서 다음 명령을 보냅니다. - - ``` - /context - ``` - -2. 잠시 후 Copilot CLI가 현재 컨텍스트를 시각적으로 표현한 결과를 생성합니다. - - ![Copilot CLI의 context window 화면](../../../_images/cli-7-context-window.png) - -3. 표시된 모델(이미지와 다를 수 있음)과 현재 사용된 token 비율을 확인합니다. 나머지 정보는 다음을 보여 줍니다. - - | 제목 | 설명 | - | ------------ | ------------------------------------------------------ | - | System/Tools | 지침 파일, 파일 내용, 도구 정의 | - | Messages | 사용자와 Copilot 간의 대화 기록 | - | Buffer | 응답 생성을 위해 Copilot CLI가 예약한 공간 | - | Free space | 남아 있는 여유 공간 | - -4. 다음 slash command를 Copilot CLI에 보내 대화 기록을 compact합니다. - - ``` - /compact - ``` - -5. 완료되면 다음 명령을 보내 현재 컨텍스트 통계를 다시 표시합니다. - - ``` - /context - ``` - -6. 컨텍스트 변화에 주목합니다. 현재 context window가 상대적으로 작을 가능성이 높으므로 큰 차이가 없을 수도 있습니다. - -> [!NOTE] -> Copilot CLI는 컨텍스트가 가득 차면 자동으로 compact를 수행합니다. 용량이 100%에 가까워지면 프롬프트 창 바로 위에 비율을 표시합니다. 일반적으로는 비동기적으로 compact를 수행하므로, 작업 중에도 계속 Copilot과 상호 작용할 수 있습니다. 다만 작업을 수행하는 동안 몇 초간 실행 중인 작업을 차단할 수도 있습니다. - -### 컨텍스트 사용 모범 사례 - -대부분의 세션에서는 Copilot이 별도 지시 없이도 컨텍스트를 효율적으로 관리합니다. 하지만 다음과 같이 히스토리를 직접 지우거나 compact하도록 지시하고 싶어지는 상황도 있을 수 있습니다. - -- 애플리케이션의 다른 부분이나 관련 없는 작업으로 전환하는 경우, 오래되고 관련 없는 컨텍스트가 Copilot을 혼란스럽게 하지 않도록 `/clear`를 사용해 새로 시작할 수 있습니다. -- 최대 context window에 가까워지고 있다면 `/compact`로 수동으로 컨텍스트를 정리해 시점을 직접 제어할 수 있습니다. - -> [!CAUTION] -> 다시 말해 대부분의 시간에는 Copilot이 직접 컨텍스트를 관리합니다. 오래된 정보 때문에 Copilot이 약간 혼란스러워 보이거나 관련 없는 작업으로 전환하려는 경우에만 수동 명령 사용을 고려합니다. - -## 모델 선택하기 - -모델마다 강점이 다르고, 개발자마다 선호도도 다릅니다. Copilot CLI는 사용 가능한 모델을 나열하고 원하는 모델을 선택할 수 있게 해줍니다. - -1. Copilot CLI에 다음 slash command를 보내 모델 목록을 표시합니다. - - ``` - /model - ``` - -2. 모델 목록을 확인합니다. 각 모델 옆에는 이름과 요청당 비용 modifier가 함께 표시됩니다. -3. 원한다면 새 모델을 선택합니다. 아니면 Esc를 선택해 모델 목록을 종료합니다. - -> [!CAUTION] -> Copilot CLI의 모델 선택은 유지됩니다. - -## Cloud agent에 위임하기(선택 사항) - -터미널에서 계속 작업하고 싶지만 더 오래 걸리는 작업은 Copilot cloud agent에 넘기고 싶을 때가 있습니다. `/delegate` 명령은 현재 Copilot CLI 세션을 GitHub.com으로 보내고, cloud agent가 이를 받아 비동기적으로 작업한 뒤 완료되면 pull request를 엽니다. - -> [!NOTE] -> `/delegate`에는 cloud agent가 필요합니다. Copilot Student, Pro, Pro+, Business, Enterprise에서 사용할 수 있으며, Copilot Free에서는 사용할 수 없습니다. 액세스 권한이 없다면 이 섹션을 읽고 실습 단계는 건너뜁니다. - -1. 워크숍에서 누적된 컨텍스트가 함께 위임되지 않도록 먼저 현재 세션을 지웁니다. - - ``` - /clear - ``` - -2. 범위가 작고 명확한 프롬프트를 보냅니다. 예를 들어 백로그에 있는 pagination stretch goal을 위임할 수 있습니다. - - ``` - Implement pagination on the game list page so it shows a fixed number of games per page with Previous and Next controls, and add tests. - ``` - -3. 다음 slash command를 보내 세션을 cloud agent에 넘기고, 위임할 프롬프트를 확인합니다. - - ``` - /delegate - ``` - -4. 브라우저에서 [Copilot agents](https://github.com/copilot/agents)를 열어 진행 상황을 모니터링합니다. -5. 이 harness에서는 pull request가 완료될 때까지 기다릴 필요는 없습니다. 나중에 다시 돌아와도 됩니다. 비동기 agent 작업 관리 방법을 더 깊이 알아보고 싶다면 [Cloud agent harness](../../cloud/)를 계속 진행합니다. - -## 요약 및 다음 단계 - -Copilot CLI의 slash commands를 사용하면 구성을 변경하고, 세션을 공유하고, Copilot이 내부적으로 어떻게 동작하는지에 대한 정보를 얻을 수 있습니다. 이 연습에서는 다음을 사용하거나 살펴보았습니다. - -- `/share`로 세션을 팀과 공유할 GitHub gist를 만들었습니다. -- `/context`로 Copilot CLI가 현재 사용 중인 컨텍스트를 확인했습니다. -- `/model`로 사용 가능한 모델 목록을 살펴보고 원한다면 새 모델을 선택할 수 있음을 확인했습니다. -- `/delegate`를 cloud agent로 연결하는 선택적 브리지로 학습했습니다. - -물론 더 많은 slash commands가 있으며, Copilot CLI로 탐색할 내용도 더 많습니다. 마지막으로 [학습한 내용을 검토하고][next-lesson] 학습을 계속하기 위한 다음 단계를 살펴보며 여정을 마무리하겠습니다. 마무리하기 전에 선택 과제에 도전하고 싶다면, 3개 모듈로 구성된 시리즈에서 [GitHub Copilot CLI와 Foundry로 컨시어지 빌드하기][foundry-lesson]를 진행할 수 있습니다. - -## 리소스 - -- [Copilot CLI 사용하기][using-copilot-cli] -- [Copilot CLI 소개][about-copilot-cli] -- [Copilot CLI의 컨텍스트 관리][context-management] -- [Copilot CLI로 세션 공유하기][share-sessions] -- [Copilot CLI에서 모델 선택하기][selecting-models] - -[previous-lesson]: ../6-custom-agents/ -[next-lesson]: ../9-review/ -[foundry-lesson]: ../8-foundry-agent/ -[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli -[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli -[about-cloud-agent]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent -[context-management]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#context-management -[share-sessions]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#share-sessions -[selecting-models]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#select-an-llm diff --git a/docs/ko-kr/real-world-development/cli/8-create-pull-request.md b/docs/ko-kr/real-world-development/cli/8-create-pull-request.md new file mode 100644 index 00000000..49a1b852 --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/8-create-pull-request.md @@ -0,0 +1,65 @@ +--- +title: "레슨 8 - 기능 PR 만들고 병합하기" +description: "필터링, 지침, 스킬 업데이트, QA 프로필, 테스트를 함께 검토한 뒤 PR을 만들고 Agent Merge를 사용합니다." +authors: + - geektrainer +lastUpdated: 2026-09-18 +--- + +필터링 구현, 지침 업데이트, 스킬 업데이트, 품질 보증(QA) 프로필, 테스트가 모두 하나의 브랜치에 저장되어 있습니다. 이제 함께 검토하고 풀 리퀘스트를 엽니다. 별점 PR은 직접 병합했지만, 이번에는 **Agent Merge**가 나머지 절차를 관리하도록 합니다. + +> [!NOTE] +> 일반적으로 기능, 지침 업데이트, 스킬 업데이트, QA 에이전트는 각각 별도의 PR로 나눕니다. 워크숍을 간소화하기 위해 필터링과 품질 작업 전체를 하나의 대화와 브랜치에서 진행하고 PR 하나에 포함했습니다. + +이 레슨에서는 다음을 수행합니다. + +- Agent Merge와 PR 병합 수명 주기 자동화 방식을 살펴봅니다. +- 기능 변경 사항 전체와 검증 근거를 확인합니다. +- 필터링 PR을 만듭니다. +- 검토를 마친 뒤 Agent Merge를 활성화하고 PR 병합을 확인합니다. + +## 시나리오 + +필터링 작업을 진행하면서 Copilot으로 기능을 계획하고 구현하고 검증했습니다. 이제 Tailspin Toys는 나머지 PR 작업을 자동화하면서 개발자가 병합을 승인하도록 하려고 합니다. + +## Agent Merge 소개 + +**Agent Merge**는 풀 리퀘스트 병합에 필요한 나머지 작업을 자동화합니다. 활성화하면 Copilot이 PR을 막고 있는 작업을 처리합니다. 실패한 지속적 통합(CI) 검사를 수정하고 검토 댓글에 응답하고 필요한 경우 리베이스한 뒤 리포지토리에서 허용하면 GitHub 자동 병합을 활성화합니다. + +지금까지는 사용자가 직접 **Merge pull request**를 선택했습니다. Agent Merge에 이 책임을 맡길 수 있습니다. 활성화하기 전에 변경 사항을 검토하고 병합할 준비가 되었는지 판단합니다. + +## Agent Merge로 PR 관리하기 + +코드를 모두 작성했으니 함께 검토하고 PR을 만든 뒤 Agent Merge가 나머지 절차를 관리하도록 합니다. + +1. Codespace로 돌아갑니다. +2. `/agent`를 입력해 에이전트 대화 상자를 엽니다. +3. 목록에서 **Default**를 선택하고 Enter를 누릅니다. +4. `/pr create` 명령으로 새 PR을 만듭니다. +5. `/pr agentmerge`를 입력해 Agent Merge를 활성화합니다. +6. Copilot이 PR에서 지속적 통합을 모니터링합니다. 모든 검사가 성공하면 병합을 수행합니다. +7. Copilot이 `"PR #14 was squash-merged successfully."`와 비슷한 메시지를 표시하는지 확인합니다. + +> [!IMPORTANT] +> Agent Merge는 필수 승인, 브랜치 보호, 병합 대기열, 리포지토리 설정, 권한 부족을 우회하지 않습니다. 차단되면 보고된 이유를 읽고 리포지토리에서 허용하는 경우 검토한 뒤 직접 병합합니다. + +## 요약 및 다음 단계 + +코드 생성, 코드 테스트 및 검증, 풀 리퀘스트 관리까지 여러 개발 작업을 자동화했습니다. 이 레슨에서는 다음을 수행했습니다. + +- Agent Merge와 PR 병합 수명 주기 자동화 방식을 살펴봤습니다. +- 기능 변경 사항 전체와 검증 근거를 확인했습니다. +- 필터링 PR을 만들었습니다. +- 검토 후 Agent Merge를 활성화하고 PR 병합을 확인했습니다. + +다음으로 [유용한 Copilot CLI 슬래시 명령][next-lesson]을 살펴보고 컨텍스트, 모델, 공유, cloud agent에 선택적으로 위임하는 방법을 알아봅니다. + +## 리소스 + +- [Copilot CLI로 풀 리퀘스트 관리][manage-prs] +- [Copilot CLI 명령 참조][cli-reference] + +[previous-lesson]: ../7-qa-agent/ +[next-lesson]: ../9-cli-power-tools/ +[manage-prs]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests +[cli-reference]: https://docs.github.com/copilot/reference/copilot-cli-reference/cli-command-reference diff --git a/docs/ko-kr/real-world-development/cli/8-foundry-agent/2-build-and-deploy.md b/docs/ko-kr/real-world-development/cli/8-foundry-agent/2-build-and-deploy.md index a2427931..9b622ff9 100644 --- a/docs/ko-kr/real-world-development/cli/8-foundry-agent/2-build-and-deploy.md +++ b/docs/ko-kr/real-world-development/cli/8-foundry-agent/2-build-and-deploy.md @@ -22,7 +22,7 @@ Tailspin Toys에는 모델의 일회성 답변 이상이 필요합니다. 후원 이 모듈은 모듈 1에서 정상적으로 작동한 모델을 기반으로 진행합니다. Azure 리소스를 새로 만들지 않고 동일한 프로젝트와 배포를 유지합니다. -1. Tailspin Toys 리포지토리의 `foundry-agent-cli` 브랜치와 모듈 1에서 사용한 Copilot CLI 세션으로 돌아갑니다. +1. Codespace로 돌아간 다음 `foundry-agent-cli` 브랜치의 Tailspin Toys 리포지토리와 모듈 1에서 사용한 Copilot CLI 세션을 엽니다. 2. `db/catalog.json`이 있는지, 모델 테스트에 사용한 Foundry 프로젝트, 선택한 모델 배포, Azure 로그인이 그대로 유지되어 있는지 확인합니다. 설정을 완료하지 않았다면 먼저 [프로젝트와 모델 준비하기][previous-lesson]를 마칩니다. > [!IMPORTANT] diff --git a/docs/ko-kr/real-world-development/cli/8-foundry-agent/3-connect-to-site.md b/docs/ko-kr/real-world-development/cli/8-foundry-agent/3-connect-to-site.md index cb8dbee3..b3d23a19 100644 --- a/docs/ko-kr/real-world-development/cli/8-foundry-agent/3-connect-to-site.md +++ b/docs/ko-kr/real-world-development/cli/8-foundry-agent/3-connect-to-site.md @@ -23,7 +23,7 @@ next: false 웹사이트 통합에는 모듈 2에서 배포한 에이전트가 필요합니다. 프록시와 웹사이트는 로컬에서 실행하고, 에이전트는 Foundry에서 계속 실행 상태로 유지합니다. -1. Tailspin Toys 리포지토리의 `foundry-agent-cli` 브랜치와 기존 Copilot CLI 세션으로 돌아갑니다. +1. Codespace로 돌아간 다음 `foundry-agent-cli` 브랜치의 Tailspin Toys 리포지토리와 기존 Copilot CLI 세션을 엽니다. 2. Backer Concierge가 배포되어 있고 [에이전트 빌드 및 배포하기][previous-lesson]의 원격 호출이 성공했는지 확인합니다. Azure 리소스를 이미 제거했다면 계속 진행하기 전에 이전 모듈을 따라 다시 만듭니다. > [!IMPORTANT] @@ -67,7 +67,7 @@ Tailspin Toys는 전체를 사전 렌더링합니다. 브라우저 코드는 호 ``` 2. 로컬 Function을 실행 상태로 유지한 채 다른 터미널에서 Copilot이 제공한 명령으로 Astro 사이트를 시작합니다. -3. Copilot CLI로 돌아갑니다. [연습 4][playwright-lesson]에서 추가한 Playwright MCP 서버를 이미 사용할 수 있습니다. Copilot에 위젯 테스트를 요청합니다. +3. Copilot CLI로 돌아갑니다. [레슨 6][playwright-lesson]에서 살펴보거나 추가한 Playwright MCP 서버를 이미 사용할 수 있습니다. Copilot에 위젯 테스트를 요청합니다. ```text Use the Playwright MCP server to test the Backer Concierge widget end to end in the running Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. @@ -87,10 +87,10 @@ Tailspin Toys는 전체를 사전 렌더링합니다. 브라우저 코드는 호 로컬 서버 측 프록시와 접근성을 갖춘 채팅 위젯을 통해 호스트된 Backer Concierge를 Tailspin Toys에 연결했습니다. 시리즈 전반에서 GitHub Copilot CLI와 Foundry를 사용해 모델을 준비하고, 에이전트를 빌드 및 배포한 뒤 완전한 웹사이트 통합을 검증했습니다. -CLI 워크숍을 마무리하려면 [검토 및 다음 단계][review]로 이동합니다. +CLI 워크숍을 마무리하려면 [마무리 및 다음 단계][review]로 이동합니다. [overview]: ../ [previous-lesson]: ../2-build-and-deploy/ -[review]: ../../9-review/ -[playwright-lesson]: ../../4-mcp/ +[review]: ../../10-review/ +[playwright-lesson]: ../../6-mcp-playwright/ [cleanup]: ../#리소스-정리하기 diff --git a/docs/ko-kr/real-world-development/cli/8-foundry-agent/README.md b/docs/ko-kr/real-world-development/cli/8-foundry-agent/README.md index 330e65df..fa7c7b8e 100644 --- a/docs/ko-kr/real-world-development/cli/8-foundry-agent/README.md +++ b/docs/ko-kr/real-world-development/cli/8-foundry-agent/README.md @@ -39,7 +39,7 @@ Tailspin Toys는 후원자가 대화를 통해 게임을 찾도록 돕는 **Back > 이 시리즈에서는 모델 배포와 호스트된 에이전트를 비롯해 요금이 부과되는 Azure 리소스를 만듭니다. 리소스를 만들기 전에 선택한 구독, 지역, 할당량, 예상 비용을 검토해야 합니다. 첫 번째 또는 두 번째 모듈을 마친 뒤 중단하더라도 [정리 지침][cleanup]을 따라야 합니다. 1. 선택 사항 시리즈를 시작하려면 [프로젝트와 모델 준비하기][project-model]로 이동합니다. 설정 지침도 해당 모듈에 포함되어 있습니다. -2. 핵심 워크숍을 마무리하고 싶다면 [검토 및 다음 단계][review]로 이동합니다. +2. 핵심 워크숍을 마무리하고 싶다면 [마무리 및 다음 단계][review]로 이동합니다. ## 리소스 정리하기 @@ -74,7 +74,7 @@ Tailspin Toys는 후원자가 대화를 통해 게임을 찾도록 돕는 **Back [project-model]: 1-project-and-model/ [build-deploy]: 2-build-and-deploy/ [connect-site]: 3-connect-to-site/ -[review]: ../9-review/ +[review]: ../10-review/ [cleanup]: #리소스-정리하기 [azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli [foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli diff --git a/docs/ko-kr/real-world-development/cli/9-cli-power-tools.md b/docs/ko-kr/real-world-development/cli/9-cli-power-tools.md new file mode 100644 index 00000000..a544804c --- /dev/null +++ b/docs/ko-kr/real-world-development/cli/9-cli-power-tools.md @@ -0,0 +1,100 @@ +--- +title: "레슨 9 - GitHub Copilot CLI의 슬래시 명령" +description: "컨텍스트 관리, 모델 선택, 세션 공유, cloud agent에 선택적으로 위임하는 슬래시 명령을 살펴봅니다." +authors: + - geektrainer +lastUpdated: 2026-09-18 +--- + +다른 CLI 도구와 마찬가지로 GitHub Copilot CLI에도 다양한 슬래시 명령이 있습니다. 이 명령으로 고급 기능, 내부 정보, 추가 구성 옵션을 사용할 수 있습니다. `/diff`, `/mcp`, `/skills`, `/agent`, `/pr` 등을 이미 사용했습니다. 이제 몇 가지 유용한 명령을 살펴봅니다. + +이 레슨에서는 다음을 수행합니다. + +- `/context`와 `/compact`로 Copilot이 대화 컨텍스트를 관리하는 방식을 살펴봅니다. +- `/model`로 사용할 수 있는 모델을 확인합니다. +- `/share`로 세션을 내보내거나 공유하는 방법을 알아봅니다. +- 병렬 작업, 워크트리, cloud agent 위임을 위한 선택적 명령을 살펴봅니다. + +## 시나리오 + +CLI 핵심 작업 흐름을 마쳤습니다. 이제 컨텍스트 관리, 모델 전환, 세션 공유, [Copilot cloud agent][about-cloud-agent]에 선택적으로 위임하는 방법 등 추가 기능을 살펴봅니다. + +## Copilot CLI 컨텍스트 살펴보기 + +크거나 복잡한 작업을 수행하면 모델의 최대 컨텍스트 창에 도달할 수 있습니다. Copilot CLI는 필요할 때 대화를 자동으로 압축하며, 슬래시 명령을 사용해 직접 확인하거나 압축할 수도 있습니다. + +1. Codespace로 돌아갑니다. Copilot CLI가 열려 있지 않다면 리포지토리 루트에서 시작합니다. +2. 다음을 입력합니다. + + ```plaintext + /context + ``` + +3. 모델, 현재 토큰 사용량, 시스템 지침, 도구, 메시지, 사용 가능한 공간에 컨텍스트가 어떻게 나뉘는지 살펴봅니다. +4. 대화를 압축합니다. + + ```plaintext + /compact + ``` + +5. 다시 `/context`를 입력해 결과를 비교합니다. 대화가 이미 짧다면 큰 차이가 없을 수 있습니다. + +> [!NOTE] +> 컨텍스트 창이 가득 차면 Copilot CLI가 자동으로 컨텍스트를 압축합니다. `/compact`를 사용하면 압축 시점을 직접 정할 수 있습니다. 관련 없는 작업으로 전환하면서 새 대화를 시작하려면 `/clear` 또는 `/new`를 사용합니다. + +## 모델 선택하기 + +모델마다 강점이 다르고 개발자마다 선호하는 모델이 다릅니다. Copilot CLI에서 사용할 수 있는 모델을 살펴보고 원하는 모델을 선택할 수 있습니다. + +1. 다음을 입력합니다. + + ```plaintext + /model + ``` + +2. 사용 가능한 모델과 사용 정보를 살펴봅니다. +3. 현재 모델을 유지하거나 다른 모델을 선택합니다. 목록을 닫으려면 Esc를 누릅니다. + +## 세션 공유하기 + +팀으로 협업하고 배운 내용을 공유하면 모두가 AI 도구를 더 잘 사용할 수 있습니다. `/share` 명령으로 세션을 Markdown 또는 HTML 파일로 내보내고 공유 가능한 링크를 만들거나 GitHub gist에 게시할 수 있습니다. + +1. `/help`를 입력하고 설치된 버전의 `/share` 옵션을 살펴봅니다. +2. 세션을 공유하려면 필요에 맞는 대상을 선택합니다. 예를 들어 `/share file`은 Markdown 파일을 로컬에 내보냅니다. +3. 내보낸 내용을 다른 사람에게 보내거나 게시하기 전에 검토합니다. 세션 내보내기 파일에 프롬프트, 응답, 프로젝트 세부 정보가 포함될 수 있습니다. + +링크나 gist를 게시하는 것은 선택 사항입니다. 팀에서 공유하지 않기로 한 리포지토리 또는 대화 내용을 게시하지 않습니다. + +## 선택 사항: 병렬 작업 또는 위임하기 + +핵심 워크숍을 마쳤습니다. Copilot CLI에는 더 큰 작업을 위한 명령도 있습니다. + +- `/fleet`은 서로 독립적인 하위 작업을 하위 에이전트에 나눠 병렬로 실행할 수 있습니다. +- `/worktree`는 별도 작업을 위한 격리된 Git 워크트리를 만들 수 있습니다. +- `/delegate`는 비동기적으로 작업하고 풀 리퀘스트를 열 수 있는 Copilot cloud agent에 작업을 보낼 수 있습니다. + +이 명령을 사용하면 워크트리나 원격 작업이 추가될 수 있으므로 선택 사항입니다. 사용해 보려면 범위가 명확한 새 작업에서 시작하고 일반적인 워크플로에 따라 결과를 검토합니다. 비동기 에이전트 작업을 더 자세히 알아보려면 [cloud agent 워크숍][cloud-workshop]을 진행합니다. + +## 요약 및 다음 단계 + +Copilot CLI의 슬래시 명령을 사용해 도구를 구성하고 세션을 공유하고 내부 상태를 확인했습니다. 이 레슨에서는 다음을 수행했습니다. + +- `/context`와 `/compact`로 Copilot이 대화 컨텍스트를 관리하는 방식을 살펴봤습니다. +- `/model`로 사용할 수 있는 모델을 확인했습니다. +- `/share`로 세션을 내보내거나 공유하는 방법을 알아봤습니다. +- 병렬 작업, 워크트리, cloud agent에 선택적으로 위임하는 방법을 살펴봤습니다. + +Copilot CLI에서 사용할 수 있는 명령과 기능은 더 많습니다. 다음으로 [지금까지 배운 내용과 다음 단계][next-lesson]를 검토합니다. + +## 리소스 + +- [Copilot CLI 명령 참조][cli-reference] +- [Copilot CLI의 컨텍스트 관리][context-management] +- [Copilot cloud agent 정보][about-cloud-agent] + +[previous-lesson]: ../8-create-pull-request/ +[next-lesson]: ../10-review/ +[cli-reference]: https://docs.github.com/copilot/reference/copilot-cli-reference/cli-command-reference +[context-management]: https://docs.github.com/copilot/concepts/agents/copilot-cli/context-management +[about-cloud-agent]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[cloud-workshop]: ../../cloud/ diff --git a/docs/ko-kr/real-world-development/cli/9-review.md b/docs/ko-kr/real-world-development/cli/9-review.md deleted file mode 100644 index 41e3cce6..00000000 --- a/docs/ko-kr/real-world-development/cli/9-review.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "연습 9 - 검토 및 다음 단계" -authors: - - geektrainer -lastUpdated: 2026-06-30 ---- - -지난 여러 연습에서 다음을 포함해 GitHub Copilot CLI의 가장 일반적인 사용 사례를 살펴보았습니다. - -- GitHub 및 다른 MCP server와 상호 작용하기 -- 지침 파일을 사용해 코드 생성을 안내하기 -- 스킬을 구현해 Copilot CLI 도구 상자에 새 도구를 추가하기 -- 고급 작업과 더 복잡한 작업을 위해 커스텀 agent 호출하기 -- Slash commands를 사용해 세션을 관리하고, 선택적으로 `/delegate`를 통해 cloud agent로 다시 연결하기 - -선택 과제에 도전하고 싶다면, 모델 설정, 에이전트 개발 및 배포, 웹사이트 통합을 다루는 3개 모듈 시리즈에서 [GitHub Copilot CLI와 Foundry로 컨시어지 빌드하기][foundry-lesson]를 진행할 수 있습니다. - -이제 몇 가지 slash commands, 모범 사례, 다음 단계를 정리해 보겠습니다. - -## 슬래시 명령 - -Copilot CLI에는 이를 제어하거나 내부에서 무슨 일이 일어나고 있는지 확인할 수 있는 다양한 slash commands가 있습니다. 이미 현재 컨텍스트를 지우고 새 채팅을 시작하는 `/clear`, MCP server를 검사하고 관리하는 `/mcp`를 사용해 보았습니다. 추가로 유용할 수 있는 명령은 다음과 같습니다. - -| 명령 | 설명 | -| ------------------ | ------------------------------------------------------------- | -| `/add-dir` | Copilot의 신뢰 목록에 디렉터리를 추가합니다 | -| `/clear`, `/new` | 대화 기록을 지우고 새로 시작합니다 | -| `/compact` | 컨텍스트 창 사용량을 줄이기 위해 대화 기록을 요약합니다 | -| `/context` | 컨텍스트 창 token 사용량과 시각화를 보여 줍니다 | -| `/diff` | 현재 디렉터리에서 이루어진 변경 사항을 검토합니다 | -| `/model` | 사용할 AI 모델을 선택합니다(Claude Sonnet, GPT-5 등) | -| `/plan ` | 코딩 전에 구현 계획을 만듭니다 | -| `/review ` | 변경 사항을 분석하도록 코드 리뷰 agent를 실행합니다 | -| `/delegate` | 비동기 처리를 위해 작업을 Copilot cloud agent에 위임합니다 | -| `/session` | 세션 정보와 작업 공간 요약을 보여 줍니다 | -| `/share` | 세션을 markdown 파일 또는 GitHub gist로 공유합니다 | -| `/skills` | 향상된 기능을 위한 스킬을 관리합니다 | -| `/usage` | 세션 사용량 지표와 통계를 표시합니다 | - -> [!TIP] -> `/help`를 사용하면 전체 명령 목록과 keyboard shortcuts를 확인할 수 있습니다. - -## 모범 사례 - -어떤 AI 도구를 사용하든, 그 결과물의 품질은 기반 인프라에 크게 좌우됩니다. 강력한 지침 파일, 커스텀 에이전트, 에이전트 스킬은 모두 중요한 역할을 하며, 이 워크숍에서 각각을 살펴보았습니다. [Awesome-copilot][awesome-copilot]은 템플릿을 찾기에 좋은 자료이며, Copilot 자체도 시작점을 마련할 수 있도록 이러한 요소를 스캐폴드해 줄 수 있습니다. - -인프라만큼이나 컨텍스트도 중요합니다. *무엇을* 만들고 싶은지, *왜* 필요한지, *어떻게* 만들고 싶은지를 명확하게 설명하면 결과가 크게 달라집니다. Copilot에 도움이 될 만한 정보라면 반드시 전달합니다. - -## 다음 단계 - -도구 사용 능력을 향상하는 가장 좋은 방법은 계속 사용하는 것입니다. 운영 코드에도, 취미 프로젝트에도, 오랫동안 마음속에 있었지만 아직 만들지 못한 작은 앱에도 사용해 봅니다. 학습한 내용을 팀과 공유하고, 팀으로부터도 배웁니다. 그리고 늘 그렇듯 문서를 계속 탐색합니다. - -GitHub Copilot 생태계를 더 살펴보고 싶다면 [VS Code harness](../../vscode/) 또는 [Cloud agent harness](../../cloud/)를 확인합니다. - -## 리소스 - -- [Copilot CLI 소개][about-copilot-cli] -- [Copilot CLI 사용하기][using-copilot-cli] -- [Awesome Copilot 리포지토리][awesome-copilot] -- [커스텀 지침 가이드][repo-instructions] -- [에이전트 스킬 문서][agent-skills] -- [커스텀 에이전트 문서][custom-agents] -- [MCP 사양][mcp-spec] - -[previous-lesson]: ../7-slash-commands/ -[foundry-lesson]: ../8-foundry-agent/ -[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli -[using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli -[awesome-copilot]: https://github.com/github/awesome-copilot -[repo-instructions]: https://docs.github.com/copilot/how-tos/configure-custom-instructions/add-repository-instructions -[agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills -[custom-agents]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents -[mcp-spec]: https://modelcontextprotocol.io/ diff --git a/docs/ko-kr/real-world-development/cli/README.md b/docs/ko-kr/real-world-development/cli/README.md index 198ff574..ab713c75 100644 --- a/docs/ko-kr/real-world-development/cli/README.md +++ b/docs/ko-kr/real-world-development/cli/README.md @@ -1,57 +1,74 @@ --- slug: ko-kr/real-world-development/cli title: "GitHub Copilot CLI" +description: "Copilot CLI 모드와 사용자 지정 기능, MCP 도구, 풀 리퀘스트 자동화를 살펴보며 Tailspin Toys의 변경 사항 두 가지를 빌드하고 검증하고 전달합니다." authors: - geektrainer -lastUpdated: 2026-06-30 +lastUpdated: 2026-09-18 --- -[**GitHub Copilot CLI**](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)는 터미널에서 GitHub Copilot을 에이전트형 코딩 도우미로 사용할 수 있게 해줍니다. 코드베이스를 탐색하고, 코드를 생성하고, 명령을 실행하고, 외부 도구에 연결하는 작업을 모두 명령줄에서 처리하므로 그래픽 편집기로 전환하지 않고도 작업 흐름을 유지할 수 있습니다. +**[GitHub Copilot CLI][about-copilot-cli]**는 에이전트형 코딩 도우미인 GitHub Copilot을 터미널에서 사용할 수 있게 합니다. 코드베이스를 살펴보고 코드를 생성하고 명령을 실행하며 외부 도구에 연결하는 작업을 명령줄에서 처리하므로 그래픽 편집기로 전환하지 않고 작업 흐름을 이어 갈 수 있습니다. -이 연습 전체에서 Copilot CLI를 설치하고 인증한 다음, 커스텀 지침으로 프로젝트 컨텍스트를 제공한 뒤 plan mode를 사용해 의도적으로 기능을 생성합니다. 이어서 Playwright MCP server를 연결해 실제 브라우저에서 해당 기능을 테스트하고, 재사용 가능한 agent skills와 custom agents로 Copilot을 확장합니다. 마지막으로 slash commands로 컨텍스트, 모델, 공유를 관리하는 방법을 살펴보고, 완성한 내용을 검토합니다. 또한 선택 사항으로, [GitHub Copilot CLI와 Foundry를 사용하는 3개 모듈 시리즈][foundry]에서 모델을 준비하고, 호스트된 에이전트를 빌드 및 배포한 뒤 사이트에 통합할 수 있습니다. +이 워크숍은 하나로 이어지는 Tailspin Toys 작업 흐름을 따라갑니다. -## 연습 +1. GitHub Codespaces에서 프로젝트를 준비하고 Copilot CLI를 설치한 뒤 기본 사용법을 익힙니다. +2. 게임 카드에 별점을 추가하고 브라우저에서 결과를 검토한 뒤 첫 풀 리퀘스트(PR)를 직접 병합합니다. +3. 필터링 이슈에서 시작해 Plan 모드에서 접근 방식을 정하고 Autopilot 모드로 구현한 뒤 Interactive 모드에서 검토합니다. +4. 리포지토리 지침을 업데이트하고 필터링 작업에 적용합니다. +5. 기존 `quality-checks` 스킬을 사용자 지정하고 프로젝트 검사를 실행합니다. +6. Playwright Model Context Protocol(MCP) 서버를 추가하고 브라우저에서 필터링 동작을 살펴봅니다. +7. 품질 보증(QA) 사용자 지정 에이전트를 만들어 요구 사항, 테스트 범위, 검증 근거를 검토합니다. +8. 필터링 변경 사항 전체를 검토하고 Agent Merge로 필터링 PR을 관리합니다. +9. 컨텍스트, 모델, 공유, cloud agent에 선택적으로 위임하는 방법을 비롯해 유용한 슬래시 명령을 살펴봅니다. -| 연습 | 주제 | 설명 | -|----------|-------|-------------| -| [0. 사전 준비][ex0] | 설정 | 리포지토리(Repository)와 코드스페이스(Codespace)를 만듭니다 | -| [1. Copilot CLI 설치][ex1] | 설치 | Copilot CLI를 설치하고 인증합니다 | -| [2. 커스텀 지침][ex2] | 컨텍스트 | 지침을 추가하고 Copilot CLI가 이를 따르는 모습을 확인합니다 | -| [3. 코드 생성][ex3] | 코드 생성 | plan mode를 사용해 기능을 생성합니다 | -| [4. Playwright MCP로 테스트][ex4] | 외부 도구 | Playwright MCP server를 추가하고 브라우저에서 기능을 테스트합니다 | -| [5. 에이전트 스킬][ex5] | 스킬 | 특화된 스킬로 Copilot을 강화합니다 | -| [6. 커스텀 에이전트][ex6] | 에이전트 | 커스텀 에이전트를 검토하고 사용합니다 | -| [7. 슬래시 명령][ex7] | CLI 기능 | 컨텍스트, 모델, 공유, 그리고 선택적으로 cloud agent 위임을 살펴봅니다 | -| [9. 검토][ex9] | 요약 | 핵심 개념과 다음 단계를 검토합니다 | -| [선택 사항: Foundry 통합하기][foundry] | 호스트된 에이전트 | 모델을 준비하고, 카탈로그 기반 Backer Concierge를 빌드 및 배포한 뒤 웹사이트에 연결합니다 | +워크숍에 집중할 수 있도록 PR 두 개를 만듭니다. 첫 번째는 별점 변경이며, 두 번째는 지침 업데이트, 스킬 업데이트, QA 프로필, 테스트를 포함한 필터링 변경입니다. 필터링과 품질 작업은 하나의 대화와 브랜치에서 진행하므로 각 도구를 익히면서 작업을 이어 갈 수 있습니다. + +## 레슨 + +| 레슨 | 주제 | 설명 | +| ------ | ----- | ----------- | +| [0. 사전 준비][ex0] | 설정 | 리포지토리와 Codespace를 준비합니다 | +| [1. Copilot CLI 설치][ex1] | 설치 | Copilot CLI를 설치하고 인증한 뒤 기본 사용법을 익힙니다 | +| [2. 별점 추가: 빠른 성과][ex2] | 첫 변경 | 기존 별점과 값이 없는 경우의 대체 표시를 추가한 뒤 첫 PR을 병합합니다 | +| [3. 에이전트 모드: Plan 및 Autopilot][ex3] | 에이전트 모드 | 이슈에서 기능을 계획하고 Autopilot으로 구현한 뒤 Interactive 모드에서 검토합니다 | +| [4. 사용자 지정 지침으로 Copilot 안내][ex4] | 컨텍스트 | 지침을 살펴보고 업데이트한 뒤 필터링 작업에 적용합니다 | +| [5. quality-checks 스킬 사용자 지정 및 사용][ex5] | 반복 가능한 검사 | 기존 스킬을 살펴보고 결과 보고 형식을 바꾼 뒤 실행합니다 | +| [6. Playwright MCP로 기능 검증][ex6] | 브라우저 확인 | CLI에서 MCP를 구성하고 필터링 동작을 살펴봅니다 | +| [7. QA 에이전트 만들기 및 사용][ex7] | 요구 사항과 테스트 범위 | 전문 프로필을 만들고 선택한 뒤 최종 검증 근거를 수집합니다 | +| [8. 기능 PR 만들기 및 병합][ex8] | 검토 및 병합 | 변경 사항 전체를 검토하고 PR을 만든 뒤 Agent Merge를 사용합니다 | +| [9. GitHub Copilot CLI의 슬래시 명령][ex9] | CLI 기능 | 컨텍스트, 모델, 공유, cloud agent에 선택적으로 위임하는 방법을 살펴봅니다 | +| [10. 마무리 및 다음 단계][ex10] | 요약 | 작업 흐름, 재사용 가능한 사용자 지정 기능, 추가 리소스를 검토합니다 | +| [선택 사항: Foundry 통합][foundry] | 호스트된 에이전트 | 모델을 준비하고 카탈로그에 기반한 에이전트를 배포한 뒤 웹사이트에 연결합니다 | ## 사전 준비 -이 워크숍에 참여하기 전에 다음 사항을 준비합니다. +이 워크숍에 참여하기 전에 다음을 준비합니다. -- [ ] **Copilot Student, Pro, Pro+, Business 또는 Enterprise** 플랜이 활성화된 GitHub 계정 -- [ ] 터미널/명령줄 사용에 대한 기본 이해 -- [ ] 설치 및 구성된 Git +- [ ] 활성 **Copilot Student, Pro, Pro+, Business 또는 Enterprise** 플랜이 있는 GitHub 계정 +- [ ] 리포지토리와 Codespace를 만들 수 있는 권한 +- [ ] 터미널 또는 명령줄 사용에 대한 기본 지식 > [!TIP] -> 유료 플랜이 없나요? 인증된 학생은 [GitHub Education][callout-student-plan-education]을 통해 GitHub Copilot을 무료로 사용할 수 있습니다. **Copilot Student** 플랜에는 이 워크숍에서 사용하는 agent, MCP, code review, Copilot CLI 기능이 모두 포함되어 있으므로 모든 harness를 완료할 수 있습니다. - -[callout-student-plan-education]: https://github.com/education/students +> 유료 플랜이 없습니까? 인증된 학생은 [GitHub Education][student-plan]을 통해 GitHub Copilot을 무료로 사용할 수 있습니다. **Copilot Student** 플랜에는 이 워크숍에서 사용하는 에이전트, MCP, 코드 검토, Copilot CLI 기능이 포함되어 있습니다. > [!NOTE] -> Copilot Business 또는 Copilot Enterprise를 사용하는 경우, 관리자가 Copilot CLI 사용을 활성화했는지 확인합니다. +> Copilot Business 또는 Copilot Enterprise를 사용하는 경우 관리자가 Copilot CLI를 활성화했는지 확인합니다. ## 시작하기 -[**연습 0: 사전 준비부터 시작하기 →**][ex0] +**[사전 준비부터 시작 →][ex0]** +[about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli +[student-plan]: https://github.com/education/students [ex0]: 0-prerequisites/ [ex1]: 1-install-copilot-cli/ -[ex2]: 2-custom-instructions/ -[ex3]: 3-generating-code/ -[ex4]: 4-mcp/ +[ex2]: 2-add-star-rating/ +[ex3]: 3-agent-modes/ +[ex4]: 4-custom-instructions/ [ex5]: 5-agent-skills/ -[ex6]: 6-custom-agents/ -[ex7]: 7-slash-commands/ +[ex6]: 6-mcp-playwright/ +[ex7]: 7-qa-agent/ +[ex8]: 8-create-pull-request/ +[ex9]: 9-cli-power-tools/ +[ex10]: 10-review/ [foundry]: 8-foundry-agent/ -[ex9]: 9-review/ diff --git a/docs/ko-kr/real-world-development/cloud/0-prerequisites.md b/docs/ko-kr/real-world-development/cloud/0-prerequisites.md new file mode 100644 index 00000000..ce4a73a5 --- /dev/null +++ b/docs/ko-kr/real-world-development/cloud/0-prerequisites.md @@ -0,0 +1,68 @@ +--- +title: "연습 0: 사전 준비" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +Copilot cloud agent 연습을 시작하기 전에 필요한 사항을 준비합니다. Tailspin Toys 리포지토리의 복사본을 만들고 [codespace][codespaces]를 시작합니다. 이 환경에서 지침 파일을 편집하고 cloud agent가 만든 결과를 검토합니다. + +## 실습용 리포지토리 설정하기 + +코드를 작성할 리포지토리 복사본을 만들기 위해 [템플릿][template-repository]을 사용합니다. 새 리포지토리에는 실습에 필요한 모든 파일이 포함되며, 연습을 진행하는 동안 사용하게 됩니다. + +1. 새 브라우저 창에서 [Tailspin Toys 템플릿][tailspin-template]으로 이동합니다. +2. 실습 리포지토리 페이지에서 **Use this template**을 선택한 다음 **Create a new repository**를 선택하여 리포지토리 복사본을 만듭니다. + + ![Use this template 버튼](../../../_images/ex0-use-template.png) + +3. GitHub 또는 Microsoft가 진행하는 행사에서 워크숍을 수행하는 경우 멘토의 안내를 따릅니다. 그렇지 않다면 GitHub Copilot을 사용할 수 있는 조직에 새 리포지토리를 만듭니다. + + ![리포지토리 템플릿 설정을 입력하는 화면](../../../_images/ex0-repository-settings.png) + +4. 나중에 참조할 수 있도록 생성한 리포지토리 경로(**organization-or-user-name/repository-name**)를 기록해 둡니다. + +## Codespace 만들기 + +이제 Codespace에서 실습을 진행합니다. + +[GitHub Codespaces][codespaces]는 브라우저에서 코드를 작성하고 실행하고 디버그할 수 있는 클라우드 기반 개발 환경입니다. 여러 프로그래밍 언어, 확장, 도구를 지원하는 완전한 기능의 IDE를 제공합니다. + +1. 방금 만든 리포지토리로 이동합니다. +2. 녹색 **Code** 버튼을 선택합니다. + + ![Code 버튼 선택](../../../_images/ex0-code-button.png) + +3. **Codespaces** 탭을 선택한 다음 **+** 버튼을 선택하여 새 Codespace를 만듭니다. + + ![새 Codespace 만들기](../../../_images/ex0-create-codespace.png) + +Codespace를 만드는 데 몇 분 정도 걸립니다. 그래도 모든 서비스를 수동으로 설치하는 것보다 훨씬 빠릅니다. 기다리는 동안 GitHub Copilot의 다른 기능을 살펴볼 수 있으며, 다음 단계에서 이어서 알아봅니다. + +> [!CAUTION] +> 이후 연습에서 Codespace를 다시 사용합니다. 지금은 브라우저 탭에서 열린 상태로 둡니다. + +> [!NOTE] +> 이 워크숍은 Codespace 또는 로컬 [dev container][dev-containers]에서 실행하도록 구성되어 있습니다. 두 환경 모두 원활하게 진행하는 데 필요한 사전 준비 항목을 제공합니다. 로컬에서 실행하려면 복제한 리포지토리를 VS Code에서 열고 메시지가 표시되면 **Reopen in Container**를 선택합니다. VS Code가 Codespace와 동일한 dev container를 빌드합니다. + +[codespaces]: https://github.com/features/codespaces +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers + +## 요약 + +실습용 리포지토리의 복사본을 만들고 Codespace를 생성하기 시작했습니다. 이 환경에서 Copilot cloud agent와 함께 작업하게 됩니다. + +## 다음 단계 + +cloud agent가 따를 사용자 지정 지침을 추가합니다. [연습 1 - 사용자 지정 지침][next-lesson]을 진행합니다. + +## 리소스 + +- [GitHub Codespaces 개요][codespaces] +- [템플릿에서 리포지토리 만들기][template-repository] +- [Codespaces 시작하기][codespaces-quickstart] + +[tailspin-template]: https://github.com/github-samples/tailspin-toys +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[codespaces-quickstart]: https://docs.github.com/codespaces/getting-started/quickstart +[next-lesson]: ../1-custom-instructions/ diff --git a/docs/ko-kr/real-world-development/cloud/1-custom-instructions.md b/docs/ko-kr/real-world-development/cloud/1-custom-instructions.md new file mode 100644 index 00000000..03410ca6 --- /dev/null +++ b/docs/ko-kr/real-world-development/cloud/1-custom-instructions.md @@ -0,0 +1,152 @@ +--- +title: "연습 1 - 사용자 지정 지침(Cloud agent)" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +[← 이전 레슨: 사전 준비][previous-lesson] · [다음 레슨: Copilot cloud agent →][next-lesson] + +생성형 AI를 사용할 때는 컨텍스트가 중요합니다. 특정 방식으로 작업해야 하거나 Copilot이 알아야 할 배경 정보가 있다면, 해당 컨텍스트를 Copilot이 사용할 수 있도록 해야 합니다. [지침 파일][instruction-files]은 Copilot에 지침을 제공하여 원하는 작업뿐 아니라 작업 방식도 이해하도록 돕습니다. + +이 연습에서는 다음을 수행합니다. + +- 리포지토리 사용자 지정 지침과 경로 범위 지침 파일을 통해 프로젝트 컨텍스트, 코딩 지침, 문서 표준이 Copilot에 전달되는 방식을 살펴봅니다. +- `.github/copilot-instructions.md`에 새로운 리포지토리 전체 표준을 추가합니다. + +> [!NOTE] +> VS Code 및 CLI 과정과 달리 여기서는 전후 결과를 비교하는 프롬프트를 실행하지 않습니다. Copilot cloud agent는 GitHub 이슈를 비동기적으로 처리하므로 실시간으로 나란히 비교하기 어렵습니다. 이 과정의 뒷부분에서 cloud agent가 만든 풀 리퀘스트를 검토할 때 지침 파일의 영향을 확인합니다. + +## 지침 파일 + +### 시나리오 + +Tailspin Toys에는 개발 관행에 관한 표준과 요구 사항이 있습니다. + +- 데이터 계층에는 항상 단위 테스트가 필요합니다. +- UI는 어두운 모드와 현대적인 느낌을 사용해야 합니다. +- 코드에는 TSDoc 문서 주석을 추가해야 합니다. +- 각 파일의 맨 위에는 파일의 역할을 설명하는 주석 블록을 추가해야 합니다. + +지침 파일을 사용해 Copilot이 이러한 관행에 따라 작업하는 데 필요한 정보를 제공합니다. + +### 사용자 지정 지침 + +사용자 지정 지침은 Copilot에 컨텍스트와 선호 사항을 제공하여 코딩 스타일과 요구 사항을 더 잘 이해하도록 합니다. 코딩 규칙, 라이브러리, 포함하려는 주석 유형을 지정할 수 있습니다. 리포지토리 전체 또는 특정 파일 유형과 작업에 적용되는 지침을 만들 수 있습니다. + +지침 파일에는 다음 두 가지 유형이 있습니다. + +- `.github/copilot-instructions.md`는 리포지토리의 **모든** 요청에 Copilot이 사용하는 단일 지침 파일입니다. 대부분의 요청에 공통으로 적용되는 프로젝트 수준의 컨텍스트와 지침을 작성합니다. +- `.github/instructions/*.instructions.md` 파일은 특정 작업이나 파일 유형에 대한 지침을 제공합니다. TypeScript나 Astro 같은 특정 언어 또는 UI 컴포넌트나 단위 테스트 작성과 같은 작업에 대한 지침을 만들 수 있습니다. + +> [!NOTE] +> IDE에서는 지침 파일을 Copilot Chat의 코드 생성에만 사용하며, 코드 완성이나 다음 편집 제안에는 사용하지 않습니다. +> +> Copilot Chat, Copilot CLI, Copilot cloud agent는 코드 생성 시 리포지토리 수준 지침과 `applyTo` frontmatter가 있는 `*.instructions.md` 파일을 함께 사용합니다. +> +> Copilot은 AGENTS.md 및 CLAUDE.md 파일을 비롯한 다른 형식의 지침 파일도 [지원합니다][custom-instructions-support]. + +### 지침 파일 관리 모범 사례 + +지침 파일을 만드는 방법에 대한 자세한 설명은 이 워크숍의 범위를 벗어납니다. 샘플 프로젝트에는 일반적인 접근 방식을 보여 주는 예제가 포함되어 있습니다. 큰 틀에서는 다음과 같이 관리합니다. + +- `copilot-instructions.md`에는 프로젝트 설명, 프로젝트 구조, 전역 코딩 표준처럼 프로젝트 수준의 지침을 작성합니다. +- `*.instructions.md` 파일에는 단위 테스트, Astro 컴포넌트, 데이터 계층과 같은 파일 유형별 지침이나 특정 작업 지침을 작성합니다. +- 자연어를 사용하고, 지침을 명확하게 작성하며, 좋은 코드와 피해야 할 코드 예제를 제공합니다. + +지침 파일을 만드는 한 가지 정답이나 AI를 사용하는 한 가지 정답은 없습니다. 직접 실험하며 프로젝트에 맞는 방법을 찾습니다. + +> [!TIP] +> GitHub Copilot을 사용하는 프로젝트에는 체계적인 지침 파일 모음이 필요합니다. 프로젝트 파일을 살펴보면 [UI 업데이트][ui-instructions] 및 [Astro][astro-instructions]를 비롯한 여러 작업에 대한 지침을 확인할 수 있습니다. +> +> Copilot에 지침 파일 생성을 요청할 수도 있습니다. 각 환경에서 사용하는 방법은 다릅니다. 예를 들어 VS Code에서는 **Configure Chat → Generate Agent Instructions**, Copilot CLI에서는 `/init`을 사용할 수 있습니다. 해당 환경의 레슨에서 관련 방법을 안내합니다. +> +> 시작 템플릿을 찾고 있다면 지침 파일, 사용자 지정 에이전트, 기타 리소스가 있는 [awesome-copilot][awesome-copilot] 리포지토리를 살펴봅니다. + +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[awesome-copilot]: https://github.com/github/awesome-copilot +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support + +## 이 프로젝트의 사용자 지정 지침 파일 살펴보기 + +이 리포지토리에는 핵심 `copilot-instructions.md` 파일 하나와 다양한 작업을 위한 `*.instructions.md` 파일 모음이 있습니다. 편집기 또는 GitHub 웹 UI에서 파일을 엽니다. + +1. `.github/copilot-instructions.md`를 엽니다. +2. 프로젝트에 대한 간단한 설명과 **Agent notes**, **Code standards**, **Scripts**, **Repository Structure** 등의 섹션을 살펴봅니다. **Code standards** 아래의 **GitHub Actions Workflows** 지침도 확인합니다. 이 지침은 Copilot과 상호 작용할 때마다 적용됩니다. +3. `.github/instructions` 폴더를 열어 파일을 살펴봅니다. Astro 파일, Drizzle 데이터 계층, 테스트 등에 대한 지침이 있습니다. +4. `.github/instructions/unit-tests.instructions.md`를 엽니다. 맨 위의 `applyTo` 필드는 리포지토리 루트에 상대적인 glob을 지정합니다. 여기서는 `**/*.test.ts`와 일치하는 TypeScript 테스트 파일에 지침이 적용됩니다. +5. 단위 테스트 작성에 관한 프로젝트별 지침을 확인합니다. +6. 마지막으로 `.github/instructions/drizzle.instructions.md`를 열고 맨 아래로 이동합니다. `unit-tests.instructions.md` 같은 다른 지침 파일과 프로젝트 파일을 가리키는 링크를 확인합니다. 이를 활용하면 큰 지침을 작고 재사용 가능한 파일로 나누고, Copilot이 참고할 예제를 지정할 수 있습니다. 이 파일의 경로는 리포지토리 루트가 아니라 지침 파일 위치를 기준으로 합니다. + +> [!NOTE] +> `copilot-instructions.md`의 **Code formatting requirements** 섹션에는 프로젝트 코딩 표준이 있지만, 아직 코드 문서화에 대한 요구 사항은 없습니다. 다음 단계에서 TSDoc 문서 주석과 파일 머리 주석에 관한 규칙을 추가합니다. + +## 새로운 리포지토리 표준 추가하기 + +다음 단계에서는 이 연습에서 수행할 유일한 편집 작업으로 코드에 TSDoc 문서 주석과 파일 머리 주석을 추가하도록 프로젝트 전체 규칙을 지정합니다. 이후 단계에서 cloud agent에 이슈를 할당하면 이 지침을 따릅니다. + +먼저 작업 브랜치를 준비합니다. cloud agent는 이슈가 대상으로 지정한 브랜치의 지침을 읽지만, 변경 사항은 별도로 커밋합니다. + +1. Codespace 터미널에서 새 브랜치를 만들고 전환합니다. + + ```bash + git checkout -b custom-instructions-cloud + ``` + +앞서 설명했듯 `.github/copilot-instructions.md`는 Copilot에 프로젝트 수준 정보를 제공합니다. 코드 제안을 개선하도록 리포지토리 코딩 표준을 문서화합니다. + +1. `.github/copilot-instructions.md`를 다시 엽니다. +2. 27행 근처의 **Code formatting requirements** 섹션을 찾습니다. 프로젝트의 코딩 표준이 있지만 코드 문서화 규칙은 아직 없다는 점을 확인합니다. +3. 기존 표준 바로 아래에 다음 Markdown을 추가하여 파일 머리 주석과 TSDoc 문서 주석을 요청합니다. + + ```markdown + - 내보내는 모든 함수에는 목적, 매개 변수, 반환 값을 설명하는 TSDoc 주석을 작성합니다. + - 가져오기 구문이나 코드를 작성하기 전에 파일의 목적을 설명하는 주석 블록을 추가합니다. + ``` + +4. `copilot-instructions.md`를 저장합니다. + +> [!TIP] +> 앞선 레슨에서 살펴봤듯이 지침 파일은 전역 지침을 위한 리포지토리 수준 파일(`.github/copilot-instructions.md`) 또는 특정 언어, 파일 유형, 작업을 위한 `*.instructions.md` 파일로 만들 수 있습니다. 문서 주석 규칙과 같은 프로젝트 전체 표준은 리포지토리 수준 파일에 작성하는 것이 적절합니다. + +## 지침 업데이트 커밋, 푸시, 병합하기 + +Cloud agent는 이슈가 대상으로 지정한 브랜치의 지침 파일을 읽습니다. 다음 연습에서 이슈를 Copilot에 할당하면 `main`에서 브랜치를 만들기 때문에, cloud agent가 지침을 사용하려면 변경 사항을 `main`에 병합해야 합니다. + +1. 스테이징하고 커밋합니다. + + ```bash + git add .github/copilot-instructions.md + git commit -m "Add doc comment and file-header standards to copilot instructions" + ``` + +2. 브랜치를 푸시합니다. + + ```bash + git push -u origin custom-instructions-cloud + ``` + +3. github.com에서 `custom-instructions-cloud` 브랜치에서 `main` 브랜치로 풀 리퀘스트를 열고 병합합니다. 다음 연습에서 이슈를 할당하면 cloud agent가 이 지침을 사용합니다. + +> [!TIP] +> 워크숍에서 `main` 브랜치로 직접 작업하려면 브랜치를 만들지 않고 건너뛰어도 됩니다. 실제 프로젝트에서 작업하는 방식을 보여 주기 위해 브랜치 단계를 포함했습니다. + +## 요약 및 다음 단계 + +이 프로젝트에서 Copilot이 지침 파일을 활용하는 방식을 살펴보고 `.github/copilot-instructions.md`에 리포지토리 전체 표준을 추가했습니다. 이후 cloud agent가 생성하는 풀 리퀘스트에서 이 표준이 적용되는 모습을 확인합니다. + +다음으로 [첫 이슈를 Copilot cloud agent에 할당합니다][next-lesson]. + +## 리소스 + +- [GitHub Copilot 사용자 지정 지침 파일][instruction-files] +- [지침 파일 작성 모범 사례][instructions-best-practices] +- [Copilot을 위한 더 나은 사용자 지정 지침 작성 팁 5가지][copilot-instructions-five-tips] +- [Awesome Copilot — 지침 파일 및 기타 리소스 모음][awesome-copilot] + +[previous-lesson]: ../0-prerequisites/ +[next-lesson]: ../2-cloud-agent/ +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[copilot-instructions-five-tips]: https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/ diff --git a/docs/ko-kr/real-world-development/cloud/2-cloud-agent.md b/docs/ko-kr/real-world-development/cloud/2-cloud-agent.md new file mode 100644 index 00000000..0b7bb983 --- /dev/null +++ b/docs/ko-kr/real-world-development/cloud/2-cloud-agent.md @@ -0,0 +1,204 @@ +--- +title: "연습 2 - GitHub Copilot cloud agent" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +| [← 이전 레슨: 사용자 지정 지침][previous-lesson] | +|:--| + +기술 부채로 어려움을 겪지 않는 조직은 거의 없습니다. 해결되지 않은 보안 문제, 업데이트가 필요한 레거시 코드, 구현할 시간이 없어 백로그에 남은 기능 요청 등이 그 예입니다. GitHub Copilot cloud agent는 코드를 업데이트하고 기능을 추가하는 등의 작업을 자율적으로 수행합니다. 작업을 마치면 사람이 검토할 수 있도록 초안 PR을 엽니다. 이를 통해 지루한 작업을 위임하고 개발 프로세스를 빠르게 진행하여 더 큰 과제에 집중할 수 있습니다. + +이 연습에서는 Copilot cloud agent를 다음과 같이 활용합니다. + +- 코드 생성 환경을 사용자 지정합니다. +- 작업이 안전하게 수행되는지 확인합니다. +- 범위가 명확한 이슈의 중요성을 살펴봅니다. +- 이슈를 Copilot에 할당합니다. + +## 시나리오 + +Tailspin Toys에는 해결할 기술 부채가 있습니다. 초기 웹사이트를 만든 계약 업체가 문서를 충분히 작성하지 않았습니다. 먼저 애플리케이션에서 내보내는 모든 함수에 TSDoc 문서 주석을 추가하려고 합니다. + +또한 디자인 팀은 게임 검색 환경을 개선하려고 합니다. 각 게임 상세 페이지에 관련 게임, 즉 같은 카테고리에 속한 다른 게임을 표시하려고 합니다. 세련된 구현이 필요한 것은 아니며, 사용자 경험(UX) 테스트에 사용할 수 있는 기능을 원합니다. 현재는 우선순위가 더 높은 다른 이슈가 있어 이 작업이 보류되어 있습니다. + +이처럼 우선순위가 밀리기 쉬운 작업은 Copilot cloud agent에 맡기기 좋습니다. 개발자는 다른 작업에 집중하고, Copilot cloud agent는 비동기적으로 작업을 수행합니다. 나중에 돌아와 Copilot이 만든 결과를 검토하고 요구 사항에 맞는지 확인하면 됩니다. + +## GitHub Copilot cloud agent 소개 + +[GitHub Copilot cloud agent](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent#overview-of-copilot-cloud-agent-formerly-copilot-coding-agent)는 사람 개발자와 비슷하게 백그라운드에서 작업을 수행할 수 있습니다. 사람 개발자에게 하듯 [GitHub 이슈를 Copilot에 할당][assign-issue]하는 방식으로 작업을 요청할 수 있습니다. 작업을 할당하면 Copilot은 진행 상황을 추적하기 위한 초안 풀 리퀘스트를 만들고 환경을 설정한 뒤 작업을 시작합니다. 작업이 진행 중일 때나 완료된 뒤에 Copilot 세션을 살펴볼 수 있습니다. 결과를 검토할 준비가 되면 풀 리퀘스트에서 사용자를 태그합니다. + +## 범위가 명확한 지침의 중요성 + +GitHub Copilot에는 마법 같은 기능이 없습니다. 생각하는 과정을 건너뛸 수는 없습니다. 겉보기에는 간단한 작업도 자세히 살펴보면 복잡할 수 있으므로 [Copilot cloud agent에 할당하는 작업의 범위를 신중하게 정합니다][cloud-agent-best-practices]. AI 페어 프로그래머처럼 단계별로 접근하고 배우고 실험하며 조정합니다. 생성형 AI를 사용하더라도 소프트웨어 개발의 기본은 달라지지 않습니다. + +## 이 리포지토리의 사용자 지정 지침 + +이전 연습에서 사용자 지정 지침과 Copilot을 안내하는 방식을 살펴봤습니다. 사용자 지정 지침 연습을 완료했다면 `.github/copilot-instructions.md`를 사용해 본 적이 있을 것입니다. 아직 살펴보지 않았다면 Copilot cloud agent에 작업을 할당하기 전에 이 리포지토리에 포함된 지침 파일을 읽어 봅니다. 나중에 영향을 확인할 수 있도록 읽기만 합니다. + +GitHub 웹 UI 또는 실행 중인 Codespace에서 다음 파일을 엽니다. + +- `.github/copilot-instructions.md` - TypeScript 규칙과 TSDoc 문서 주석 요구 사항이 포함된 **Code standards** 섹션을 검토합니다. +- `.github/instructions/unit-tests.instructions.md` - `applyTo` frontmatter가 `**/*.test.ts` 파일에 지침을 적용하는 방식을 살펴봅니다. + +다음 섹션에서 `코드에 문서가 부족합니다` 이슈를 cloud agent에 할당할 때 풀 리퀘스트에 TSDoc 문서 주석, TypeScript 규칙, 파일 머리 주석이 반영되는지 확인합니다. 이후 연습에서 풀 리퀘스트를 검토할 때 다시 살펴봅니다. + +## Copilot cloud agent 개발 환경 설정하기 + +코드를 작성하려면 일반적으로 적절한 환경을 마련하고 초기 상태를 확인하기 위한 설정 스크립트를 실행해야 합니다. Copilot은 소프트웨어 엔지니어와 비슷한 방식으로 작업하므로 Copilot에 작업을 할당할 때도 마찬가지입니다. + +Cloud agent는 작업 환경으로 [GitHub Actions][github-actions]를 사용합니다. 작업을 시작하기 전에 실행할 [특수 설정 워크플로][setup-workflow]를 `.github/workflows/copilot-setup-steps.yml` 파일에 구성하여 필요한 개발 도구와 종속성을 제공할 수 있습니다. 이 워크숍이 원활하게 진행되도록 해당 설정이 미리 준비되어 있습니다. 단일 Astro 앱에 필요한 Node.js, 프로젝트 종속성, 엔드투엔드 테스트용 브라우저 바이너리, 마이그레이션 및 시드 작업을 마친 SQLite 데이터베이스를 Copilot이 사용할 수 있도록 합니다. + +```yaml +name: "Copilot Setup Steps" + +# 리포지토리의 Actions 탭에서 설정 단계를 직접 실행할 수 있습니다. +on: workflow_dispatch + +env: + ASTRO_TELEMETRY_DISABLED: "1" + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + # 아래 단계에 필요한 최소 권한만 지정합니다. Copilot은 자체 토큰을 사용합니다. + permissions: + # 종속성 설치 등을 위해 설정 단계에서 리포지토리를 복제하려면 contents: read 권한이 필요합니다. 설정 단계에서 리포지토리를 복제하지 않으면 단계가 끝난 뒤 Copilot이 자동으로 복제합니다. + contents: read + steps: + - name: Checkout code + uses: actions/checkout@v5 + + # 프런트엔드 및 앱 설정 - Node.js(앱 전체가 Astro + Drizzle/libSQL로 구성됨) + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: "lts/*" + cache: "npm" + cache-dependency-path: "./package-lock.json" + + - name: Install JavaScript dependencies + run: npm ci + + - name: Install Playwright browsers + run: npx playwright install --with-deps chromium + + # 로컬 SQLite 데이터베이스를 마이그레이션하고 시드하여 빌드 및 테스트용 데이터를 준비합니다. + - name: Set up the database + run: npm run db:setup +``` + +다른 GitHub 워크플로 파일과 비슷하지만 몇 가지 중요한 특징이 있습니다. + +- `copilot-setup-steps`라는 단일 작업이 있습니다. Copilot이 풀 리퀘스트에서 작업을 시작하기 전에 이 작업이 GitHub Actions에서 실행됩니다. +- `workflow_dispatch` 트리거를 사용하므로 리포지토리의 **Actions** 탭에서 워크플로를 직접 실행할 수 있습니다. Copilot이 작업을 시작할 때까지 기다리지 않고 워크플로가 성공적으로 실행되는지 확인할 수 있습니다. + +## 문서 추가하기 + +문서가 중요하다는 것은 모두 알지만, 대부분의 프로젝트에는 오래된 정보가 있거나 문서가 전혀 없습니다. 이런 기술 부채는 해결되지 않은 채 남아 생산성을 낮추고 코드베이스를 유지 관리하거나 새 개발자를 온보딩하기 어렵게 만듭니다. Copilot은 문서 작성에도 유용하므로 이 작업을 Copilot cloud agent에 맡길 수 있습니다. Copilot은 백그라운드에서 필요한 문서를 작성합니다. 이후 연습에서 결과를 검토합니다. + +1. 새 브라우저 탭에서 github.com의 리포지토리로 이동합니다. +2. **Issues** 탭을 선택합니다. +3. **New issue**를 선택하여 새 이슈 대화 상자를 엽니다. +4. **Blank issue**를 선택합니다. +5. **Title**에 `코드에 문서가 부족합니다`를 입력합니다. +6. **Description**에 다음을 입력합니다. + + ```plaintext + 우리 조직에서는 함수와 메서드에 도움이 되는 경우 TSDoc 문서 주석을 포함하도록 요구합니다. 안타깝게도 최근 업데이트에서 이 표준이 지켜지지 않았습니다. 동작을 명확히 하는 경우 문서 주석이 포함되도록 기존 코드를 업데이트해야 합니다. + ``` + +7. **Create**를 선택하여 이슈를 만듭니다. +8. 오른쪽에서 **Assign to Copilot**을 선택하여 할당 대화 상자를 엽니다. + + ![이슈에 Copilot을 할당하는 화면](../../../_images/shared-assign-copilot.png) + +9. **Assign**을 선택합니다. + + ![Copilot에 이슈를 할당한 세부 정보](../../../_images/ex4-assign-copilot-details.png) + +10. **Pull Requests** 탭을 선택합니다. +11. 새 풀 리퀘스트(PR)를 엽니다. 제목은 `[WIP]: 문서 누락 수정`과 비슷할 수 있습니다. 목록에 새 PR이 없으면 잠시 기다린 뒤 브라우저 창을 새로 고칩니다. +12. 몇 분 뒤 Copilot이 할 일 목록을 만든 것을 확인합니다. + +> [!NOTE] +> Copilot의 할 일 목록이 PR에 나타나기까지 몇 분 정도 걸릴 수 있습니다. Copilot이 작업 환경을 만들고, 앞서 설명한 워크플로를 실행하고, 프로젝트를 분석하고, 문제를 해결할 방법을 찾고 있습니다. + +13. 목록과 Copilot이 수행할 작업을 검토합니다. +14. 풀 리퀘스트 타임라인을 아래로 스크롤하여 Copilot이 이슈 작업을 시작했다는 업데이트를 확인합니다. +15. **View session** 버튼을 선택합니다. + + ![Copilot 세션 보기](../../../_images/ex4-view-session.png) + +> [!CAUTION] +> 업데이트된 표시를 보려면 창을 새로 고쳐야 할 수 있습니다. + +16. 실시간 세션을 스크롤하며 Copilot이 문제를 해결하는 과정을 살펴봅니다. 코드와 상태를 확인하고 적절한 계획을 세운 뒤 코드를 작성하는 과정을 확인할 수 있습니다. + +이 작업은 몇 분 정도 걸립니다. Copilot cloud agent의 주요 장점은 비동기적으로 작업하여 개발자가 다른 일에 집중할 수 있게 하는 것입니다. 이 기능을 활용해 또 다른 작업을 Copilot cloud agent에 할당한 다음, 애플리케이션의 기능을 추가하는 작업을 진행합니다. + +## 게임 상세 페이지에 관련 게임 섹션 추가하기 + +GitHub Copilot cloud agent의 장점 중 하나는 작업을 나눌 수 있다는 점입니다. 사용자는 한 가지 작업에 집중하고 Copilot은 다른 작업을 수행할 수 있습니다. 디자인 팀이 요청한 관련 게임 섹션을 추가하는 데 시간이 오래 걸리지 않더라도, 그 시간에 다른 작업을 할 수 있습니다. 이 작업도 Copilot cloud agent에 할당합니다. + +1. github.com의 리포지토리로 돌아갑니다. +2. **Issues** 탭을 선택합니다. +3. **New issue**를 선택하여 새 이슈 대화 상자를 엽니다. +4. **Blank issue**를 선택합니다. +5. **Title**에 `게임 상세 페이지에 관련 게임 표시`를 입력합니다. +6. **Description**에 다음을 입력합니다. + + ```markdown + 사용자가 더 많은 게임을 발견할 수 있도록 각 게임 상세 페이지에 관련 게임을 표시하려고 합니다. 디자인 팀은 사용자 경험을 살펴보고 인수 테스트를 수행하려고 합니다. 요구 사항은 다음과 같습니다. + + - `src/lib/`에 지정한 게임을 제외하고 같은 카테고리의 다른 게임을 반환하는 데이터 접근 도우미를 추가합니다. + - 해당 도우미를 사용하는 "관련 게임" 섹션을 게임 상세 페이지에 표시합니다. + - 관련 게임이 없는 경우를 처리합니다. + - 새 도우미에 대한 단위 테스트를 작성합니다. + - PR을 만들기 전에 모든 테스트가 통과하는지 확인합니다. + ``` + +7. **Create**를 선택하여 이슈를 만듭니다. +8. 오른쪽에서 **Assign to Copilot**을 선택하여 할당 대화 상자를 엽니다. + + ![이슈에 Copilot을 할당하는 화면](../../../_images/shared-assign-copilot.png) + +9. **Assign**을 선택합니다. + +잠시 후 이슈의 첫 번째 댓글에 Copilot이 작업 중임을 나타내는 👀 표시가 나타납니다. + +![눈 이모지로 이슈 작업 중임을 표시하는 Copilot](../../../_images/ex4-issue-eyes-emoji.png) + +이제 Copilot이 두 번째 요청을 처리하고 있습니다. Copilot cloud agent는 소프트웨어 엔지니어처럼 작업하므로 계속 지켜볼 필요는 없습니다. 작업이 완료된 후 결과를 검토하면 됩니다. 이제 사용자 지정 에이전트를 살펴보고 사용합니다. + +## 요약 및 다음 단계 + +[GitHub Copilot cloud agent][copilot-agents]를 살펴봤습니다. cloud agent에 이슈를 할당하면 비동기적으로 작업을 수행합니다. Copilot에 기술 부채 해결, 새 기능 작성, 프레임워크 간 코드 마이그레이션 등을 요청할 수 있습니다. + +이 연습에서는 다음을 살펴봤습니다. + +- 코드 생성 환경을 사용자 지정하는 방법 +- 작업이 안전하게 수행되는지 확인하는 방법 +- 범위가 명확한 이슈의 중요성 +- Copilot에 이슈를 할당하는 방법 + +Cloud agent가 백그라운드에서 작업하는 동안 사용자 지정 에이전트를 만들고 사용합니다. [Copilot cloud agent는 MCP 서버][cloud-agent-mcp]도 사용할 수 있으며, 앞선 모듈에서 살펴본 사용자 지정 지침을 함께 활용합니다. + +## 리소스 + +- [Copilot cloud agent 정보][copilot-agents] +- [GitHub 이슈를 Copilot에 할당하기][assign-issue] +- [Copilot cloud agent 설정 워크플로 모범 사례][cloud-agent-best-practices] + +| [다음 레슨: 사용자 지정 에이전트 →][next-lesson] | +|--:| + +[previous-lesson]: ../1-custom-instructions/ +[next-lesson]: ../3-custom-agents/ +[cloud-agent-mcp]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/extend-cloud-agent-with-mcp +[assign-issue]: https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions +[setup-workflow]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[copilot-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[cloud-agent-best-practices]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[github-actions]: https://docs.github.com/actions diff --git a/docs/ko-kr/real-world-development/cloud/3-custom-agents.md b/docs/ko-kr/real-world-development/cloud/3-custom-agents.md new file mode 100644 index 00000000..5d621244 --- /dev/null +++ b/docs/ko-kr/real-world-development/cloud/3-custom-agents.md @@ -0,0 +1,106 @@ +--- +title: "연습 3 - 사용자 지정 에이전트" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +## 사용자 지정 에이전트란? + +GitHub Copilot의 [사용자 지정 에이전트][custom-agents-concept]는 개발 워크플로의 특정 작업이나 영역에 맞춘 전문 AI 도우미를 만들 수 있게 합니다. 리포지토리의 `.github/agents` 폴더에 Markdown 파일로 에이전트를 정의하면, Copilot이 특정 유형의 작업을 더 효과적으로 수행하도록 집중된 지침, 모범 사례, 코딩 패턴, 도메인 지식을 제공할 수 있습니다. 팀은 접근성 규정을 적용하는 에이전트, [WCAG][wcag]를 따르는 에이전트, 보안 코딩 관행을 적용하는 에이전트, 일관된 테스트 패턴을 유지하는 에이전트처럼 전문 지식을 재사용 가능한 에이전트로 정리할 수 있습니다. + +사용자 지정 에이전트는 프로젝트의 `.github/agents` 폴더 또는 전역 `~/.copilot/agents` 폴더에 Markdown 파일로 정의합니다. 각 파일에는 최소한 `name`과 `description`이 포함된 YAML frontmatter가 있고, 그 뒤에 에이전트의 동작 방식, 전문 지식, 지침을 정의하는 Markdown 프롬프트가 이어집니다. + +### 사용자 지정 에이전트와 에이전트 스킬 비교 + +사용자 지정 에이전트와 [에이전트 스킬][agent-skills-concept]은 일부 역할이 겹칩니다. 둘 다 주로 Markdown 파일로 정의하며 AI에 작업 수행 방법을 알려 줍니다. 간단하게 구분하면 **사용자 지정 에이전트는 작업자이고 스킬은 도구**입니다. + +사용자 지정 에이전트에는 자체 컨텍스트 창이 있으며, 작업을 수행할 때 스킬이나 다른 에이전트를 조율할 수 있습니다. 이 실습의 접근성 사용자 지정 에이전트는 접근성 지침에 따라 사이트를 검토하고 업데이트합니다. 작업의 일부로 풀 리퀘스트 워크플로 스킬이나 테스트를 실행하고 관리하는 스킬을 호출할 수 있습니다. + +> [!NOTE] +> 사용자 지정 에이전트를 작성하는 하나의 정답은 없습니다. AI를 사용하는 다른 작업과 마찬가지로 환경과 시나리오에 맞게 테스트하고 반복 개선합니다. + +[custom-agents-concept]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[agent-skills-concept]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/ + +사용자 지정 에이전트로 다음을 살펴봅니다. + +- 사용자 지정 에이전트를 정의하는 방법 +- 사용자 지정 에이전트에 작업을 할당하는 방법 + +## 시나리오 + +Tailspin Toys는 시각 능력이나 선호도에 관계없이 모든 사용자가 크라우드 펀딩 플랫폼을 이용할 수 있도록 노력하고 있습니다. 최근 사용자 의견에 따르면 텍스트와 배경 색상의 대비가 충분하지 않아 일부 사용자가 현재 어두운 테마를 읽기 어렵다고 합니다. 이에 디자인 팀은 사용자가 켜고 끌 수 있는 고대비 모드 구현을 요청했습니다. + +접근성은 중요하므로 이 기능을 가능한 한 빨리 구현하려고 합니다. 사용자 지정 에이전트를 활용해 기능을 생성합니다. + +## 접근성 사용자 지정 에이전트 검토하기 + +접근성 작업을 위한 사용자 지정 에이전트가 이미 준비되어 있습니다. 내용을 검토하여 Copilot을 어떻게 안내하는지 확인합니다. + +Codespace로 돌아가 접근성 사용자 지정 에이전트 파일을 검토합니다. + +1. `.github/agents/accessibility.md`를 엽니다. +2. `name` 및 `description` 필드가 있는 YAML frontmatter를 확인합니다. + +> [!CAUTION] +> 사용자 지정 에이전트에는 `name` 및 `description` frontmatter가 필요합니다. + +3. 이어지는 섹션을 살펴보고 다음 내용을 확인합니다. + - 접근성 있는 웹사이트를 위한 코드 생성 시 핵심 책임 + - 접근성 모범 사례 + - HTML, CSS, JavaScript 코드 예제 + - 흔히 발생하는 문제와 실수 + +## 이슈 만들고 Copilot에 할당하기 + +제어 센터(Mission control)는 환경의 모든 에이전트와 작업하는 중심 공간입니다. Copilot cloud agent에 작업을 할당하고 작업을 모니터링하며 추가 지침을 보낼 수 있습니다. 먼저 접근성 에이전트에 고대비 모드 구현 작업을 할당합니다. + +1. 리포지토리로 이동합니다. +2. **Issues** 탭을 선택합니다. +3. **New issue**를 선택하여 새 이슈 대화 상자를 엽니다. +4. **Blank issue**를 선택합니다. +5. **Title**에 `웹사이트에 고대비 모드 추가`를 입력합니다. +6. **Description**에 다음을 입력합니다. + + ```plaintext + 사이트에 고대비 모드를 추가해야 합니다. 사용자가 설정할 수 있는 고대비 토글이 있어야 하며, 브라우저의 로컬 스토리지에 설정을 저장해야 합니다. + ``` + +7. **Create**를 선택하여 이슈를 만듭니다. +8. 오른쪽에서 **Assign to Copilot**을 선택하여 할당 대화 상자를 엽니다. +9. 목록에서 **Accessibility agent**를 선택합니다. + + ![고대비 모드 이슈에 접근성 에이전트를 할당하는 화면](../../../_images/ex5-select-custom-agent.png) + +10. **Assign**을 선택합니다. +11. Copilot이 백그라운드에서 작업을 시작합니다. + +## 요약 및 다음 단계 + +GitHub Copilot의 [사용자 지정 에이전트][custom-agents]는 특정 작업과 영역을 위한 전문 AI 도우미입니다. 사용자 지정 에이전트로 팀의 전문 지식과 표준을 재사용 가능한 형태로 정의해 Copilot이 특정 유형의 작업을 더 효과적으로 수행하도록 안내할 수 있습니다. + +이 연습에서는 다음을 살펴봤습니다. + +- 사용자 지정 에이전트가 정의되는 방식 +- 사용자 지정 에이전트에 작업을 할당하는 방법 + +Copilot이 고대비 모드를 구현하는 동안 다음으로 [에이전트 세션을 모니터링하고 안내합니다][next-lesson]. + +## 리소스 + +- [사용자 지정 에이전트 정보][custom-agents] +- [조직에서 사용자 지정 에이전트 사용 준비하기][org-custom-agents] +- [엔터프라이즈에서 사용자 지정 에이전트 사용 준비하기][enterprise-custom-agents] + +--- + +| [← 이전 레슨: GitHub Copilot cloud agent][previous-lesson] | [다음 레슨: 에이전트 모니터링 및 관리 →][next-lesson] | +|:--|--:| + +[previous-lesson]: ../2-cloud-agent/ +[next-lesson]: ../4-managing-agents/ +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[org-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents +[enterprise-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents diff --git a/docs/ko-kr/real-world-development/cloud/4-managing-agents.md b/docs/ko-kr/real-world-development/cloud/4-managing-agents.md new file mode 100644 index 00000000..1bc8f14e --- /dev/null +++ b/docs/ko-kr/real-world-development/cloud/4-managing-agents.md @@ -0,0 +1,91 @@ +--- +title: "연습 4 - 에이전트 모니터링 및 관리" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +앞선 두 연습에서는 Copilot cloud agent에 사용자 경험을 개선하고 기능을 추가하는 세 가지 작업을 요청했습니다. Cloud agent는 비동기적이고 자율적으로 작동하지만, 작업을 모니터링하는 것도 중요합니다. + +GitHub.com의 [agents 페이지][agents-page] 등 cloud agent에 할당한 작업을 관리하는 도구가 다양하게 있습니다. 이 제어 센터에서 열린 풀 리퀘스트(PR)가 있는 모든 에이전트 작업을 볼 수 있습니다. 수행한 작업을 살펴보고, 진행 중인 세션에 추가 지침을 보내 방향을 조정할 수도 있습니다. + +이 레슨에서는 다음을 수행합니다. + +- agents 페이지에서 cloud agent 작업을 모니터링합니다. +- 진행 중인 세션에 추가 기능을 요청합니다. + +## 시나리오 + +접근성 에이전트가 고대비 모드를 만들도록 요청한 뒤, 팀은 밝은 모드도 함께 추가하기로 했습니다. 사이트 스타일을 업데이트하고 토글 기능을 만드는 중이므로 밝은 모드도 포함하는 편이 자연스럽습니다. 에이전트에 추가 지침을 보내 고대비 모드와 밝은 모드를 모두 구현하도록 합니다. + +## Copilot cloud agent 작업 검토하기 + +Copilot cloud agent에 할당된 작업의 현재 상태를 확인합니다. + +1. [Copilot agents 페이지](https://github.com/copilot/agents)로 이동합니다. +2. 기본 창과 왼쪽 창에 표시되는 작업 목록을 살펴봅니다. 다음과 같이 Copilot에 할당한 작업이 표시됩니다. + - 코드베이스 문서 업데이트 + - 게임 상세 페이지에 관련 게임 표시 + - 웹사이트에 고대비 모드 추가 +3. 실행 중인 작업 하나를 선택하고 Copilot이 수행한 작업을 검토합니다. 다음 작업을 수행할 수 있습니다. + - 리포지토리에서 코드 확인 + - Copilot 작업 환경 생성 + - MCP 서버 설정 + - 할당된 작업 완료를 위한 여러 단계 수행 + +> [!NOTE] +> 표시되는 정확한 단계는 Copilot의 작업 상태와 접근 방식에 따라 다릅니다. + +4. 오른쪽에 나타나는 풀 리퀘스트(PR) 창도 살펴봅니다. 여기에서 PR과 변경된 파일을 확인할 수 있습니다. + +## Cloud agent에 추가 지침 보내기 + +현재 진행 중인 작업을 확인했으니, 에이전트가 고대비 모드를 구현하는 동안 밝은 모드 토글도 추가하도록 요청합니다. + +1. 고대비 모드 작업을 진행 중인 세션을 선택합니다. 정확한 제목은 Copilot이 선택한 이름과 작업 상태에 따라 달라집니다. + + ![제어 센터의 접근성 세션](../../../_images/ex6-accessibility-session.png) + +2. 세션이 설정을 마치고 작업을 시작할 때까지 몇 분간 확인합니다. 다음과 비슷한 메시지가 표시되면 작업이 시작된 것입니다. +3. **Steer active session while Copilot is working** 대화 상자에 다음 프롬프트를 입력합니다. + + ```plaintext + 고대비 모드를 만드는 김에 밝은 모드도 추가해 주세요. 사용자가 원하는 표시 모드를 선택할 수 있도록 밝은 모드 토글도 제공해야 합니다. + ``` + + ![agents 페이지의 cloud agent 작업에서 활성 세션 안내 대화 상자를 강조한 스크린샷](../../../_images/ex6-steer-cloud-agent-task.png) + +4. Enter를 눌러 프롬프트를 보냅니다. +5. Copilot이 요청을 확인하고 작업 흐름에 반영하는지 살펴봅니다. + +## Copilot이 작업하도록 두기 + +이전과 마찬가지로 Copilot이 업데이트된 작업을 시작합니다. 메시지를 보낸 시점에 진행 중이던 단계를 마친 다음 새로운 요청을 작업 흐름에 반영합니다. + +이 작업도 몇 분 정도 걸리므로, 그동안 지금까지 배운 내용을 돌아볼 수 있습니다. + +## 요약 및 다음 단계 + +Copilot cloud agent 작업을 모니터링하고 안내하는 중심 공간인 Copilot agents 페이지를 살펴봤습니다. 이 제어 센터에서 진행 중이거나 완료된 모든 작업을 추적하고 수행 내용을 검토하며, 진행 중인 세션의 방향을 조정할 수 있습니다. + +이 연습에서는 다음을 수행했습니다. + +- 제어 센터와 agents 페이지를 살펴보며 cloud agent 작업을 모니터링했습니다. +- 진행 중인 세션에 추가 기능을 요청했습니다. + +Copilot이 접근성 기능 구현을 계속하는 동안, 다음으로 [Copilot이 만든 풀 리퀘스트를 반복 개선합니다][next-lesson]. + +## 리소스 + +- [Copilot agents 페이지][agents-page] +- [사용자 지정 에이전트 정보][custom-agents] + +--- + +| [← 이전 레슨: 사용자 지정 에이전트][previous-lesson] | [다음 레슨: Copilot 작업 반복 개선 →][next-lesson] | +|:--|--:| + +[previous-lesson]: ../3-custom-agents/ +[next-lesson]: ../5-iterating/ +[agents-page]: https://github.blog/changelog/2025-07-03-agents-page-for-copilot-coding-agent-in-public-preview +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents diff --git a/docs/ko-kr/real-world-development/cloud/5-iterating.md b/docs/ko-kr/real-world-development/cloud/5-iterating.md new file mode 100644 index 00000000..c548b856 --- /dev/null +++ b/docs/ko-kr/real-world-development/cloud/5-iterating.md @@ -0,0 +1,192 @@ +--- +title: "연습 5: GitHub Copilot 작업 반복 개선" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +| [← 이전 레슨: 에이전트 관리][previous-lesson] | +|:--| + +## 작업 검토하기 + +이 실습에서는 GitHub Copilot과 함께 사용자 경험과 기능을 개선하는 여러 작업을 수행했습니다. Copilot에 코드 문서를 추가하고 디자인 팀을 위해 관련 게임 기능을 만들고, 고대비 및 밝은 모드 토글을 포함한 접근성 기능을 구현하도록 요청했습니다. Copilot의 작업을 살펴보고 필요하다면 피드백을 제공해 개선합니다. 그런 다음 나머지 팀원에게 검토를 요청합니다. + +### 시나리오 + +생성형 AI를 사용하더라도 소프트웨어 설계와 DevOps의 기본은 바뀌지 않습니다. 생성된 코드를 검토하고 일반적인 DevOps 프로세스를 따라야 합니다. 이를 염두에 두고 팀에서 검토를 시작하기 전에 GitHub Copilot이 문서, 관련 게임 기능, 접근성 기능을 어떻게 만들었는지 검토합니다. + +## GitHub Copilot cloud agent 보안 + +Copilot cloud agent는 감독 없이 비동기적으로 작업하므로 안전성을 보장하기 위한 보안 제한이 있습니다. + +- Copilot은 리포지토리에 대한 읽기 권한만 가집니다. 코드 작성에 사용하는 브랜치에만 쓰기 권한이 있습니다. +- Cloud agent는 GitHub Actions에서 별도의 임시 작업 환경을 만듭니다. +- GitHub Actions 워크플로를 실행하려면 사람이 먼저 승인해야 합니다. +- MCP 서버를 포함한 [외부 리소스 액세스는 기본적으로 제한됩니다](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-firewall). + +## 생성된 문서 검토하기 + +먼저 GitHub Copilot cloud agent가 코드를 문서화한 첫 번째 풀 리퀘스트(PR)를 검토합니다. github.com의 일반적인 PR 인터페이스를 사용합니다. + +> [!NOTE] +> PR을 살펴볼 때 GitHub Copilot이 방화벽에 의해 차단되었다는 경고가 표시될 수 있습니다. MCP 서버 호출을 포함한 외부 리소스 액세스가 기본적으로 제한되므로 정상적인 동작입니다. 원한다면 [Copilot cloud agent의 방화벽을 사용자 지정하거나 비활성화할 수 있습니다][agent-firewall]. + +1. github.com의 리포지토리로 돌아갑니다. +2. **Pull Requests**를 선택하여 PR 목록을 엽니다. +3. 제목이 **누락된 문서 추가** 또는 이와 비슷한 풀 리퀘스트를 엽니다. + +> [!NOTE] +> Copilot이 아직 작업 중이면 PR에 **[WIP]** 표시가 있습니다. Copilot이 작업을 완료할 때까지 기다립니다. 몇 분 정도 걸릴 수 있으므로 잠시 쉬거나 지금까지 배운 내용을 돌아봐도 좋습니다. + +4. PR이 준비되면 **Files changed** 탭을 선택하여 변경 사항을 검토합니다. + + ![Files changed 탭](../../../_images/shared-pr-files-changed.png) + +5. 새로 추가된 TSDoc 문서 주석과 기타 문서를 포함해 코드 변경 사항을 살펴봅니다. 정확한 변경 사항은 다를 수 있습니다. + + 검토할 때 TSDoc 문서 주석, TypeScript 규칙, 파일 머리 주석을 확인합니다. 이는 연습 2에서 살펴본 사용자 지정 지침 파일의 영향을 받은 내용입니다. + +6. 업데이트를 검토하고 문제가 없으면 **Conversation** 탭으로 돌아가 아래로 스크롤합니다. +7. 승인을 기다리는 워크플로가 있다는 표시가 있는지 확인합니다. +8. 승인을 기다리는 워크플로가 있다면 **Approve and run workflows**를 선택합니다. + + ![워크플로 승인 및 실행](../../../_images/shared-approve-workflows.png) + +9. 풀 리퀘스트 검사 섹션에서 워크플로가 실행 대기열에 추가되는 것을 확인합니다. 문제가 없다면 단일 Astro 앱에 대한 프로젝트 검사가 통과합니다. 완료까지 몇 분 정도 걸릴 수 있습니다. + +## GitHub Copilot에 변경 요청하기 + +Copilot과 풀 리퀘스트에서 협업할 때 댓글로 Copilot을 태그할 수 있습니다. 팀원에게 요청하는 것처럼 PR 댓글이나 코드의 인라인 댓글에서 요청할 수 있습니다. Copilot은 댓글을 확인하고 변경 사항을 처리하기 위한 새 세션을 시작합니다. 결과가 비결정적이므로 특정 문구를 지정할 수는 없습니다. 다음과 같은 변경을 요청할 수 있습니다. + +- 각 코드 파일 맨 위에 파일의 역할을 설명하는 주석을 추가합니다. +- TypeScript 및 Astro 파일에 TSDoc 문서 주석을 추가합니다. +- Astro 앱 구조를 설명하는 README를 만듭니다. + +1. 위 아이디어 중 하나를 사용하거나 코드베이스에 추가하고 싶은 문서에 대해 다른 요청을 작성하고, **@copilot**을 태그해 댓글을 추가합니다. +2. **View Session**을 선택하여 Copilot의 작업을 확인합니다. Copilot이 업데이트를 위해 새 세션을 시작합니다. +3. **Back to pull request**를 선택해 PR로 돌아갈 수 있습니다. + + ![풀 리퀘스트로 돌아가기](../../../_images/ex7-back-to-pr.png) + +4. Copilot이 변경을 마치면 PR에 새 커밋이 표시됩니다. +5. **Files changed** 탭을 선택하여 변경 사항을 검토합니다. + +원하는 결과가 나올 때까지 계속 반복해도 좋습니다. 만족스러우면 초안 PR을 검토 준비 상태로 변경한 뒤 `main` 브랜치에 병합할 수 있습니다. + +![검토 준비 상태로 변경하는 PR](../../../_images/ex7-ready-for-review.png) + +## 관련 게임 기능 검토하기 + +게임 상세 페이지에 관련 게임을 표시하는 이슈를 해결하기 위해 Copilot이 만든 PR을 검토합니다. + +1. GitHub.com의 리포지토리로 돌아갑니다. +2. **Pull Requests** 탭을 선택합니다. +3. 제목이 **게임 상세 페이지에 관련 게임 표시** 또는 이와 비슷한 PR을 선택합니다. +4. **Files changed** 탭을 선택하여 Copilot이 작성한 코드를 검토합니다. +5. 업데이트를 검토하고 문제가 없으면 **Conversation** 탭으로 돌아가 아래로 스크롤합니다. +6. 승인을 기다리는 워크플로가 있다는 표시가 있는지 확인합니다. +7. 승인을 기다리는 워크플로가 있다면 **Approve and run workflows**를 선택합니다. + + ![워크플로 승인 및 실행](../../../_images/shared-approve-workflows.png) + +8. 풀 리퀘스트 검사 섹션에서 워크플로가 실행 대기열에 추가되는 것을 확인합니다. 문제가 없다면 단일 Astro 앱에 대한 프로젝트 검사가 통과합니다. 완료까지 몇 분 정도 걸릴 수 있습니다. +9. **선택 사항:** Codespace에서 해당 브랜치로 전환하여 관련 게임 기능을 직접 테스트할 수 있습니다. Codespace로 이동해 터미널을 열고 다음 명령을 실행합니다. ``을 Copilot이 만든 브랜치 이름(예: **copilot/fix-8**)으로 바꿉니다. + + ```bash + git fetch origin + git checkout + ``` + +Copilot이 관련 게임 기능을 만들었습니다. 이전처럼 Copilot cloud agent에 업데이트를 요청하며 반복 작업할 수 있습니다. 예를 들어 표시할 관련 게임 수를 조정하거나, 사용자 지정 지침을 업데이트하기 **전에** 이슈에 할당된 작업에 파일 머리 주석과 TSDoc 문서 주석을 추가하도록 요청할 수 있습니다. **Conversation** 탭에 댓글을 추가하면 Copilot이 확인하고 새 세션을 시작합니다. + +## 접근성 기능 검토하기 + +마지막으로 접근성 사용자 지정 에이전트를 사용해 구현한 기능을 검토합니다. PR에는 연습 3에서 요청한 고대비 모드와 연습 4에서 제어 센터를 통해 추가로 요청한 밝은 모드가 모두 포함되어야 합니다. + +1. GitHub.com의 리포지토리로 돌아갑니다. +2. **Pull Requests** 탭을 선택합니다. +3. 제목이 **웹사이트에 고대비 모드 추가** 또는 이와 비슷한 PR을 선택합니다. + +> [!NOTE] +> Copilot이 아직 작업 중이면 PR에 **[WIP]** 표시가 있습니다. Copilot이 작업을 완료할 때까지 기다립니다. 몇 분 정도 걸릴 수 있습니다. + +4. **Files changed** 탭을 선택하여 Copilot이 작성한 코드를 검토합니다. +5. 구현 내용을 확인하며 특히 다음을 살펴봅니다. + - 모드를 전환하는 토글 UI 컴포넌트 + - 사용자 기본 설정을 유지하기 위한 로컬 스토리지 사용 + - 고대비 및 밝은 모드를 위한 CSS 또는 스타일 변경 + - 접근성 속성(ARIA 레이블, 키보드 탐색 등) + - 모드 전환을 관리하는 JavaScript/TypeScript 코드 + +6. 업데이트를 검토하고 문제가 없으면 **Conversation** 탭으로 돌아가 아래로 스크롤합니다. +7. 승인을 기다리는 워크플로가 있다는 표시가 있는지 확인합니다. +8. 승인을 기다리는 워크플로가 있다면 **Approve and run workflows**를 선택합니다. + + ![워크플로 승인 및 실행](../../../_images/shared-approve-workflows.png) + +9. 풀 리퀘스트 검사 섹션에서 워크플로가 실행 대기열에 추가되는 것을 확인합니다. 문제가 없다면 단일 Astro 앱에 대한 프로젝트 검사가 통과합니다. 완료까지 몇 분 정도 걸릴 수 있습니다. +10. **선택 사항:** Codespace에서 해당 브랜치로 전환하여 접근성 기능을 직접 테스트할 수 있습니다. Codespace로 이동해 터미널을 열고 Copilot이 만든 브랜치 이름으로 ``을 바꾼 뒤 다음을 실행합니다. + + ```bash + git fetch origin + git checkout + ``` + + 그런 다음 애플리케이션을 시작하고 브라우저에서 고대비 및 밝은 모드 토글을 테스트하여 페이지를 새로 고친 뒤에도 설정이 유지되는지 확인합니다. + +접근성 사용자 지정 에이전트는 접근성 모범 사례에 따라 기능을 구현하도록 Copilot을 안내합니다. 접근성과 관련해 우려 사항이나 개선점이 있다면 앞선 PR과 마찬가지로 댓글에서 **@copilot**을 태그해 업데이트를 요청할 수 있습니다. + +## 선택 연습 - 위임 계속하기 + +실제 백로그 작업을 cloud agent에 맡기고 다른 작업에 집중할 수 있습니다. 이 습관을 익히려면 리포지토리에 이슈를 몇 개 더 등록하고 Copilot에 할당합니다. 다음과 같은 작업을 요청할 수 있습니다. + +- 게임 상세 페이지에 후원자 관심 등록 양식을 추가합니다. +- 게임 목록 페이지에 페이지 매김을 구현합니다. +- 데이터 접근 도우미에 입력 검증과 오류 처리를 추가합니다. + +## 요약 + +Cloud agent 과정을 완료했습니다. 이 레슨에서는 다음을 수행했습니다. + +- **이 리포지토리에 포함된 사용자 지정 지침 파일을 검토했습니다.** 이후 cloud agent 결과에 미친 영향을 확인할 수 있습니다. +- **GitHub Copilot cloud agent에 이슈를 할당했습니다.** 작업 환경을 설정하고 비동기적으로 계획과 구현을 진행하는 과정을 살펴봤습니다. +- **접근성 사용자 지정 에이전트를 만들고 사용했습니다.** 고대비와 밝은 모드 토글을 추가했습니다. +- **Copilot agents 페이지를 제어 센터로 사용했습니다.** 작업이 진행되는 동안 접근성 세션을 모니터링하고 안내했습니다. +- **cloud agent가 만든 풀 리퀘스트를 검토하고 반복 개선했습니다.** `@copilot`을 태그해 변경을 요청하고 워크플로를 승인했습니다. + +## 검토 및 다음 단계 + +Cloud agent 과정을 완료했습니다. 계속 학습하려면 다른 환경을 다루는 다음 워크숍을 살펴봅니다. + +- 🖥️ **[VS Code 과정](../../vscode/)** — IDE에서 Copilot Chat 에이전트 모드와 MCP 통합을 살펴봅니다. +- 💻 **[CLI 과정](../../cli/)** — Plan 및 Autopilot 모드, 에이전트 스킬, 사용자 지정 QA 에이전트, Playwright MCP, Agent Merge, 선택적 `/delegate`를 사용해 터미널에서 변경 사항 두 개를 검토하고 전달합니다. + +본인의 리포지토리에서 다음 작업을 시도할 수도 있습니다. + +- 리팩터링이나 테스트 범위 확장 이슈를 cloud agent에 할당합니다. +- 다른 작업 분야를 위한 사용자 지정 에이전트를 만듭니다. +- 다른 기술 스택에 맞게 `copilot-setup-steps.yml`을 구성합니다. + +## 리소스 + +- [GitHub Copilot][github-copilot] +- [Copilot agent 정보][copilot-agents] +- [GitHub 이슈를 Copilot에 할당하기][assign-issue] +- [Copilot cloud agent 설정 워크플로 모범 사례][cloud-agent-best-practices] +- [Copilot cloud agent 방화벽 구성][agent-firewall] + +--- + +| [← 이전 레슨: 에이전트 관리][previous-lesson] | +|:--| + +[github-copilot]: https://github.com/features/copilot +[cloud-agent-overview]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[assign-issue]: https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions +[setup-workflow]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[copilot-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent +[cloud-agent-best-practices]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment +[agent-firewall]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-firewall + +[previous-lesson]: ../4-managing-agents/ diff --git a/docs/ko-kr/real-world-development/cloud/README.md b/docs/ko-kr/real-world-development/cloud/README.md new file mode 100644 index 00000000..130c784d --- /dev/null +++ b/docs/ko-kr/real-world-development/cloud/README.md @@ -0,0 +1,53 @@ +--- +slug: ko-kr/real-world-development/cloud +title: "GitHub Copilot cloud agent" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +[**GitHub Copilot cloud agent**](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent)는 클라우드에서 비동기적으로 작업합니다. GitHub에서 작업을 할당하면 cloud agent가 백그라운드에서 리포지토리를 살펴보고 변경한 다음 풀 리퀘스트를 엽니다. 그동안 사용자는 다른 작업을 진행할 수 있습니다. + +이 연습에서는 cloud agent가 따를 사용자 지정 지침을 추가한 다음 GitHub 이슈를 할당하여 작업을 구현하도록 합니다. 사용자 지정 에이전트를 검토하고 사용하여 접근 방식을 조정하고, 에이전트 대시보드에서 세션을 모니터링하고 안내한 뒤, 에이전트가 만든 풀 리퀘스트를 검토하고 반복해서 개선합니다. + +## 연습 + +| 연습 | 주제 | 설명 | +|----------|-------|-------------| +| [0. 사전 준비][ex0] | 설정 | 리포지토리를 만들고 codespace를 준비합니다 | +| [1. 사용자 지정 지침][ex1] | 컨텍스트 | cloud agent가 따를 사용자 지정 지침을 추가합니다 | +| [2. Cloud agent][ex2] | 비동기 에이전트 | 이슈를 GitHub Copilot cloud agent에 할당합니다 | +| [3. 사용자 지정 에이전트][ex3] | 특화된 에이전트 | 사용자 지정 에이전트를 검토하고 사용합니다 | +| [4. 에이전트 관리][ex4] | 모니터링 | 에이전트 세션을 모니터링하고 안내합니다 | +| [5. 반복 개선][ex5] | 검토 | PR을 검토하고 Copilot의 작업을 반복 개선한 뒤 다음 단계를 선택합니다 | + +## 사전 준비 + +이 워크숍에 참여하기 전에 다음을 준비합니다. + +- [ ] 활성 **Copilot Student, Pro, Pro+, Business 또는 Enterprise** 플랜이 있는 GitHub 계정 +- [ ] 계정 또는 조직에서 GitHub Copilot cloud agent가 활성화되어 있어야 합니다. + +> [!TIP] +> 유료 플랜이 없습니까? 인증된 학생은 [GitHub Education][callout-student-plan-education]을 통해 GitHub Copilot을 무료로 사용할 수 있습니다. **Copilot Student** 플랜에는 이 워크숍에서 사용하는 agent, MCP, 코드 검토, Copilot CLI 기능이 포함되어 있으므로 모든 실습 과정을 완료할 수 있습니다. + +[callout-student-plan-education]: https://github.com/education/students + +> [!NOTE] +> Cloud agent는 **Copilot Student, Pro, Pro+, Business, Enterprise** 플랜에서 사용할 수 있습니다. Copilot Free 플랜에서는 사용할 수 없습니다. Copilot Business 또는 Enterprise를 사용하는 경우 관리자가 조직에서 cloud agent를 활성화해야 합니다. + +> [!NOTE] +> 이 과정에서는 MCP를 다루지 않습니다. Copilot에서 MCP 서버를 사용하는 방법을 알아보려면 [CLI 과정][cli] 또는 [VS Code 과정][vscode]을 참조합니다. + +## 시작하기 + +**[연습 0: 사전 준비부터 시작 →][ex0]** + +[ex0]: 0-prerequisites/ +[ex1]: 1-custom-instructions/ +[ex2]: 2-cloud-agent/ +[ex3]: 3-custom-agents/ +[ex4]: 4-managing-agents/ +[ex5]: 5-iterating/ +[cli]: ../cli/ +[vscode]: ../vscode/ diff --git a/docs/ko-kr/real-world-development/vscode/0-prerequisites.md b/docs/ko-kr/real-world-development/vscode/0-prerequisites.md new file mode 100644 index 00000000..f48c7bcf --- /dev/null +++ b/docs/ko-kr/real-world-development/vscode/0-prerequisites.md @@ -0,0 +1,92 @@ +--- +title: "연습 0: 사전 준비" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +VS Code 연습을 시작하기 전에 필요한 사항을 준비합니다. Tailspin Toys 리포지토리의 복사본을 만들고 [Codespace][codespaces]를 시작한 뒤 편집기에서 GitHub Copilot Chat이 작동하는지 확인합니다. + +## 실습용 리포지토리 설정하기 + +코드를 작성할 리포지토리 복사본을 만들기 위해 [템플릿][template-repository]을 사용합니다. 새 리포지토리에는 실습에 필요한 모든 파일이 포함됩니다. + +1. 새 브라우저 창에서 [Tailspin Toys 템플릿][tailspin-template]으로 이동합니다. +2. 실습 리포지토리 페이지에서 **Use this template**을 선택한 다음 **Create a new repository**를 선택하여 리포지토리 복사본을 만듭니다. + + ![Use this template 버튼](../../../_images/ex0-use-template.png) + +3. GitHub 또는 Microsoft가 진행하는 행사에서 워크숍을 수행하는 경우 멘토의 안내를 따릅니다. 그렇지 않다면 GitHub Copilot을 사용할 수 있는 조직에 새 리포지토리를 만듭니다. + + ![리포지토리 템플릿 설정을 입력하는 화면](../../../_images/ex0-repository-settings.png) + +4. 나중에 참조할 수 있도록 생성한 리포지토리 경로(**organization-or-user-name/repository-name**)를 기록해 둡니다. + +> [!NOTE] +> **백로그 준비 완료** +> +> 템플릿에서 리포지토리를 만들면 GitHub 이슈 백로그가 자동으로 생성됩니다. 워크숍 전체에서 해당 이슈를 사용하므로 직접 등록할 필요가 없습니다. + +## Codespace 만들기 + +이제 Codespace에서 실습을 진행합니다. + +[GitHub Codespaces][codespaces]는 브라우저에서 코드를 작성하고 실행하고 디버그할 수 있는 클라우드 기반 개발 환경입니다. 여러 프로그래밍 언어, 확장, 도구를 지원하는 완전한 기능의 IDE를 제공합니다. + +1. 방금 만든 리포지토리로 이동합니다. +2. 녹색 **Code** 버튼을 선택합니다. + + ![Code 버튼 선택](../../../_images/ex0-code-button.png) + +3. **Codespaces** 탭을 선택하고 **+** 버튼을 선택해 새 Codespace를 만듭니다. + + ![새 Codespace 만들기](../../../_images/ex0-create-codespace.png) + +Codespace를 만드는 데 몇 분 정도 걸릴 수 있지만 모든 서비스를 수동으로 설치하는 것보다 훨씬 빠릅니다. 기다리는 동안 GitHub Copilot의 다른 기능을 살펴볼 수 있으며, 다음 단계에서 이어서 알아봅니다. + +> [!CAUTION] +> 이후 연습에서 Codespace를 다시 사용합니다. 지금은 브라우저 탭에서 열린 상태로 둡니다. + +> [!NOTE] +> 이 워크숍은 Codespace 또는 로컬 [dev container][dev-containers]에서 실행하도록 구성되어 있습니다. 두 환경 모두 원활하게 진행하는 데 필요한 사전 준비 항목을 제공합니다. 로컬에서 실행하려면 복제한 리포지토리를 VS Code에서 열고 메시지가 표시되면 **Reopen in Container**를 선택합니다. VS Code가 Codespace와 동일한 dev container를 빌드합니다. + +[codespaces]: https://github.com/features/codespaces +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers + +## GitHub Copilot Chat 및 에이전트 모드 사용하기 + +GitHub Copilot Chat 에이전트 모드를 사용하려면 IDE에 GitHub Copilot Chat 확장이 설치되어 있어야 합니다. GitHub Codespace를 사용한다면 일반적으로 이미 설치되어 있습니다. + +> [!TIP] +> GitHub Copilot Chat 확장이 설치되어 있지 않다면 [Visual Studio Code Marketplace에서 설치][copilot-chat-extension]합니다. 또는 Visual Studio Code에서 Extensions 보기를 열고 **GitHub Copilot Chat**을 검색한 다음 **Install**을 선택합니다. + +확장을 설치한 뒤 GitHub 계정으로 인증해야 할 수 있습니다. + +1. Codespace로 돌아갑니다. +2. 편집기 오른쪽에 Copilot Chat이 보이지 않으면 Codespace 위쪽의 **Copilot Chat** 아이콘을 선택합니다. +3. Copilot Chat 창에서 `Hello world`와 같은 메시지를 입력하고 Enter를 누릅니다. 그러면 Copilot Chat이 활성화됩니다. +4. 인증되지 않았다면 GitHub 계정으로 로그인하라는 메시지가 표시됩니다. 안내에 따라 인증합니다. + + ![Copilot Chat 인증 프롬프트 예시](../../../_images/ex1-copilot-authentication.png) + +5. 인증이 완료되면 Copilot Chat 창이 표시됩니다. + +## 요약 + +실습용 리포지토리의 복사본을 만들고 코드를 작성할 Codespace를 준비하기 시작했습니다. + +## 다음 단계 + +Copilot을 사용해 프로젝트의 규칙을 알려 주는 [연습 1 - 사용자 지정 지침][next-lesson]을 진행합니다. + +## 리소스 + +- [GitHub Codespaces 개요][codespaces] +- [템플릿에서 리포지토리 만들기][template-repository] +- [Codespaces 시작하기][codespaces-quickstart] + +[tailspin-template]: https://github.com/github-samples/tailspin-toys +[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository +[codespaces-quickstart]: https://docs.github.com/codespaces/getting-started/quickstart +[copilot-chat-extension]: https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat +[next-lesson]: ../1-custom-instructions/ diff --git a/docs/ko-kr/real-world-development/vscode/1-custom-instructions.md b/docs/ko-kr/real-world-development/vscode/1-custom-instructions.md new file mode 100644 index 00000000..45e66edc --- /dev/null +++ b/docs/ko-kr/real-world-development/vscode/1-custom-instructions.md @@ -0,0 +1,254 @@ +--- +title: "연습 1 - 사용자 지정 지침(VS Code)" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +[← 이전 레슨: 사전 준비][previous-lesson] · [다음 레슨: 에이전트 모드 →][next-lesson] + +생성형 AI를 사용할 때 컨텍스트가 중요합니다. 특정 방식으로 작업해야 하거나 Copilot이 알아야 할 배경 정보가 있다면 해당 정보를 사용할 수 있도록 해야 합니다. Copilot과 특정 컨텍스트를 공유하는 방법은 여러 가지가 있습니다. 그중 [지침 파일][instruction-files]은 코드 생성 방법을 안내하는 대표적인 방법입니다. + +이 연습에서는 다음을 수행합니다. + +- 리포지토리 사용자 지정 지침과 경로 범위 지침 파일을 통해 프로젝트 컨텍스트, 코딩 지침, 문서 표준이 Copilot에 전달되는 방식을 살펴봅니다. +- 현재 지침을 적용해 필터링을 위한 첫 데이터 기능인 퍼블리셔 도우미를 생성합니다. +- `.github/copilot-instructions.md`에 새로운 리포지토리 전체 표준을 추가합니다. +- 동일한 프롬프트를 다시 실행해 생성된 코드에 새 표준이 적용되는지 확인합니다. +- 지침 업데이트와 필터링 기능을 `main`에 커밋하여 다음 연습에서 업데이트된 지침을 사용할 수 있도록 합니다. + +> [!CAUTION] +> 생성된 코드가 설정한 표준과 다를 수 있습니다. Copilot은 비결정적으로 작동합니다. 이 연습의 목적은 문자를 하나하나 일치시키는 것이 아니라 지침을 업데이트한 뒤 동작이 어떻게 달라지는지 확인하는 것입니다. + +## 지침 파일 + +### 시나리오 + +Tailspin Toys에는 개발 관행에 관한 표준과 요구 사항이 있습니다. + +- 데이터 계층에는 항상 단위 테스트가 필요합니다. +- UI는 어두운 모드와 현대적인 느낌을 사용해야 합니다. +- 코드에는 TSDoc 문서 주석을 추가해야 합니다. +- 각 파일의 맨 위에는 파일의 역할을 설명하는 주석 블록을 추가해야 합니다. + +지침 파일을 사용해 Copilot이 이러한 관행에 따라 작업하는 데 필요한 정보를 제공합니다. + +### 사용자 지정 지침 + +사용자 지정 지침은 Copilot에 컨텍스트와 선호 사항을 제공하여 코딩 스타일과 요구 사항을 더 잘 이해하도록 합니다. 코딩 규칙, 라이브러리, 포함하려는 주석 유형을 지정할 수 있습니다. 리포지토리 전체 또는 특정 파일 유형에 적용되는 작업별 지침 파일을 만들 수 있습니다. + +지침 파일에는 다음 두 가지 유형이 있습니다. + +- `.github/copilot-instructions.md`는 리포지토리의 **모든** 요청에 Copilot이 사용하는 단일 지침 파일입니다. 대부분의 Copilot Chat 또는 CLI 요청과 관련된 프로젝트 수준 컨텍스트를 작성합니다. 기술 스택, 개발 중인 프로젝트 개요, 모범 사례, 전역 지침 등을 포함할 수 있습니다. +- `.github/instructions/*.instructions.md` 파일은 특정 작업이나 파일 유형에 대한 지침을 제공합니다. TypeScript나 Astro 같은 특정 언어나 UI 컴포넌트 또는 새 단위 테스트 작성 같은 작업에 대한 지침을 만들 수 있습니다. + +> [!NOTE] +> IDE에서는 지침 파일을 Copilot Chat의 코드 생성에만 사용하며, 코드 완성이나 다음 편집 제안에는 사용하지 않습니다. +> +> Copilot Chat, Copilot CLI, Copilot cloud agent는 코드 생성 시 리포지토리 수준 지침과 `applyTo` frontmatter가 있는 `*.instructions.md` 파일을 함께 사용합니다. +> +> Copilot은 AGENTS.md 및 CLAUDE.md 파일을 비롯한 다른 형식의 지침 파일도 [지원합니다][custom-instructions-support]. + +### 지침 파일 관리 모범 사례 + +지침 파일을 만드는 방법에 관한 자세한 설명은 이 워크숍의 범위를 벗어납니다. 샘플 프로젝트에는 일반적인 접근 방식을 보여 주는 예제가 포함되어 있습니다. 큰 틀에서는 다음과 같이 관리합니다. + +- `copilot-instructions.md`에는 개발 중인 내용, 프로젝트 구조, 전역 코딩 표준 등 프로젝트 수준의 지침을 작성합니다. +- `*.instructions.md` 파일에는 단위 테스트, Astro 컴포넌트, 데이터 계층과 같은 파일 유형별 또는 특정 작업 지침을 작성합니다. +- 자연어로 지침을 명확하게 작성하고, 좋은 코드와 피해야 할 코드 예제를 제공합니다. + +지침 파일을 만드는 한 가지 정답이나 AI를 사용하는 한 가지 정답은 없습니다. 직접 실험하며 프로젝트에 맞는 방법을 찾습니다. + +> [!TIP] +> GitHub Copilot을 사용하는 모든 프로젝트에는 체계적인 지침 파일 모음이 필요합니다. 이 프로젝트에는 [UI 업데이트][ui-instructions] 및 [Astro][astro-instructions]를 비롯한 여러 작업에 대한 지침 파일이 있습니다. +> +> Copilot에 지침 파일 생성을 요청할 수도 있습니다. 환경마다 제공 방법이 다릅니다. 예를 들어 VS Code에서는 **Configure Chat → Generate Agent Instructions**, Copilot CLI에서는 `/init`을 사용할 수 있습니다. 사용 중인 환경의 레슨에서 관련 방법을 안내합니다. +> +> 시작 템플릿을 찾고 있다면 지침 파일, 사용자 지정 에이전트, 기타 리소스가 있는 [awesome-copilot][awesome-copilot] 리포지토리를 살펴봅니다. + +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[awesome-copilot]: https://github.com/github/awesome-copilot +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support + +## 이 프로젝트의 사용자 지정 지침 파일 살펴보기 + +이 리포지토리에는 핵심 `copilot-instructions.md` 파일 하나와 다양한 작업을 위한 `*.instructions.md` 파일 모음이 있습니다. 편집기 또는 GitHub 웹 UI에서 파일을 엽니다. + +1. `.github/copilot-instructions.md`를 엽니다. +2. 프로젝트에 대한 간단한 설명과 **Agent notes**, **Code standards**, **Scripts**, **Repository Structure** 같은 섹션을 살펴봅니다. **Code standards** 아래의 **GitHub Actions Workflows** 지침도 확인합니다. 이 지침은 Copilot과 상호 작용할 때마다 적용됩니다. +3. `.github/instructions` 폴더를 열어 파일을 살펴봅니다. Astro 파일, Drizzle 데이터 계층, 테스트 등에 대한 지침이 있습니다. +4. `.github/instructions/unit-tests.instructions.md`를 엽니다. 맨 위의 `applyTo` 필드는 리포지토리 루트에 상대적인 glob을 지정합니다. 예를 들어 `**/*.test.ts`와 일치하는 TypeScript 테스트 파일에 지침이 적용됩니다. +5. 단위 테스트 작성에 관한 프로젝트별 지침을 확인합니다. +6. 마지막으로 `.github/instructions/drizzle.instructions.md`를 열고 맨 아래로 이동합니다. `unit-tests.instructions.md` 같은 다른 지침 파일과 프로젝트 파일을 가리키는 링크를 확인합니다. 이를 사용해 큰 지침을 작고 재사용 가능한 파일로 나누고 Copilot이 참고할 예제를 지정할 수 있습니다. 이 파일의 경로는 리포지토리 루트가 아니라 지침 파일 위치를 기준으로 합니다. + +> [!NOTE] +> `copilot-instructions.md`의 **Code formatting requirements** 섹션에는 프로젝트 코딩 표준이 있지만, 아직 코드 문서화에 대한 요구 사항은 없습니다. 다음 단계에서 TSDoc 문서 주석과 파일 머리 주석에 관한 규칙을 추가합니다. + +## 변경 사항을 위한 브랜치 만들기 + +변경 사항을 별도 브랜치에서 관리합니다. + +1. 이전 연습에서 사용한 Codespace로 돌아갑니다. +2. Mac에서는 Control+\`를, Windows/Linux에서는 Ctrl+\`를 눌러 새 터미널을 엽니다. +3. 새 브랜치를 만들고 전환합니다. + + ```bash + git checkout -b custom-instructions + ``` + +## 지침 업데이트 *전* Copilot Chat 사용하기 + +> [!TIP] +> **Copilot Chat 열기** +> +> 아래 연습을 시작하기 전에 Codespace로 돌아가 Copilot Chat 패널을 열고 **New Chat**을 선택하여 새 대화를 시작합니다. 모드와 모델 선택은 연습마다 다를 수 있습니다. 관련 단계에서 안내합니다. + +사용자 지정 지침의 영향을 확인하려면 먼저 현재 지침이 적용된 상태에서 프롬프트를 보냅니다. 다음 단계에서 지침을 업데이트한 뒤 동일한 프롬프트를 다시 보내 결과를 비교합니다. + +1. 이전 연습에서 열었던 편집기 탭을 닫아 Copilot이 필요한 컨텍스트만 사용하도록 합니다. +2. Copilot이 도우미를 작성할 위치를 알 수 있도록 `src/lib/publishers.ts`를 엽니다. +3. Chat 보기의 에이전트 드롭다운에서 **Agent**를 선택하여 Copilot이 파일을 수정할 수 있도록 합니다. + + ![Chat 보기의 에이전트 선택기를 보여 주는 스크린샷](../../../_images/shared-chat-mode-selector.png) + +4. 다음 프롬프트를 입력합니다. + + ```plaintext + src/lib/publishers.ts에 이름과 ID를 포함한 모든 퍼블리셔 목록을 반환하는 데이터 접근 도우미를 만들거나 업데이트해 주세요. 파일에 변경 사항을 적용해 주세요. + ``` + +5. Copilot이 프로젝트를 살펴보고 도우미 파일과 테스트 등을 업데이트합니다. +6. 제안된 도우미가 첫 번째 인수로 `db` 클라이언트를 받고 형식이 지정된 퍼블리셔 배열을 반환하는지 살펴봅니다. 이는 `src/lib/*.ts`에 적용되는 `.github/instructions/drizzle.instructions.md`의 데이터 계층 규칙에 따른 것입니다. +7. 제안된 코드에 TSDoc 문서 주석과 파일 머리 주석이 **없는지** 확인합니다. + +> [!CAUTION] +> Copilot은 확률적으로 작동하므로 지침이 없어도 문서 주석을 추가할 수 있습니다. 이 경우에도 지침을 업데이트한 뒤 출력의 일관성이 어떻게 개선되는지 살펴보면 됩니다. + +## 새로운 리포지토리 표준 추가하기 + +`.github/copilot-instructions.md`는 Copilot에 프로젝트 수준 정보를 제공합니다. 코드 제안을 개선하기 위해 리포지토리 코딩 표준에 문서 주석 규칙을 추가합니다. + +1. `.github/copilot-instructions.md`를 다시 엽니다. +2. 27행 근처의 **Code formatting requirements** 섹션을 찾습니다. 코드 생성 도우미에 문서 주석이 없었던 이유는 아직 이 규칙이 없기 때문입니다. +3. 기존 표준 바로 아래에 다음 Markdown을 추가하여 파일 머리 주석과 TSDoc 문서 주석을 요청합니다. + + ```markdown + - 내보내는 모든 함수에는 목적, 매개 변수, 반환 값을 설명하는 TSDoc 주석을 작성합니다. + - 가져오기 구문이나 코드 앞에 파일의 목적을 설명하는 주석 블록을 추가합니다. + ``` + +4. `copilot-instructions.md`를 저장합니다. + +> [!TIP] +> 앞선 레슨에서 살펴봤듯이 리포지토리 수준 파일(`.github/copilot-instructions.md`)에는 전역 지침을, `*.instructions.md` 파일에는 특정 언어, 파일 유형, 작업 지침을 작성할 수 있습니다. 문서 주석 규칙과 같은 프로젝트 전체 표준은 리포지토리 수준 파일에 두는 것이 적절합니다. + +## 프롬프트를 다시 실행하고 변경 사항 살펴보기 + +1. Copilot Chat으로 돌아가 **New Chat**을 선택해 대화 컨텍스트를 비웁니다. +2. `src/lib/publishers.ts`를 다시 선택해 Copilot이 올바른 파일을 대상으로 하도록 합니다. +3. 이전과 **동일한 프롬프트**를 입력합니다. + + ```plaintext + src/lib/publishers.ts에 이름과 ID를 포함한 모든 퍼블리셔 목록을 반환하는 데이터 접근 도우미를 만들거나 업데이트해 주세요. 파일에 변경 사항을 적용해 주세요. + ``` + +4. 제안된 파일 맨 위에 다음과 비슷한 주석 블록이 추가되었는지 확인합니다. + + ```typescript + /** + * Tailspin Toys 크라우드 펀딩 플랫폼의 퍼블리셔 데이터 접근 도우미입니다. + * 데이터베이스에서 퍼블리셔 정보를 가져오는 기능을 제공합니다. + */ + ``` + +5. 제안된 함수에 다음과 비슷한 TSDoc 주석이 추가되었는지 확인합니다. + + ```typescript + /** + * ID와 이름을 포함한 모든 퍼블리셔 목록을 반환합니다. + * + * @param db - Drizzle 데이터베이스 클라이언트입니다. + * @returns 퍼블리셔 객체 배열을 반환하는 Promise입니다. + */ + ``` + +새 프로젝트 표준을 추가하여 Copilot을 안내하고 다음 연습에서 사용할 실제 코드에 적용했습니다. + +## 지침 변경과 브랜치 푸시하기 + +지침 파일도 다른 리포지토리 자산과 마찬가지로 버전 관리합니다. 변경 사항을 커밋하고 브랜치를 푸시합니다. + +1. Mac에서는 Control+\`를, Windows/Linux에서는 Ctrl+\`를 눌러 Codespace에서 새 터미널 창을 엽니다. +2. 다음 명령을 실행해 지침 변경과 도우미 파일이 있는지 확인합니다. + + ```bash + git status + ``` + +3. 터미널에서 지침 변경, 도우미 코드, Copilot이 수정한 테스트 등 관련 파일을 스테이징하고 커밋합니다. + + ```bash + git add .github/copilot-instructions.md src/lib/publishers.ts + # git status에 테스트 같은 지원 변경 사항이 표시되면 해당 파일도 추가합니다. + git commit -m "Add doc comment standards and publishers helper foundation" + ``` + +4. 브랜치를 리포지토리에 푸시합니다. + + ```bash + git push -u origin custom-instructions + ``` + +## 풀 리퀘스트 만들고 병합하기 + +브랜치를 푸시했으니 지침 표준 이슈와 연결된 풀 리퀘스트를 만듭니다. 직접 만들 수도 있지만 이미 연결된 GitHub 도구를 사용해 Copilot에 이슈를 찾고 이슈를 해결하는 PR을 만든 뒤 병합하도록 요청합니다. + +> [!NOTE] +> 이 연습은 Copilot이 사용자를 대신해 GitHub 작업을 수행하는 첫 번째 단계입니다. 프로젝트 템플릿에 GitHub 도구가 이미 연결되어 있어 별도로 설정할 필요가 없습니다. Copilot이 처음으로 도구를 사용하면 VS Code에서 GitHub 로그인을 요청할 수 있습니다. 안내에 따라 로그인합니다. 이후 연습에서 Model Context Protocol을 살펴봅니다. + +1. Codespace에서 Copilot Chat을 엽니다. +2. Control+Command+I(Mac) 또는 Ctrl+Alt+I(Windows/Linux)를 눌러 Copilot Chat 보기를 열고 에이전트 선택기에서 **Agent**가 선택되었는지 확인합니다. +3. Copilot에 지침 파일 업데이트와 필터링 작업을 위한 퍼블리셔 도우미를 설명하는 PR을 현재 브랜치에서 만들고 해당 이슈를 해결하도록 요청합니다. + + ``` + 지침 파일 업데이트와 관련된 이슈를 찾아 주세요. 현재 브랜치에서 새 PR을 만들고 해당 이슈를 해결한다고 명시해 주세요. 다음 필터링 작업을 위한 퍼블리셔 도우미 기반을 추가한 내용도 포함해 주세요. + ``` + +4. Copilot이 이슈를 찾고 PR을 만드는 과정을 살펴봅니다. +5. Copilot이 GitHub 작업을 대신 수행하도록 **Allow**를 요청하면 명령을 검토하고 허용할지 결정합니다. +6. PR이 만들어지면 Copilot에 병합한 뒤 로컬 브랜치를 `main`으로 전환하도록 요청합니다. + + ``` + PR을 main에 병합해 주세요. 그런 다음 로컬에서 main으로 돌아가 최신 코드를 가져와 최신 상태로 맞춰 주세요. + ``` + +7. Copilot이 GitHub 작업과 셸 명령을 수행하도록 **Allow**를 요청하면 명령을 검토하고 허용할지 결정합니다. + +GitHub Copilot의 도움으로 풀 리퀘스트를 만들고 병합했습니다. + +## 요약 및 다음 단계 + +이 프로젝트에서 Copilot이 지침 파일을 활용하는 방식을 살펴본 뒤 VS Code에서 Copilot Chat을 사용해 다음을 수행했습니다. + +- 현재 지침이 적용된 코드 생성 프롬프트를 보내 결과를 살펴봤습니다. +- `.github/copilot-instructions.md`에 새로운 리포지토리 전체 표준을 추가했습니다. +- 동일한 프롬프트를 다시 실행해 새 표준이 코드에 반영되는지 확인했습니다. +- 지침 업데이트와 퍼블리셔 도우미를 `main`에 커밋하여 다음 연습에서 사용할 수 있도록 했습니다. + +다음으로 [에이전트 모드][next-lesson]에서 지침을 사용하여 코드베이스 전반에 걸친 기능을 추가합니다. + +## 리소스 + +- [GitHub Copilot 사용자 지정 지침 파일][instruction-files] +- [사용자 지정 지침 작성 모범 사례][instructions-best-practices] +- [Copilot을 위한 더 나은 사용자 지정 지침 작성 팁 5가지][copilot-instructions-five-tips] +- [GitHub Copilot 개인 사용자 지정 지침][personal-instructions] +- [Awesome Copilot — 지침 파일 및 기타 리소스 모음][awesome-copilot] + +[previous-lesson]: ../0-prerequisites/ +[next-lesson]: ../2-agent-mode/ +[instruction-files]: https://code.visualstudio.com/docs/copilot/copilot-customization +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[personal-instructions]: https://docs.github.com/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot +[copilot-instructions-five-tips]: https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/ diff --git a/docs/ko-kr/real-world-development/vscode/2-agent-mode.md b/docs/ko-kr/real-world-development/vscode/2-agent-mode.md new file mode 100644 index 00000000..0e0f298b --- /dev/null +++ b/docs/ko-kr/real-world-development/vscode/2-agent-mode.md @@ -0,0 +1,197 @@ +--- +title: "연습 2 - Copilot 에이전트 모드로 새 기능 추가하기" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +애플리케이션을 조금만 변경해도 여러 파일을 수정하고 테스트를 실행해야 하는 경우가 많습니다. 개발자는 관련 파일을 찾고 변경하고 테스트를 실행하고 오류를 수정하고 빠뜨린 파일을 찾아 다시 변경하는 등의 작업을 반복합니다. + +이럴 때 Copilot 에이전트 모드를 사용할 수 있습니다. + +Copilot 에이전트 모드는 IDE에서 더 자율적으로 작업하도록 설계되었습니다. 개발자처럼 기존 프로젝트 구조를 살펴보고 필요한 변경을 적용하고 테스트를 실행하며 발견된 문제를 자동으로 수정합니다. 에이전트 모드를 사용해 사이트에 기능을 추가하는 방법을 알아봅니다. + +> [!NOTE] +> 이름은 비슷하지만 에이전트 모드와 cloud agent는 서로 다른 방식으로 작동합니다. 에이전트 모드는 IDE에서 작업하고 빠르게 피드백을 주고받습니다. Cloud agent는 이슈와 풀 리퀘스트로 상호 작용하며 팀원처럼 비동기적으로 작업합니다. + +이 연습에서는 다음을 수행합니다. + +- Copilot 에이전트 모드가 프로젝트를 살펴보고 관련 파일을 찾아 변경을 조율하는 방법을 알아봅니다. +- GitHub Copilot 에이전트 모드로 UI와 데이터 계층 전반에 기능을 구현합니다. +- 코드베이스에 병합하기 전에 Copilot 에이전트 모드가 생성한 변경 사항과 테스트를 검토합니다. + +## 시나리오 + +게임 목록이 늘어나면서 사용자가 카테고리와 퍼블리셔별로 게임을 필터링할 수 있어야 합니다. 이전 연습에서 퍼블리셔 도우미를 추가했으며, 이제 Copilot 에이전트 모드로 나머지 데이터 계층, UI, 테스트 작업을 완료합니다. + +## Tailspin Toys 웹사이트 실행하기 + +변경 사항을 적용하기 전에 Tailspin Toys 웹사이트를 살펴보고 현재 기능을 확인합니다. + +이 웹사이트는 개발자 테마의 보드게임 크라우드 펀딩 플랫폼입니다. 사용자가 게임 목록과 상세 정보를 볼 수 있습니다. 단일 Astro 앱으로 구성되어 있으며 빌드 시 페이지를 정적 HTML로 렌더링합니다. 페이지는 frontmatter에서 Drizzle ORM을 통해 로컬 SQLite 데이터베이스를 직접 조회합니다. 별도 백엔드 API나 클라이언트 UI 프레임워크는 없습니다. 재사용 가능한 데이터 접근 도우미는 `src/lib/`에 있고, 상호 작용 기능은 표준 DOM API를 사용하는 작은 범위의 Astro `