관찰 가능한 결과로 시작하세요
코딩 에이전트는 화면이 무엇을 해야 할지 결정하기 전에 그럴듯해 보이는 화면을 만들 수 있습니다. 작은 사용자 결과로 시작하세요: 로그인한 사용자가 프로필을 편집하고 저장한 뒤 새로고침 후 저장된 이름을 봅니다. 이것이 구현과 리뷰에 구체적인 목표를 줍니다.
브리프에는 현재 동작, 기대 동작, 중요한 실패 사례를 포함하세요. 작업을 소유하는 기존 모듈을 지명하세요. 프로필 편집 추가 요청은 에이전트가 두 번째 사용자 저장소를 만들게 하는 대신 인증 계층을 가리켜야 합니다. 자격 증명은 프롬프트와 스크린샷에서 제외하세요 — 붙여넣은 apps/web/.env.local이나 세션 쿠키는 대화 기록의 일부가 됩니다.
실행 가능한 브리프는 이렇게 읽힙니다: “계정 화면에서 로그인한 사용자가 표시 이름을 편집하고 새로고침 후에도 볼 수 있게 하세요. auth 모듈이 사용자 레코드를 소유하며 테이블을 추가하지 마세요. 빈 이름이나 다른 사용자의 레코드를 지목하는 요청은 거부되어야 합니다. pnpm test와 좁은 너비에서의 수동 저장 한 번으로 증명하세요.” 다섯 문장이면 추측이 대부분 사라집니다.
- 사용자에게 보이는 결과 — 실행 중인 앱에서 확인할 수 있게 표현합니다.
- 오늘 그 동작을 소유하는 파일이나 모듈 — 그리고 건드리지 말아야 할 영역.
- 최소 하나의 실패 사례: 인증되지 않은 시도, 유효하지 않은 입력, 반복된 요청.
- 그것을 증명하는 검사 — 테스트 명령, 픽스처, 또는 명시적 수동 절차.
리포지토리가 스스로 설명하게 하세요
애플리케이션 실행 방법, 어떤 검사가 결정적인지, 소유권이 어디서 강제되는지 문서화하세요. supastack에서 AGENTS.md는 워크스페이스 경계를, .ai/는 파일 수준 결정을 기록합니다. 이러한 노트는 어떤 파일이 바뀌었는지뿐 아니라 구현이 왜 존재하는지 다음 기여자 — 사람이든 에이전트든 — 에게 설명할 때 가장 유용합니다. 에이전트 설정 가이드는 킷이 그 자료를 어떻게 노출하는지 보여주고, 로컬 설정 가이드는 에이전트가 실제로 따를 절차입니다.
수정 전에 관련 코드를 읽도록 에이전트에게 요청하세요. 좁은 변경은 보통 인터페이스, 그것의 서버 경계, 그 경계 주변의 테스트가 필요합니다. 리포지토리 전체를 로드하는 것보다 새 동작이 올바른지를 결정하는 몇 군데 — 소유권 검사, 스키마, 엔타이틀먼트 — 를 이해하는 것이 더 유용합니다.
기능이 구성을 건드릴 때는 내용을 옮기는 대신 파일을 지명하세요 — “apps/web/.env.local에 키를 추가하세요”가 시크릿을 디스크에 둡니다. 같은 원칙이 프로바이더 대시보드에도 적용됩니다: 목적지를 설명하고 자격 증명을 붙여넣지 마세요.
작고 리뷰 가능한 변경으로 작업하세요
변경에 소유자 하나와 확인 가능한 결과 하나가 있을 때 에이전트는 가장 신뢰할 수 있습니다. “프로필 편집 추가”는 리뷰 가능하지만 “계정 영역 개선”은 아무도 요청하지 않은 리팩터를 부릅니다. 기능이 스키마 변경, 서버 경계, 화면으로 분해된다면 각각 빌드를 초록으로 남기는 별도의 브리프로 실행하세요.
각 에이전트 실행 전에 커밋하거나 체크포인트를 만드세요. 깨끗한 기준선은 나쁜 출력을 고고학 작업이 아니라 지운 diff로 바꾸고, 리뷰에 비교할 안정적인 전후를 제공합니다.
한 번에 하나의 완전한 변경을 리뷰하세요
동작을 바꾸기 전에 수용 검사를 작성하세요. 프로필 편집의 경우 유효한 업데이트와 무단 시도를 커버하세요. 그 사례를 충족하는 최소 구현을 만들고, 실제 텍스트와 좁은 뷰포트에서 실제 상호작용을 검사하세요.
결과만큼 diff도 리뷰하세요. 중복된 비즈니스 로직, 지나치게 넓은 예외 처리, 기존 스택이 이미 커버하는 문제를 해결하는 새 의존성을 찾으세요. 프로젝트 검사를 실행하고 그것이 확립하는 것을 기록하세요. 브라우저 픽스처는 폼 상호작용을 검증할 수 있지만 프로덕션 데이터베이스나 외부 프로바이더가 올바르게 구성되었는지는 확립할 수 없습니다.
각 명령은 다른 질문에 답합니다. pnpm test는 결정적 fake 및 로컬 어댑터에 대해 동작을 실행하고, pnpm check는 lint, 타입 검사, 포매팅을 커버하며, pnpm build는 번들 시점에만 나타나는 통합 오류를 표면화합니다. 함께 보면 리뷰의 하한선입니다 — 출시 체크리스트는 실제 환경에서 여전히 증명해야 할 것을 다룹니다.
pnpm test
pnpm check
pnpm build에이전트가 틀렸을 때
결과가 틀렸을 때 나쁜 diff 위에 후속 프롬프트를 쌓는 것을 자제하세요. 체크포인트로 되돌리고, 오해된 것 — 보통 말하지 않은 제약이나 빠진 소유자 — 을 중심으로 브리프를 조인 뒤 다시 실행하세요. 재시도마다 새로운 긴박함이 아니라 새로운 정보를 담아야 합니다.
반복되는 실패는 보통 브리프가 리포지토리에 없는 컨텍스트를 가정한다는 뜻입니다. 에이전트가 계속 사용자를 저장할 두 번째 장소를 만들어낸다면, 해결책은 더 단호한 어조가 아니라 신원이 어디에 있는지에 대한 AGENTS.md의 문장입니다. 문서를 업데이트한 뒤 작업을 재시도하세요 — 에이전트 가이드가 킷이 이 워크플로를 두는 곳입니다.
에이전트 워크플로에 관한 흔한 질문
창업자가 실제 제품 작업을 코딩 에이전트에 맡기기 시작할 때마다 나오는 몇 가지 질문이 있습니다.
- 코딩 에이전트가 SaaS 전체를 혼자 만들 수 있나요? — 보이는 부분은 빠르게 조립할 수 있지만, 오래 가는 부분 — 인가, 결제 라이프사이클, 데이터 격리 — 은 여전히 브리프, 검사, 리뷰가 필요합니다. 그 순환 없는 속도는 재작업이 됩니다.
- 코딩 에이전트에게 주는 작업은 얼마나 커야 하나요? — 실행 중인 앱에서 몇 분 안에 결과를 검증할 수 있을 만큼 작게: 사용자에게 보이는 결과 하나, 소유 모듈 하나, 수용 검사 하나.
- 프롬프트에 절대 넣지 말아야 할 것은요? — 프로바이더 시크릿, 세션 쿠키,
.env.local내용, 고객 데이터. 값을 채팅 로그에 복사하는 대신 파일을 지명하고 도구가 로컬에서 읽게 하세요. - 에이전트가 쓴 코드는 리뷰 방식을 바꾸나요? — 리뷰는 타이핑에서 읽기로 옮겨갑니다: diff에서 중복 로직, 지나치게 넓은 예외 처리, 스택이 이미 처리하는 문제를 다시 해결하는 의존성을 검사하세요.
- 에이전트 출력에 가장 중요한 테스트는요? — 소유권과 실패 동작을 고정하는 테스트: 무단 요청, 유효하지 않은 입력, 반복된 제출이며, 데모가 보여주는 해피 패스만이 아닙니다.