코딩 에이전트를 명확한 티켓과 스스로의 작업을 확인할 수 있는 방법을 갖춘 빠르고 유능한 동료처럼 다루세요. 작업에 인수 기준(acceptance criteria)을 작성하고, 코드를 작성하기 전에 계획을 요청하며, 변경 사항이 작동하는지 증명하는 명령을 에이전트에게 주고, 모든 diff를 작게 유지하며, 소유자로서 검토하세요. 속도는 에이전트의 역할입니다. 판단은 여전히 당신의 몫입니다.
현재 시간 배분 방식
코딩 에이전트는 코드를 빠르고 많이 작성하고 변경하며, 지침을 잘 따릅니다. 이로 인해 프로젝트에서 노력이 필요한 부분이 바뀝니다. 타이핑하는 양은 줄어들고, 대신 두 가지 영역에 더 많은 노력이 필요합니다: 원하는 것을 정확하게 말하는 것과 그것이 제대로 되었는지 확인하는 것입니다.
둘 다 기존의 엔지니어링 기술입니다. 명확한 티켓을 작성하고 변경 사항을 검토하는 것은 항상 업무의 일부였으며, 생산 비용은 하락했지만 이해하는 데 드는 비용은 그렇지 않기 때문에 지금 더 중요해졌습니다. 아래 워크플로우는 특정 벤더에 의존하지 않습니다. 에이전트가 터미널, 에디터 또는 풀 리퀘스트 봇(pull request bot) 중 어디에 있든 작동합니다.
티켓처럼 작업을 작성하기
에이전트는 당신이 남긴 모든 공백을 스스로의 최선의 추측으로 채웁니다. 모호한 요청은 당신이 완전히 질문하지 않은 내용에 대해 자신감 있는 답변을 돌려줍니다. 유용한 작업에는 네 가지 부분이 있습니다: 목표(goal), 제약 조건(constraints), 완료되었음을 알리는 방법, 그리고 범위를 벗어난 것(out of scope)입니다.
Goal
Add a "resend verification email" button to the account page.
...
마지막 섹션이 보이는 것보다 더 중요합니다. 이것이 없으면 에이전트는 당신이 언급하지 않은 내용까지 유용하게 정리하려 들 것이고, 결국 원하는 것보다 더 큰 변경 사항을 검토하게 될 것입니다.
코드 작성 전 계획 요청하기
작은 수정 이상의 모든 것에 대해서는 에이전트에게 코드를 읽고 계획을 제안하도록 요청하고, 그 계획을 당신이 읽기 전까지는 파일을 변경하도록 두지 마세요. 대부분의 에이전트는 바로 이런 목적을 위해 계획 수립(planning) 또는 읽기 전용 모드(read only mode)를 가지고 있습니다. 계획은 읽기도 쉽고 수정하기도 쉽습니다. 여기서 잘못된 계획을 잡아내는 것은 잘못된 구현과 그 뒤에 따를 검토 작업을 아껴줍니다.
계획을 읽을 때 저는 세 가지를 확인합니다. 예상하는 파일만 건드리는가? 이미 존재하는 코드를 재사용하는가 아니면 병렬 복사본을 작성하는가? 변경 사항이 어떻게 테스트될지 명시했는가? 계획이 새로운 의존성이나 새로운 패턴을 제안하면, 한 줄을 쓰기 전에 그 이유를 묻습니다.
에이전트가 실행할 수 있도록 정확성을 확보하기
에이전트 출력의 가장 큰 개선점은 스스로 검사하는 방법을 제공하는 것입니다. 테스트, 타입 체크 및 린팅(linting)이 하나의 명령으로 실행된다면, 에이전트는 코드를 변경하고, 해당 명령을 실행하며, 실패 내용을 읽고 수정할 수 있습니다. 이때 사용자의 개입이 필요 없습니다.
{
"scripts": {
"check": "eslint . && tsc --noEmit && vitest run"
...
}
에이전트에게 작업 완료를 알리기 전에 해당 명령을 실행하도록 평범한 말로 지시하세요. 더 좋은 방법은 원하는 동작을 설명하는 실패한 테스트부터 시작하여 에이전트가 이를 통과시키도록 하는 것입니다. 사용자가 작성한 테스트는 명세(specification)입니다. 에이전트가 자체 코드에 대해 작성한 테스트는 자체 가정을 조용히 확인할 수 있으므로, 코드 자체보다 이 테스트들을 더 주의 깊게 읽으세요.
모든 변경 사항을 작게 유지하기
리뷰의 품질은 diff(변경 내용)가 커질수록 빠르게 떨어집니다. 몇 분 안에 읽을 수 있는 변경 사항은 진정한 리뷰를 받습니다. 서른 개의 파일에 걸쳐 퍼진 변경 사항은 훑어보기만 하게 만듭니다. 한 번에 하나의 우려사항만을 요청하고, 체크포인트에서 커밋하며, 되돌리기(revert)를 실패가 아닌 평범한 도구로 취급하세요.
이것을 바랄 것이 아니라 강제할 수 있습니다. 이 스크립트는 변경 사항이 합의된 리뷰 범위를 초과하면 빌드를 실패시킵니다. 병합하려는 브랜치에 대해 CI(Continuous Integration)에서 실행하세요.
import { execFileSync } from 'node:child_process'
const base = process.env.BASE_REF ?? 'origin/main'
...
15개 파일과 400줄은 시작점일 뿐, 규칙이 아닙니다. 팀이 진정으로 리뷰할 수 있는 한계를 정하고, 더 이상 잘못된 경보를 일으키는 lockfile이나 생성된 파일은 제외하세요.
지침 파일을 이용해 레포지토리를 가르치기
에이전트는 매 세션마다 프로젝트에 대해 아무것도 모르는 상태로 시작합니다. 대부분의 도구는 리포지토리 루트에서 일반 텍스트 지침 파일을 읽습니다. AGENTS.md는 여러 도구가 이해하는 공통 이름이 되었으며, 일부 도구는 CLAUDE.md와 같은 자체 파일을 읽기도 합니다. 만약 팀이 여러 도구를 사용한다면, 공유 규칙을 한 곳에 보관하는 것이 이들이 서로 어긋나는 것을 방지합니다.
여기에 들어갈 내용은 짧고 실용적입니다: 빌드 및 테스트 명령어, 코드만으로는 명확하지 않은 컨벤션, 접근 금지 폴더, 그리고 이전에 발생했던 실수들. 작게 시작하세요. 같은 실수를 두 번 볼 때마다 한 줄을 추가하고, 가능하다면 그 규칙이 단순히 기록되는 것이 아니라 강제되도록 실패하는 테스트를 추가하세요.
# AGENTS.md
## Commands
...
소유자로서 검토하기
풀 리퀘스트(pull request)가 도착하면, 변경된 파일을 여는 것이 본능적인 반응입니다. 한 단계 더 앞서 시작하세요. 작업을 읽고 올바른 변경 사항이 어떤 모습일지 결정한 다음 비교하는 것입니다. 의도에 맞춰 검토하는 것은 가장 비싼 문제, 즉 깔끔하고 잘 테스트되었지만 잘못된 것을 해결하는 변경 사항을 포착합니다.
- 범위(Scope). 작업에서 요청한 것만 했고 그 이상은 하지 않았는가?
- 엣지 케이스(Edge cases). 빈 입력, 반복적인 클릭, 누락된 레코드, 느린 네트워크.
- 보안(Security). 누가 이것을 호출하도록 허용되었는가? 모든 입력이 검증되는가? 비밀 정보가 코드와 로그에서 제외되는가?
- 의존성(Dependencies). 패키지를 추가했는지, 그리고 그것이 정당화되는가?
- 성능(Performance). 루프 안의 쿼리, 제한 없는 리스트, 메모리에 로드된 전체 파일.
- 테스트(Tests). 기능에 문제가 생겼다면 실패할 것인가?
이러한 종류의 검토는 기본 원칙에 기반합니다. 커리어 초반이라면 vibe coding 대 코딩 학습 가 가능한 기초를 다루고 있습니다.
키보드를 다시 가져와야 할 때 아는 법
어떤 상황은 수동으로 처리하는 것이 더 좋거나, 적어도 당신이 가까이 운전대를 잡는 것이 좋습니다.
- 같은 오류가 세 번 연속으로 발생했습니다.
- 요구사항이 불분명하여 에이전트가 여러 해석 사이에서 추측하고 있습니다.
- 코드가 보안에 민감합니다: 인증(authentication), 권한(permissions) 또는 결제(payments).
- 데이터 마이그레이션이나 삭제와 같이 되돌릴 수 없는 작업입니다.
새로운 팀원에게 부여할 최소 권한(least privilege)을 적용하세요. 브랜치에서 작업하고, 프로덕션 자격 증명(production credentials)에 닿지 않도록 하며, 잘못된 추측이 복구(recovery)가 아닌 되돌리기(revert)로 끝나게 하려면 파괴적인 명령(destructive commands)을 제한해야 합니다.
한 곳에서 루프 돌기 (The loop in one place)
- 목표, 제약 조건(constraints), 완료 정의(definition of done), 그리고 범위 외 항목(out of scope)이 명시된 티켓을 작성하세요.
- 계획을 요청하고 파일 변경 전에 읽어보세요.
- 에이전트에게 검사 명령(check command)을 실행하게 하고 실패한 부분을 수정하도록 하세요.
- 검토하기에 충분히 작은 diff를 유지하세요.
- 의도(intent)에 따라, 그리고 체크리스트에 따라 검토하세요.
- 반복되는 실수는 지침 파일(instructions file)에 기록하고, 이상적으로는 테스트와 함께 기록하세요.
티켓을 작성하고 검사를 설정하는 동안 처음 몇 가지 작업은 더 느리게 느껴질 것입니다. 하지만 그 보상은 출력물이 신뢰할 수 있는 상태로 도착하여 빠르게 검토할 수 있다는 점이며, 바로 여기서 에이전트가 실제로 시간을 절약해 주는 부분이 나옵니다.
원래 게시된 곳: my portfolio blog.