How to Build Quality Gates into Agentic Coding Workflows — Nnenna Ndukwe, Qodo AI

한 줄 핵심

AI 코딩 에이전트의 결과물을 신뢰하려면 규칙·스킬·계획·검증을 레포와 CI에 미리 고정해 두고, 계획-구현-리뷰-재검증의 품질 게이트를 끝까지 자동화해야 한다.

시간별 요약

1. 0:00
   구조화된 AI 코딩 워크플로 AI 코딩은 즉흥적으로 쓰는 것보다 구조화된 절차로 운영할 때 품질을 통제하기 쉽다. 레포 구조를 기준으로 에이전트가 참고할 수 있는 구조를 만들고, 각 단계에 맞는 검증 기준을 재사용하는 방식이 핵심이다.
2. 3:15
   코드 품질이 무너지는 지점 계획, 설계, 개발, 코드 리뷰, 테스트, 배포의 모든 구간에서 AI 생성 코드의 실패가 발생할 수 있다. 그래서 단순 생성보다 품질을 보장하는 시스템을 설계하는 쪽으로 초점을 옮겨야 한다.
3. 4:09
   기준을 정의하고 문서화하기 코드 품질의 정의는 팀 차원에서 먼저 합의되어야 하며, 그 기준은 문서가 아니라 기계가 읽을 수 있는 형태로 저장되어야 한다. 그래야 CLI, IDE, CI 등 어떤 인터페이스에서도 동일한 기준을 꺼내 쓸 수 있다.
4. 5:06
   컨텍스트를 운영 가능한 자산으로 만들기 rules, skills 같은 컨텍스트 자산을 계획, 코드 생성, 코드 리뷰 전반에 걸쳐 재사용해야 한다. 같은 기준을 각 단계에서 검사하게 만들면 품질 확인이 한 번으로 끝나지 않고 반복적으로 이루어진다.
5. 6:00
   SignalPay 워크숍 레포 소개 실습용으로 payments API인 SignalPay 레포를 포크하고 로컬에 복제해 진행한다. 모든 절차는 README에 정리되어 있으며, 에이전트를 통해 메타 수준에서 구현을 돕는 구성이 목표다.
6. 7:11
   계획·테스트·리뷰 게이트 설계 변경 전에는 관련 규칙을 읽어 적용 범위를 정하고, TDD와 BDD 스킬로 테스트를 준비한 뒤 구현을 진행해야 한다. 이후 lint, static analysis 같은 결정적 검사와 PR 리뷰를 거쳐, 발견된 문제는 다시 자동 수정과 재검증으로 이어진다.
7. 8:21
   레포 구조와 로컬 실행 준비 agents.md, hidden plan 디렉터리, rules, skills, docs, API, tests, 정적 분석 도구, CI 워크플로가 레포에 함께 배치되어 있다. `make setup`과 `make run`으로 로컬에서 앱을 띄워 기본 동작을 확인한 뒤 작업을 시작한다.
8. 10:00
   품질 체크포인트와 공통 규칙 설정, 검증, PR 리뷰까지 이어지는 품질 게이트가 미리 정해져 있어야 한다. 특히 repo에 들어 있는 rules와 skills를 Qodo가 흡수해 코드 생성과 리뷰 모두에 같은 기준을 쓰는 구조가 중요하다.
9. 11:32
   계획과 검증 증거 계획 단계에서는 무엇을 바꾸는지, 어떤 규칙이 적용되는지, 어떤 스킬이 쓰이는지, 어떤 테스트와 게이트가 통과해야 하는지를 문서에 명시해야 한다. 로컬 검증은 Ruff, Pytest, Bandit, `piptest`, `sp`, conventional commits 같은 결정적 도구로 증거를 남기고, PR 단계에서는 발견된 이슈를 문서화한 뒤 다시 검증한다.
10. 13:23
    Qodo를 레포에 연결하기 GitHub 계정, CLI, Python, UV, Node.js, npm, 코딩 에이전트 준비가 필요하고, Qodo 포털에서 GitHub 연결과 API key 발급을 마친 뒤 설정 파일에 반영한다. 팀 환경에서는 규칙과 스킬을 로컬에만 두지 말고 별도 컨텍스트 관리층에서 배포 가능하게 두는 편이 유리하다.
11. 16:55
    결제 작업 흐름 선택하기 작업 범위는 refund workflow 또는 capture retry handling처럼 작고 민감한 결제 변경으로 잡는다. 이런 변경은 AI가 그럴듯하게 만들기 쉽지만 오류가 생기기 쉬워 품질 게이트를 시험하기에 적합하다.
12. 18:13
    규칙과 스킬로 Codex 준비하기 에이전트에게 레포의 agents.md와 rules를 읽히고, 이번 작업에 관련된 rule id를 선택하게 해야 한다. 로컬 워크숍 스킬이 설치되어 있지 않으면 설치 과정을 먼저 수행해 에이전트가 실행 전에 필요한 컨텍스트를 갖추게 한다.
13. 20:47
    구현 전에 변경 계획 세우기 구현 전에 high-level plan과 build session execution plan을 먼저 작성해, 아직 코드는 쓰지 않도록 제어한다. 이 계획에는 다음 구현 스킬로 넘길 handoff와 이후의 TDD 프롬프트까지 포함되어야 한다.
14. 25:07
    계획 템플릿 살펴보기 계획 템플릿은 변경할 동작, 적용 규칙, 사용할 스킬, 검증 테스트, 통과해야 할 품질 게이트를 체계적으로 정리하도록 만든다. 구조화된 계획은 에이전트가 중간에 스스로 오류를 수정하고, 커밋과 PR까지 일관된 방식으로 이어지게 한다.
