Настройка модернизации GitHub Copilot

Модернизация GitHub Copilot является расширяемой. Агент предоставляет несколько точек настройки для кодирования шаблонов обновления вашей команды, принудительного применения стандартов кодирования во время обновлений и определения новых рабочих процессов обновления.

Обзор точек настройки

Точка настройки Объем Сохраняемость Effort
Инструкции чата За сеанс или обновление Сеанс или сохранённый файл в scenario-instructions.md Минимальный
Артефакты сценария За каждое обновление Длительность обновления Низкий
Пользовательские навыки Командная или личная Постоянное (зарегистрировано в репозитории или профиле пользователя) Средняя
Пользовательские сценарии Командная или личная Постоянный Высокий

Подсказка

Начните с инструкций чата и редактирования артефактов сценария. Перейдите к пользовательским навыкам, когда вы обнаружите, что повторяете те же инструкции во время обновлений.

Настройка с помощью чата

Настройте поведение агента в режиме реального времени с помощью естественной беседы. Агент либо немедленно применяет инструкцию, либо сохраняет ее scenario-instructions.md для последующего использования.

Вы говорите Что происходит
"Теперь всегда фиксируйте после каждой задачи" Сохранено в scenario-instructions.md качестве предпочтения выполнения
"Пропустить проверку теста для этой задачи" Применяется немедленно только к текущей задаче
"Используйте стратегию снизу вверх для этого обновления" Влияет на стратегию этапа планирования
"Не касайтесь проекта Logging" Добавлено в настройки; Агент исключает этот проект
"Всегда использовать пространства имен с областью действия файла" Сохранено в качестве стандартного предпочтения кодирования
"Пауза после каждой задачи для моей проверки" Сохранено в качестве предпочтения стиля выполнения

Подсказка

Чтобы сделать инструкцию сохраняемой на протяжении всего обновления, сформулируйте её в качестве постоянного предпочтения: "Отныне, всегда..." или "Для всех задач в этом обновлении...". Агент записывает инструкцию в scenario-instructions.md.

Изменение артефактов сценария

При запуске обновления агент создает рабочую область в .github/upgrades/{scenarioId}/. Папка обновления содержит редактируемые артефакты, которые напрямую управляют поведением агента.

scenario-instructions.md

Файл scenario-instructions.md — это постоянная память агента для обновления. Агент всегда загружает этот файл в контекст, поэтому все, что вы пишете здесь, напрямую влияет на каждое решение агента.

Добавьте такие разделы, чтобы помочь агенту:

## User Preferences

