에이전트를 위한 작업 설명을 작성하세요

검토자가 평가할 수 있는 변경을 설명하세요

“고객 내보내기 추가”에는 여러 결정이 빠져 있습니다. 누가 레코드를 내보낼 수 있나요? 어떤 레코드와 필드를 포함하나요? 요청이 실패하면 어떻게 되나요? 에이전트는 그럴듯한 선택으로 빈틈을 채울 수 있습니다. 하지만 업무에는 맞지 않을 수 있습니다.

사용자와 문제로 시작하세요. 그다음 필요한 동작을 설명하세요. 결과를 받아들일 수 있는지 보여 줄 증거를 포함하세요.

작업 설명은 모든 내부 설계 선택을 고정하지 않으면서 불확실성을 줄여야 합니다. 필요한 데이터 경계를 명시하세요. 바꿀 이유가 없다면 저장소의 기존 패턴으로 구현하도록 하세요.

구체적인 예시를 사용하세요

다음 작업 설명은 가상의 지원 애플리케이션을 위한 것입니다. 학습 예시이며 완전한 프로덕션 명세는 아닙니다.

결과: 지원 관리자가 고객 목록을 다운로드할 수 있다.
행위자: 현재 조직의 관리자.
데이터: 해당 조직의 활성 고객만 포함.
필드: 고객 ID, 회사 이름, 계정 상태.
형식: 헤더 행이 있는 UTF-8 CSV.
거부된 요청: 기존 인가 오류를 반환.
빈 결과: 헤더만 있는 유효한 CSV를 반환.
범위: 기존 내보내기 라우트와 감사 패턴을 사용.
제외: 새 역할, 의존성, 배포 없음.
증거: 허용, 거부, 빈 결과, 조직 간 요청에 대한 테스트.

이 설명은 유용한 동작과 한계를 밝힙니다. 추가 질문도 드러냅니다. 내보내기 크기를 제한해야 하나요? 필드에 스프레드시트 수식이 들어갈 수 있나요? 감사 기록에 누가 접근할 수 있나요? 중요한 결과를 초래하는 질문은 구현 전에 해결하세요. 이 예시를 모든 상황에 적용되는 체크리스트로 보지 마세요.

요구사항과 가정을 구분하세요

요구사항은 변경이 충족해야 하는 동작입니다. 가정은 아직 검증하지 않은 사실입니다. 둘을 구분하세요.

예를 들어 “기존 감사 패턴을 사용하세요”는 적합한 패턴이 있다는 가정입니다. 에이전트에게 찾아 달라고 하세요. 저장소에 없다면 새 감사 시스템을 만들기 전에 빠진 의존성을 보고해야 합니다.

제약이 결과와 충돌할 수도 있습니다. 기존 라우트는 설계상 모든 조직을 반환할 수 있습니다. 에이전트는 충돌을 보여 주고 제한적인 수정을 제안해야 합니다. 데이터 경계를 조용히 없애거나 작업을 아키텍처 재작성으로 확대해서는 안 됩니다.

완료 조건에 증거를 포함하세요

최종 동작, 범위 변경, 수행한 검사를 설명하는 전달 요약을 요청하세요. 중요한 경우 정확한 명령과 결과를 요구하세요. 통과한 검사와 실행하지 못한 검사를 구분하세요.

풀 리퀘스트에는 변경 이유가 남아야 합니다. 나중에 유지보수하는 사람은 원래 대화 없이 코드만 볼 수 있습니다. 내보내기에서 특정 필드를 제외한 이유와 접근을 통제하는 방법을 설명할 만큼의 맥락을 포함하세요.

Google의 변경 설명 지침이 이 기록에 유용한 참고 자료입니다. 설명에는 변경 내용과 목적이 있어야 합니다. 검토 후 수정이 생기면 최종 구현에 맞게 기록을 유지하세요.

작업에 맞는 분량으로 쓰세요

작은 텍스트 수정에는 짧은 설명이면 됩니다. 데이터 내보내기는 실패 시 정보가 노출될 수 있어 더 자세한 설명이 필요합니다. 새 결제 작업 흐름에는 더 많은 분석과 검토가 필요합니다.

길이로 작업 설명의 품질을 판단하지 마세요. 유능한 검토자가 올바른 결과와 잘못된 결과를 구분할 수 있는지 물으세요. 합리적인 두 구현이 중요한 동작에서 다를 수 있다면 그 동작부터 명확히 하세요.