15. 27:13
    실행 및 완료 노트 작성하기 빌드 실행 템플릿에는 시작 상태, 현재 브랜치, 로컬 검증 명령, 린터 기대값, 구현 단계와 테스트 계획이 들어가야 한다. 완료 시점에는 실행한 명령, 남겨둔 보류 사항, 변경된 의사결정을 모두 기록해 두어야 한다.
16. 28:38
    환불 워크플로 구현하기 실제 구현 단계에서는 선택한 환불 흐름을 코드에 반영한다. 이 구간은 계획과 검증이 앞서 준비되어 있어야만 안전하게 진행된다.
17. 29:07
    스킬과 로컬 코드 리뷰 구현 품질은 Python typing, Pydantic, audit 계열 스킬처럼 레포와 언어에 맞는 스킬 조합으로 높일 수 있다. 로컬 코드 리뷰를 먼저 돌린 뒤 CI나 Git provider에서 자동 리뷰를 한 번 더 돌리는 흐름이 문제를 더 빨리 잡아낸다.
18. 33:17
    규칙 범주와 심각도 규칙은 accessibility, correctness, maintainability, architecture, security 같은 범주로 나뉘고, severity에 따라 다르게 취급된다. 모든 규칙이 같은 강도로 처리될 필요는 없으며, 일부는 병합 차단까지 연결할 수 있다.
19. 36:14
    추론된 규칙과 사람의 승인 규칙은 rules 디렉터리처럼 명시적으로 존재하는 것뿐 아니라 코드베이스 분석으로 추론된 제안 형태로도 생성된다. 제안된 규칙은 예시 코드, 범주, 경고 수준을 사람이 검토한 뒤 활성화해야 실제 규칙으로 적용된다.
20. 39:10
    PR을 열어 리뷰에 넘기기 구현이 끝나면 PR을 열어 Qodo가 분석하게 하고, 요약과 변경 다이어그램을 확인한다. 리뷰 결과에서 문제가 나오면 그 이슈를 자동 해결하는 에이전트 스킬로 이어진다.
21. 42:24
    검증과 리뷰 컨텍스트 코드 리뷰에서는 계획이나 구현이 아니라 리뷰에 필요한 규칙과 스킬만 컨텍스트로 가져와야 한다. 이 단계에서는 특정 PR에 연관된 규칙을 추출하고, 로컬 검증을 재실행하는 습관이 중요하다.
22. 44:00
    규칙 위반과 병합 차단 예를 들어 Python 함수의 docstring 누락처럼 조직이 높은 심각도로 정한 규칙은 action required로 표시되고 병합을 막을 수 있다. 심각도 정책은 팀이 정한 기준에 따라 조정 가능하며, 차단 여부도 설정할 수 있다.
23. 45:46
    결정성과 규칙 선택의 한계 현재는 에이전트가 어떤 규칙이 정확히 관련되는지 완전히 결정적으로 판정하지 못할 수 있으며, 특히 규제 산업에서는 이 부분이 중요하다. 그래서 선택 정확도와 검증 자동화는 앞으로 더 강화되어야 할 영역이다.
24. 47:13
    리뷰 결과 살펴보기 리뷰 결과는 버그, 규칙 위반, 스킬 인사이트처럼 구체적으로 분해되어 표시된다. 예를 들어 refund 결과를 인메모리 dict에 저장하는 방식은 지속성이 없으므로, 해당 코드와 증거를 함께 보고 수정해야 한다.
25. 49:03
    에이전트 스킬로 문제 해결하기 Qodo PR resolver 같은 스킬을 사용하면 critical, high 수준 이슈를 모아 자동 수정할 수 있다. 각 이슈를 개별적으로 검토할 수도 있지만, 워크숍에서는 자동 수정으로 흐름을 보여준다.
26. 50:16
    검증을 다시 돌리고 PR 갱신하기 수정 후에는 다시 검증을 실행하고, 구조화된 커밋 규칙이 지켜지는지 확인한 뒤 PR에 변경 요약을 게시해야 한다. worktree 같은 세부 운용은 에이전트가 처리할 수 있지만, 최종적으로는 검증이 다시 돌아가야 안전하다.
27. 53:08
    워크숍 과정을 재사용하기 이 워크숍의 핵심은 특정 레포가 아니라 rules, skills, 계획 템플릿, 검증 절차를 다른 프로젝트에도 재사용하는 데 있다. open-source 대안으로 Packmind 같은 컨텍스트 관리 도구도 검토할 수 있다.
28. 55:15
    컨텍스트와 배포 관련 질문 세션 컨텍스트는 사용 방식에 따라 compact해도 문제없을 수 있으며, 필요하면 새 세션으로 옮겨가며 이어갈 수 있다. 보안 요구가 있으면 on-prem deployment 같은 로컬·사내 배포 옵션도 제공된다.
29. 56:39
    완료된 수정 사항 검증하기 마지막에는 모든 이슈가 실제로 해결되었는지 다시 확인하고, 수정 결과를 요약해 마무리한다. 품질 게이트는 수정 제안에서 끝나지 않고 최종 검증까지 완료되어야 닫힌다.

실무 인사이트

• AI 코딩 워크플로는 생성보다 검증을 먼저 설계해야 하며, 규칙·스킬·테스트·리뷰를 같은 기준으로 반복 적용할 때 품질이 안정된다.
• 계획 템플릿은 에이전트의 자유도를 줄이는 장치가 아니라, 구현 중 자기수정과 재검증을 유도하는 운영 도구로 써야 효과가 크다.
• 조직 차원의 규칙 심각도와 병합 차단 정책을 미리 정해 두면, AI 코드 리뷰를 단순 권고가 아니라 실제 게이트로 만들 수 있다.