### Technical Preferences
- Always prefer explicit type declarations over `var`
- Use `ILogger<T>` instead of `ILoggerFactory` for dependency injection
- Target .NET 10 for all projects
- Keep Newtonsoft.Json in the shared library (don't migrate to System.Text.Json)

### Execution Style
- **Pace**: Methodical
- **Pause Points**: After assessment, after each task group

### Custom Instructions

#### 02-common-lib
- Skip the database migration for now — it has external dependencies
- Use the connection string from `appsettings.Production.json` for testing

#### 03-data-layer
- Keep existing repository interfaces during migration
- Preserve all Entity Framework conventions

## Key Decisions Log
- 2025-01-15: Keep Newtonsoft.Json in SharedLib — third-party SDK requires it
- 2025-01-16: Skip database project — DBA team will handle separately

plan.md

Файл plan.md определяет задачи и их область. Измените plan.md на:

  • Переупорядочение задач для изменения последовательности выполнения.
  • Добавьте задачи, которые агент не планировал.
  • Удалите задачи, которые не применяются.
  • Добавьте заметки для предоставления контекста для определенных задач.

Отдельные файлы задач

В tasks/{taskId}/task.md содержатся спецификация задачи и рабочие заметки. Измените эти файлы следующими способами:

  • Уточнение области задачи.
  • Добавьте контекст для конкретного домена, который пропустил агент.
  • Укажите примеры кода для желаемого результата.

Это важно

Средства агента управляют tasks.md, как панелью мониторинга в режиме только для чтения. Не редактируйте tasks.md напрямую. Агент перезаписывает любые изменения, сделанные вручную. Вместо этого измените scenario-instructions.md или отдельные task.md файлы.

Создайте пользовательские навыки

Навыки — это основа для расширения функциональности агента. Навык — это файл Markdown с заголовком метаданных, который учит агента об обработке определенного обновления, шаблона или задачи.

Где разместить пользовательские навыки

Местоположение Объем Используйте, когда
.github/skills/my-skill.md Репозиторий (общий доступ к команде) Шаблоны обновления на уровне команды
.github/upgrades/skills/my-skill.md Репозиторий (для конкретного обновления) Навыки, относящиеся к сценариям обновления
%UserProfile%/.copilot/skills/my-skill.md Профиль пользователя (персональный, все репозитории) Личные предпочтения и шаблоны

Подсказка

Навыки уровня репозитория (.github/skills/) являются наиболее распространенным выбором. Они путешествуют с кодом, и вся команда может использовать их.

Структура файла навыка

Каждый файл навыка состоит из двух частей: заголовка метаданных (который агент использует для понимания того, когда применяется навык) и текста Markdown (инструкции, которым агент следует).

---
name: migrating-foobar-v2-to-v3
description: >
  Migrate our internal FooBar library from v2 to v3. Activates when
  FooBar.v2 NuGet package is detected, or when asked to "upgrade FooBar",
  "migrate FooBar", or "update FooBar library".
metadata:
  discovery: lazy
  traits: .NET | CSharp
---

# Migrating FooBar Library v2 to v3

## Overview

FooBar v3 introduces a new async-first API surface. This skill guides the
agent through replacing synchronous FooBar.v2 calls with their v3 async
equivalents, updating configuration, and verifying behavior.

## Workflow

1. **Identify FooBar.v2 references**
   - Search for `PackageReference` elements referencing `FooBar.v2`
   - Locate all `using FooBar.V2;` directives

2. **Update package references**
   - Replace `FooBar.v2` with `FooBar.v3` in all `.csproj` files
   - Run `dotnet restore` to verify resolution

3. **Migrate API calls**
   - Replace `FooBarClient.Send(...)` with `await FooBarClient.SendAsync(...)`
   - Replace `FooBarConfig.LoadFromFile(...)` with `FooBarConfig.LoadFromJsonAsync(...)`
   - Update method signatures to `async Task` where needed

4. **Update configuration**
   - Rename `foobar.config` to `foobar.json`
   - Migrate XML config entries to JSON format

5. **Verify**
   - Build the project: `dotnet build`
   - Run existing tests: `dotnet test`
   - Verify no remaining references to `FooBar.V2` namespace

## Success Criteria

- [ ] No references to `FooBar.v2` NuGet package remain
- [ ] All `FooBar.V2` namespace usages replaced with `FooBar.V3`
- [ ] Project builds without errors
- [ ] All existing tests pass

## Error Handling

- If `FooBar.v3` is not available in the configured NuGet feeds, instruct
  the user to add the internal feed
- If async migration causes deadlocks in legacy synchronous code paths,
  wrap calls with `.GetAwaiter().GetResult()` and add a TODO comment

Поля метаданных

Поле Обязательный Описание
name Да Уникальный идентификатор в kebab-case. Начните с деепричастия (например, upgrading-, converting-). Не более 64 символов.
description Да Определяет, когда агент загружает навык. Включите фразы триггера, такие как слова и шаблоны, которые должны активировать навык.
metadata.discovery Нет Определяет, когда загружается навык: preload (всегда доступно), lazy (по запросу при совпадении описания, используется по умолчанию и рекомендуется), или scenario (определяет оркестратор рабочего процесса).
metadata.traits Нет Ключевые слова, описывающие технологии в проекте, такие как .NET, CSharp, VisualBasic или DotNetCore.

Рекомендации по разработке навыков

  • Будьте конкретными в описании: Включите точные имена пакетов, имена библиотек и фразы триггеров естественного языка, которые могут вводить пользователи.
  • Включите четкие пошаговые рабочие процессы: Нумеруем шаги. Четко укажите, какие файлы необходимо изменить и какие команды следует выполнить.
  • Включите критерии успешности: Без условий успешного выполнения агент не знает, когда остановиться. Используйте флажки или четкий список проверяемых условий.
  • Включить обработку ошибок: Предвидеть распространенные режимы сбоя, такие как отсутствующие пакеты, сбои сборки или неисправные тесты.
  • Сосредоточьтесь на навыках: Один навык на улучшение или тип задачи. Навык обновления FooBar версии 2 до версии 3 лучше, чем "обновление всех внутренних библиотек".
  • Имя с глаголом в форме герундия: Использовать upgrading-foobar-v2-to-v3, а не foobar-upgrade или foobar-v3.
  • Использование обнаружения: используйте lazylazy обнаружение для большинства пользовательских навыков, чтобы избежать раздувания окна контекста агента.

Создание пользовательских сценариев

Для расширенных пользователей, которые хотят определить совершенно новые рабочие процессы обновления, пользовательские сценарии позволяют оркестрировать полный конвейер многоэтапного обновления. Сценарий — это навык с metadata.discovery: scenario, который определяет фазы, которые должен пройти агент.

---
name: migrating-soap-to-rest-api
description: >
  Migrate legacy WCF/SOAP services to ASP.NET Core REST APIs. Activates
  when WCF service references, .svc files, or SOAP clients are detected,
  or when asked to "migrate SOAP to REST", "replace WCF", or "convert
  web services to REST".
metadata:
  discovery: scenario
  traits: .NET | CSharp
  scenarioTraitsSet: [wcf, soap, web-services]
---

# SOAP to REST API Migration

## Pre-initialization

Gather from the user:
- Which SOAP services to migrate (all or specific ones)
- Whether to maintain backward compatibility with a SOAP facade
- Authentication mechanism for the new REST APIs
- API versioning strategy (URL path, header, query string)

## Assessment

Analyze the solution for:
- `.svc` files and WCF service contracts
- WSDL files and service references
- `System.ServiceModel` usage and binding configurations
- Data contracts and their serialization requirements
- Client proxies consuming SOAP services

## Planning

Create tasks in this order:
1. Create shared DTOs — Convert `[DataContract]` types to POCOs
2. Create REST controllers — One controller per `[ServiceContract]`
3. Map operations to HTTP methods
4. Migrate service implementations
5. Update clients — Replace `ChannelFactory`/generated proxies with `HttpClient`
6. Remove WCF infrastructure
7. Add API documentation — Swagger/OpenAPI via Swashbuckle

## Execution

For each service contract:
1. Create a corresponding controller
2. Create a service interface and implementation
3. Register the service in DI
4. Map WCF operations to REST endpoints
5. Update any in-solution clients to use the new REST endpoints
6. Build and run existing tests

Поместите файлы сценариев в .github/skills/ или .github/upgrades/skills/, чтобы агент мог их обнаружить.

Подсказка

Поле scenarioTraitsSet определяет признаки, которые агент использует для сопоставления сценария с характеристиками решения. Эти признаки помогают агенту предложить сценарий при необходимости.

Управление версиями и ветвление

Агент предлагает работать в ветви Git, но у вас есть полный контроль над стратегией:

  • Именование ветви: Сообщите агенту, какое имя ветви следует использовать, или позвольте агенту предложить его.
  • Ветви для каждой задачи: Запросите отдельную ветвь для каждой задачи для детализации проверки.
  • Время фиксации: Выберите, когда агент фиксирует: после каждой завершенной задачи (по умолчанию), только в конце полного обновления или по запросу.
  • Нет системы управления версиями: Агент также работает с папками, отличными от Git, но рекомендует сначала создать резервную копию проекта.

Примеры инструкций чата:

  • "Используйте имя ветви "upgrade/dotnet10" для этого обновления"
  • "Создайте ветвь для каждой задачи, чтобы просмотреть каждую отдельно"
  • "Не закоммитьте, пока я вас об этом не попрошу"
  • "Внесение изменений после каждой задачи с описательным сообщением"

Подсказка

Для крупных обновлений, включающих несколько проектов, ветви, создаваемые для каждой задачи, предоставляют гибкость: вы можете независимо проверять и объединять каждое изменение или откатить одну задачу, не затрагивая остальные.

Приоритет загрузки навыка

Когда агент обнаруживает несколько навыков, он разрешает их с помощью системы приоритета. Источники с более высоким приоритетом переопределяют или дополняют более низкие приоритеты:

Priority Исходный материал Местоположение
5 (самый высокий) Пользовательские навыки (предоставляемые пользователем через API) —
4 Навыки профиля пользователя %UserProfile%/.copilot/skills/
3 Навыки обновления репозитория .github/upgrades/skills/
2 Навыки управления репозиторием .github/skills/
1 (самый низкий) Внедренные навыки (встроенные в агент) —

Агент собирает навыки из всех источников. Если навыки имеют перекрывающиеся области, источники с более высоким приоритетом имеют приоритет. Поле discovery определяет, когда загружается навык. lazy означает «по требованию», когда это актуально, и preload означает «всегда доступен».

Подсказка

Вам не нужно заменить встроенный навык для изменения поведения. Навык репозитория с более высоким приоритетом дополняет встроенный навык, добавляя конкретные соглашения вашей команды на основе базового поведения.

Связанный контент

  • Last updated on