AI에게 구현을 맡기기 전에 결정하고 싶은 것

「記事管理の機能を作って」。AI에 부탁할 때, 이것만으로 시작하고 싶어지는 경우가 있습니다.

하지만 이 요청만으로는 무엇을 저장해야 하는지, 같은 ID가 오면 어떻게 할지, 어디까지 완성되어야 끝인지 결정되지 않습니다. 코드가 만들어진 후에 그 판단까지 처음부터 다시 시작하는 것은 힘든 일입니다.

처음부터 세밀한 사양서(仕様書)를 준비할 필요는 없습니다. 우선 이번에 만들 범위와, 완성된 것을 어떻게 확인할지 짧게 적어봅시다. 기존 프로젝트에서 작은 기능을 추가할 때의 진행 방식을 소개합니다.

'완성'의 기준을 먼저 작성하기

GitHub의 Copilot cloud agent용 자료에서도 해결하고 싶은 문제, 완료 조건(完了条件), 변경할 파일에 대한 단서를 명확히 하는 것이 권장됩니다. GitHub 작업 설계 가이드

기사 후보를 저장하는 기능이라면, 예를 들어 다음과 같이 부탁할 수 있습니다. 이것은 요청문의 예시입니다.

記事ID, 일본어 제목, 개요
...

'저장할 수 있다'에서 끝나는 것이 아니라, 저장해서는 안 될 때의 처리 방법도 전달하는 것이 핵심입니다.

여기까지 작성하면, 원고나 화면을 봤을 때 '요청대로 되었는지'를 확인할 항목이 생깁니다. 다른 기능을 부탁할 때도 정상적인 조작 외에 입력이 부족한 경우나 중복된 경우를 생각해 보세요.

이번 한 번의 요구사항은 요청문에 작성하고, 여러 번 사용하는 규칙은 리포지토리(repository)에 두는 것이 다루기 쉽습니다.

VS Code에는 Markdown 지시 파일에 공통 개발 방침을 저장하는 장치가 있습니다. 다만, 선택한 에이전트(agent)에 따라 대응하는 형식이나 읽어들이는 방식이 다릅니다. VS Code의 지시 파일 설명

남겨두고 싶은 것은 그 프로젝트에서 작업할 때 필요한 정보입니다.

예를 들어, 다음과 같은 지시가 있습니다. 저장소 파일명은 사용 중인 환경의 자료에서 확인해 주세요.

변경 전에 docs/PROJECT.md를 읽는다.
저장 처리를 바꿨다면, 기존 데이터를 덮어쓰지 않는 것을 확인한다.
작업 후에는, 확인한 것과 미구현 기능을 보고한다.

AI에게 이 지시 파일을 만들게 할 경우에도, 내용은 한 번 다시 읽어봅니다. VS Code 설정 가이드에서도 명령어나 배치(配置), 완료 조건이 올바른지 확인하고, 오래된 정보나 모순을 제거하는 절차가 소개되어 있습니다. 생성된 지시를 검토하는 절차

예를 들어, 아직 준비되지 않은 테스트 실행 방법이 적혀 있지는 않은지. 이전 구성 그대로 잘못된 장소에 파일을 만들도록 지시하지 않았는지. 실제 리포지토리와 비교하며 수정해 나갑니다.

지시 파일을 두었다면, 우선 작은 변경을 하나 부탁해 봅니다.

VS Code 공식 가이드에서는 파일이 발견된 것과, 작업으로 인해 지시가 지켜졌는 것을 구분합니다. 같은 조건으로 대표적인 태스크를 시험하고, 참조 정보나 생성된 파일, 실행 결과를 비교하는 방법이 제시되어 있습니다. 지시가 사용되는지 확인할 절차

볼 수 있는 것은 요청에 적은 항목들입니다. 파일은 지정한 장소에 있는지. 기존의 만들기에 따르고 있는지. 중복 ID를 거부하는 확인까지 실시했는지.

지시가 읽히는데 결과가 맞지 않다면, 그 부분의 작성 방식을 검토합니다. 규칙을 늘리기 전에, 어디에서 차이가 났는지를 확인하고 싶은 곳입니다.

마지막은 보고와 실제 변경을 비교하는 것입니다.

기사 저장 기능이라면, 단순히 등록되었는지뿐만 아니라, 중복 ID나 입력 불비일 때 저장을 멈출 수 있었는지도 확인합니다. 요청문의 완료 조건과, 보고된 결과를 하나씩 대조해 보면 보기 좋습니다.

'테스트에 통과했습니다'라는 보고에도, 무엇을 시험했는지, 무엇은 시험할 수 없었는지를 덧붙여 달라고 합시다. 테스트가 성공했더라도, 이번에 신경 쓰는 동작을 확인하지 않았다면, 그 부분은 따로 확인할 필요가 있습니다.

다음번에 AI에게 작업을 부탁할 때는, '만들 것'에 '완성하면 확인하고 싶은 것'을 덧붙여 보세요. 우선 하나의 기능으로 시도해 보고, 부족했던 정보를 요청문이나 지시 파일에 채워나가는 진행 방식입니다.