요즘 코딩 에이전트들이 제 코드의 대부분을 작성합니다. 최고의 모델들조차도 숙련된 엔지니어가 소프트웨어를 구축하는 방식만큼은 아닙니다. 그들은 사용자, 코드베이스의 이력, 또는 팀이 좋다고 여기는 디자인 원칙들을 알지 못합니다. 엔지니어는 코드를 작성하기 전에 이러한 질문들을 정리합니다.
에이전트는 추측합니다.
저에게 가장 도움이 된 습관은 사소한 것입니다. 에이전트가 어떤 코드든 작성하기 전에, 저와 에이전트는 결과에 대한 번호 목록을 만듭니다. 이 목록의 모든 항목이 충족되면 변경 사항이 승인됩니다. 저는 이것을 "Done means"라고 부릅니다. 이는 도구 사용 여부와 관계없이 제 판단력을 다시 루프 안으로 가져옵니다.
왜 목록이 중요한가
예를 들어, 에이전트에게 "보고서 페이지에 CSV 내보내기 기능을 추가해 줘"라고 지시했다고 가정해 봅시다. 이 요청은 열려 있는 모든 질문들을 추측으로 채웁니다. 내보내기가 필터를 존중할까요? 50,000개의 행에서는 어떻게 될까요? 어떤 컬럼이 파일에 들어가야 할까요? 에이전트는 각각의 항목에 대한 답을 골라 코드를 작성합니다. 저는 나중에 diff에서 그 답변들을 발견하게 됩니다.
제 경험상, diff를 통해 결정 사항들을 도출하는 것이 에이전트와 작업할 때 가장 느린 부분입니다. Done means 목록은 이러한 결정들을 시작 지점으로 옮겨줍니다. 그곳에서는 변경하기가 쉽고, 제가 직접 결정권을 행사합니다.
작성 방법
저는 에이전트에게 대부분의 작업을 맡깁니다. Claude Code에서는 plan 모드를 사용하고, Codex에서는 /plan을 사용하며, 다음과 같은 프롬프트를 제공합니다:
Read the code that this change touches. Then ask me up to six questions
that decide how the change behaves. For each question, give your
recommended answer. After my answers, write a numbered "Done means" list.
...
추천 답변들이 핵심입니다. 저는 대부분의 내용을 한 번의 키 입력으로 수락합니다. 제가 직접 변경하는 두세 가지 항목이 진정한 결정 사항들입니다.
그것들은 엔지니어가 필요했던 부분입니다.
예시 내보내기 기능에 대한 좋은 목록은 다음과 같습니다:
보고서 페이지에는 필터 옆에 "CSV 내보내기(Export CSV)" 버튼이 표시됩니다.
파일은 현재 필터와 일치하는 행들을 현재 정렬 순서대로 포함합니다.
열들은 동일한 헤더를 가진 보이는 테이블 열과 일치합니다.
50,000개 행의 내보내기가 페이지가 반응성을 유지하는 동안 완료됩니다.
기존 PDF 내보내기 기능은 계속 작동합니다.
각 줄은 제가 1분 안에 직접 확인할 수 있는 내용입니다. "내보내기가 작동한다(Export works)"는 너무 모호해서 어떤 동작을 확인해야 하는지 명시하지 않습니다.
항목 5가 사람들이 건너뛰는 부분입니다. 에이전트(agents)들이 조용히 문제를 일으키는 곳이 바로 '반드시 유지되어야 하는 것'을 명시해야 합니다.
버그를 위한 목록 (A list for bugs)
버그를 위해 저는 네 가지 부분을 사용합니다:
- 언제(When): 이를 유발하는 단계들.
- 무슨 일이 발생하는지(What happens): 잘못된 동작.
- 예상되는 것(Expected): 올바른 동작.
- 반드시 유지되어야 하는 것(Must keep working): 수정 사항이 변경해서는 안 되는 주변 동작.
목록을 마지막에 활용하기 (Using the list at the end)
이 목록은 빌드(build) 이후 두 번째로 빛을 발합니다. 저는 새로운 세션을 열어 빌드를 보지 않은 상태를 만듭니다. 이 세션에 목록을 제공하고 실행 중인 프로그램의 한 지점씩 확인해 달라고 요청합니다:
For each item in Done means, run the program or the tests and show me
the evidence: command output, a screenshot or a file. If you cannot check
an item, say so and tell me what I need to do to check it myself.
새로운 세션이 중요합니다. 코드를 작성한 세션은 자신이 무엇을 해야 했는지 알고 있습니다. 따라서 코드의 실제 동작보다는 그것이 의도했던 바를 보고하는 경향이 있습니다.
저는 각 항목별 증거가 담긴 짧은 보고서를 받습니다. 먼저 이것을 읽고, 그 다음 diff(차이점)를 확인하여 어디를 봐야 할지 알게 됩니다.
QualityLayer에서 이를 수행하는 방법 (How I do this in QualityLayer)
QualityLayer는 이 목록을 중심으로 구축되었습니다. Discuss 단계가 모든 변경 사항에 대해 이 대화를 실행하며, 목록은 코드가 존재하기 전에 제가 승인하는 계획서에 포함됩니다. 빌드 이후에는 코드를 작성하지 않은 에이전트가 모든 지점을 확인하고 증거를 보여줍니다. 확인할 수 없는 것은 검토(Review) 단계에서 저에게 열려 있게 됩니다. 이 시스템은 Claude Code, Codex, OpenCode, Pi 등과 함께 작동하며, 목록은 저장소(repo) 내의 Markdown 파일입니다.
제 관점에서는 소프트웨어를 작성하는 모든 사람이 에이전트의 관리자가 되어가고 있습니다. 이 목록은 제가 그 환경에서 엔지니어 역할을 유지하는 방법입니다. 저는 결정하고(decide), 검토하며(review) 방향을 제시하고(steer), 에이전트가 타이핑을 수행합니다.
하지만 시작하기 위해 도구가 필요하지는 않습니다. 목록을 작성하고, 그것을 기준으로 확인해 보면서, 자신의 검토 과정이 어떻게 변화하는지 살펴보세요.
리포지토리(repo): https://github.com/maxritter/qualitylayer