AGENTS.md와 이슈, 스펙, CodeRabbit으로 만드는 AI 개발 사이클

AGENTS.md와 이슈, 스펙, CodeRabbit으로 만드는 AI 개발 사이클

최근에는 AI에게 단순히 “이 기능 구현해줘”라고 요청하지 않습니다.
먼저 Issue를 만들고, 필요한 경우 Spec을 작성한 뒤, AGENTS.md와 작업 프롬프트를 기준으로 개발 흐름을 고정합니다.

현재 제가 사용하는 흐름은 다음과 같습니다.

1. 이슈 생성
2. 스펙 생성 또는 확인
3. 구현
4. 테스트 및 정적 검사
5. PR 생성
6. CodeRabbit 리뷰 요청
7. 리뷰 타당성 검토
8. 필요한 내용만 반영
9. CodeRabbit 재리뷰
10. 최종 diff 검토

이 흐름은 AI가 임의로 정한 방식이 아닙니다.
프로젝트 루트에 있는 AGENTS.md, 제가 사용하는 작업 프롬프트, Issue, Spec, CodeRabbit이 함께 작동하면서 만들어지는 방식입니다.

 

왜 이슈를 먼저 만드는가

저는 작업을 시작할 때 가능한 한 Issue를 먼저 만듭니다.

이슈를 사용하는 이유는 단순히 할 일을 기록하기 위해서가 아닙니다. 제가 작업할 때 이슈는 작업의 목적, 범위, 완료 기준을 고정하는 기준점입니다.

AI와 함께 개발할 때 가장 위험한 부분은 구현 속도가 아니라 작업 범위가 흐려지는 것입니다.
요청이 모호하면 AI는 그럴듯한 방향으로 기능을 넓히거나, Spec에 없는 동작을 추가할 수 있는데, 이슈는 그 위험을 줄이는 역할을 합니다.

보통 이슈에는 다음 내용을 적습니다.

• 해결하려는 문제
• 현재 동작
• 기대 동작
• 변경 대상 범위
• 제외할 범위
• 검증 방법
• 관련 스펙 또는 문서

이렇게 이슈를 만들어두면 작업 중 판단 기준이 명확해집니다.

예를 들어 CodeRabbit이 좋은 제안을 하더라도, 그 제안이 현재 이슈 범위 밖이라면 반영하지 않습니다. 하지만 반대로 이슈의 목적과 맞고, 스펙에도 부합한다면 반영 대상이 됩니다.

즉, 이슈는 다음 역할을 합니다.

• 작업 범위를 고정합니다.
• AI의 추측 구현을 줄입니다.
• PR의 목적을 명확하게 만듭니다.
• 리뷰 의견을 반영할지 판단하는 기준이 됩니다.
• 나중에 왜 이 변경을 했는지 추적할 수 있게 합니다.

저에게 이슈는 작업 요청서이자 PR의 기준 문서입니다.

 

언제 스펙을 만드는가

모든 작업에 새로운 Spec이 필요한 것은 아닙니다.
이미 OpenAPI, YAML Markdown 문서, 기존 도메인 문서가 있다면 해당 스펙을 기준으로 구현하면 됩니다.

하지만 다음과 같은 경우에는 스펙을 먼저 만들거나 수정합니다.

• 새로운 API를 추가할 때
• 요청 또는 응답 구조가 바뀔 때
• 검증 조건이 명확하지 않을 때
• 예외 응답 규칙이 필요한 때
• 기존 코드만으로 기대 동작을 판단하기 어려울 때
• 이슈만으로 구현 기준이 부족할 때

스펙은 구현보다 먼저 있어야 합니다.
구현을 먼저 하고 나중에 스펙을 맞추면, 실제로는 코드가 기준이 되기 때문에 스펙 기반 개발이 아니라 구현 기반 문서화가 됩니다.

제가 원하는 흐름은 반대입니다.

1. 스펙
2. 구현
3. 검증
4. 리뷰

먼저 스펙을 정하고, 그 스펙에 맞춰 구현합니다.

 

 AGENTS.md란 무엇인가

AGENTS.md는 AI 에이전트에게 이 프로젝트에서 어떻게 작업해야 하는지 알려주는 지침 파일입니다.

사람 개발자로 비유하면 팀 컨벤션 문서, 개발 가이드, PR 규칙, 리뷰 기준을 하나로 묶은 문서에 가깝습니다.

현재 제 프로젝트에서 AGENTS.md는 다음 역할을 합니다.

• 어떤 언어로 답변해야 하는지 정합니다.
• 구현 전에 무엇을 읽어야 하는지 정합니다.
• 스펙을 기준으로만 구현하도록 제한합니다.
• 계층별 책임을 정합니다.
• CodeRabbit 리뷰 요청 방식을 정합니다.
• 리뷰 제안을 어떻게 판단할지 정합니다.
• 테스트 실행 순서를 정합니다.
• 최종 응답 형식을 고정합니다.

즉, AGENTS.md는 AI가 작업 중 마음대로 판단하지 않도록 작업 경계를 만들어주는 문서입니다.

 

현재 사용하는 AGENTS.md의 핵심 내용

현재 AGENTS.md의 첫 번째 원칙은 스펙 기반 구현입니다.

• 모든 구현은 스펙을 기반으로 해야 합니다.
• 명시되지 않은 동작을 추측하거나 추가하지 않습니다.
• 이 원칙 때문에 AI는 이슈나 스펙에 없는 기능을 임의로 추가하지 않습니다.
• 요구사항이 불명확하면 추측해서 구현하지 않고, 질문하거나 TODO를 남기는 방향으로 동작합니다.

언어 규칙도 정해져 있습니다.

• 채팅 응답은 기본적으로 한국어로 작성합니다.
• 프로젝트의 commit, issue, PR 문구는 영어로 작성합니다.
• 코드, 명령어, 식별자, 파일 경로 등 필요한 경우에만 영어를 사용합니다.

대략적인 우선순위는 다음과 같습니다.

1. System Prompt
2. Developer Prompt
3. App / Workspace Context
4. AGENTS.md
5. User Prompt
6. Issue, PR, diff
7. Spec 문서
8. 관련 코드
9. 테스트와 실행 결과
10. 최종 diff

여기서 중요한 점은 AGENTS.md가 실제 구현 코드보다 먼저 기준으로 적용된다는 것입니다.

AI가 바로 코드를 열고 수정하는 것이 아니라, 먼저 “이 프로젝트에서는 어떻게 작업해야 하는가”를 확인한 뒤에 이슈, 스펙, 코드 순서로 내려갑니다.

 

AGENTS.md를 먼저 읽는 이유

AGENTS.md를 먼저 읽는 이유는 작업 방식 자체를 고정하기 위해서입니다.

현재 AGENTS.md에는 다음과 같은 규칙이 들어 있습니다.

• 한국어로 응답합니다.
• 프로젝트의 commit, issue, PR은 영어로 작성합니다.
• 구현 전에 이슈와 스펙을 읽습니다.
• 스펙에 없는 기능은 구현하지 않습니다.
• 관련 없는 리팩터링을 하지 않습니다.
• CodeRabbit 제안은 무조건 반영하지 않습니다.
• 테스트 결과를 최종 응답에 포함합니다.

이 규칙을 먼저 읽어야 이후 작업이 흔들리지 않습니다.

만약 AI가 AGENTS.md보다 코드를 먼저 읽는다면, 기존 코드만 보고 임의로 구조를 바꾸거나 스펙에 없는 개선을 추가할 수 있습니다.
하지만 AGENTS.md가 먼저 적용되면 “스펙 밖 구현 금지”, “최소 변경”, “관련 없는 리팩터링 금지” 같은 제한이 먼저 걸립니다.

 

실제 작업 순서

실제 작업에서는 다음 순서로 읽어갑니다.

1. AGENTS.md
2. User Prompt
3. Issue
4. PR
5.  diff
6. Spec
7. 관련 코드
8. 테스트 결과
9. 최종 diff

먼저 프로젝트 규칙을 확인합니다.
여기서 언어 규칙, 작업 순서, 테스트 방식, CodeRabbit 처리 방식, 최종 응답 형식을 확인합니다.

그다음 사용자의 요청을 확인합니다.
예를 들어 사용자가 “이슈 10번 구현해줘”라고 하면, AI는 이 요청을 작업 목표로 잡습니다.

그다음 관련 이슈와 PR 정보를 읽습니다.
이 단계에서는 작업 목적과 범위를 확인합니다.

그다음 스펙 문서를 읽습니다.
API경로, 요청, 응답, 검증 조건, 예외 규칙을 확인합니다.

그다음 관련 코드를 읽습니다.
하지만 이때도 코드를 보고 마음대로 바꾸는 것이 아니라, 앞에서 읽은 이슈와 스펙에 필요한 부분만 수정합니다.

마지막으로 테스트와 diff를 확인합니다.
여기서 스펙과 구현이 맞는지, 변경 범위가 과하지 않은지, 기존 계약을 깨지 않았는지 다시 확인합니다.

계층별 책임도 프롬프트로 제한합니다

AGENTS.md에는 코드 계층별 규칙도 들어 있습니다.

Controller
- 비즈니스 로직을 포함하지 않습니다.
- 요청과 응답 매핑만 담당합니다.

Service
- 비즈니스 로직은 서비스 계층에 둡니다.
- transaction을 명시적으로 설정합니다.
- 비즈니스 검증을 서비스 계층에서 수행합니다.

DTO
- 요청 DTO와 응답 DTO를 분리합니다.
- 검증 annotation을 DTO에 둡니다.
- 필요한 경우 변환 로직을 DTO 내부에 둡니다.

Entity
- 상태와 도메인 동작만 유지합니다.
- 생성을 위해 static factory method를 선호합니다.

Repository
- 데이터 접근만 담당합니다.
이 규칙은 AI가 Controller에 비즈니스 로직을 넣거나, DTO와 Entity의 책임을 섞는 일을 줄여줍니다.
결과적으로 코드 구조가 기존 프로젝트 방식에서 벗어나지 않게 됩니다.

금지 사항도 명확히 둡니다
AI에게 가장 위험한 요청은 “좋게 알아서 해줘”입니다.
그래서 현재 지침에는 금지 사항도 명확히 적어두었습니다.

• 스펙에 없는 기능을 추가하지 않습니다.
• 필드를 임의로 만들지 않습니다.
• 전체 구조를 다시 작성하지 않습니다.
• 관련 없는 코드를 수정하지 않습니다.
• 기존 API계약을 깨지 않습니다.
• 검증되지 않은 로직을 PR에 포함하지 않습니다.
• PR 목적 밖의 리팩터링을 하지 않습니다.

이 규칙은 변경 범위를 줄이는 데 큰 역할을 합니다.
AI가 코드를 더 깔끔하게 만들고 싶어도, 현재 이슈와 관계없으면 수정하지 않도록 제한합니다.

 

CodeRabbit 리뷰 흐름

현재 사이클의 핵심 중 하나는 CodeRabbit 리뷰입니다.
AGENTS.md에는 Draft PR 또는 리뷰 후속 작업에서는 CodeRabbit 리뷰를 먼저 요청하도록 되어 있습니다.

첫 리뷰는 전체 리뷰로 요청합니다. 아래 명령은 해당 PR에 CodeRabbit 전체 리뷰를 요청하는 명령입니다.

gh pr comment <PR_NUMBER> --repo KoreaNirsa/spec-guard --body "@coderabbitai full review"

 

후속 리뷰는 증분 리뷰로 요청합니다. 아래 명령은 새로 추가된 변경 사항 중심으로 CodeRabbit 리뷰를 요청하는 명령입니다.

gh pr comment <PR_NUMBER> --repo KoreaNirsa/spec-guard --body "@coderabbitai review"

이렇게 나누는 이유는 명확합니다.
첫 리뷰에서는 PR 전체를 확인한 후 새로 반영한 변경만 확인하는 편이 더 효율적입니다.

 

CodeRabbit YAML을 사용하지 않은 이유

CodeRabbit은 별도의 YAML을 통해 리뷰 규칙을 지정할 수 있습니다.
하지만 현재 프로젝트에서는 CodeRabbit YAML을 중심으로 흐름을 만들지 않고 AGENTS.md, 이슈, 스펙, PR 흐름을 기준으로 작업 방식을 고정했습니다.

첫 번째 이유는 이 프로젝트가 OSS 프로젝트이기 때문입니다.
OSS 프로젝트에서는 특정 도구의 설정 파일보다, 사람이 읽고 이해할 수 있는 작업 원칙이 중요하다고 생각합니다.
외부 기여자나 리뷰어가 저장소를 봤을 때 “이 프로젝트는 어떤 기준으로 작업하는가”를 쉽게 이해할 수 있어야 합니다.

두 번째 이유는 CodeRabbit YAML이 CodeRabbit의 리뷰 동작에는 영향을 줄 수 있지만, AI 구현 흐름 전체를 통제하지는 못하기 때문입니다.

현재 제가 원하는 흐름은 단순 리뷰 설정이 아닙니다.

1. 이슈 생성
2. 스펙 확인
3. 구현
4. 테스트
5. PR
6. CodeRabbit 리뷰
7. 타당성 검토
8. 필요한 내용만 반영
9. 재리뷰

이 전체 흐름은 CodeRabbit만으로는 만들 수 없습니다.
CodeRabbit은 PR이 만들어진 뒤 리뷰를 도와주는 도구에 가깝습니다.
반면 AGENTS.md는 구현 전 단계부터 AI가 무엇을 읽고, 무엇을 기준으로 판단하고, 어떤 범위 안에서 수정해야 하는지를 정합니다.

세 번째 이유는 특정 리뷰 도구에 작업 기준이 종속되는 것을 피하기 위해서입니다.

이 프로젝트에서 더 중요한 기준은 CodeRabbit 아니라 이슈와 스펙입니다.

현재 구조에서는 역할을 이렇게 나눕니다.

1. Issue
  → 작업 목적과 범위를 정합니다.
2. Spec
  → 구현 기준과 API 계약을 정합니다.
3. AGENTS.md
  → AI가 따라야 할 작업 방식과 제한을 정합니다.
4. CodeRabbit
  → PR 이후 보조 리뷰를 수행합니다.

이렇게 분리하면 CodeRabbit은 중요한 보조 도구로 사용할 수 있지만, 프로젝트의 최종 기준이 되지는 않습니다.

CodeRabbit 제안은 무조건 반영하지 않습니다. 중요한 점은 CodeRabbit의 모든 제안을 적용하지 않는다는 것입니다.

현재 지침에서는 다음 조건을 만족하는 제안만 반영하도록 되어 있습니다.

•  PR목적과 일치합니다.
• 관련 이슈와 일치합니다.
• 스펙 또는 API 계약과 일치합니다.
• diff를 최소로 유지합니다.
• 테스트로 검증할 수 있습니다.

반대로 다음 제안은 반영하지 않습니다.

• 관련 없는 리팩터링입니다.
• 스펙에 없는 기능입니다.
• 큰 구조 변경입니다.
• 단순 스타일 취향입니다.
• API 계약에 위험합니다.
• 현재 PR 범위 밖입니다.
• 근거가 약하거나 모호합니다.

즉, CodeRabbit은 최종 결정자가 아니라 보조 리뷰어입니다. 최종 판단 기준은 항상 이슈, 스펙, API 계약입니다.

테스트 순서도 정해둡니다
변경 후에는 테스트를 실행합니다.
이때도 무작정 전체 테스트부터 돌리지 않고, 지침에 따라 순서를 둡니다.

1. 변경 파일 대상 테스트
2. 영향받은 도메인의 기존 테스트
3. 이슈나 PR에 명시된 검증 명령
4. 필요할 경우 전체 테스트

테스트를 실행할 수 없는 경우에도 그냥 넘어가지 않습니다.
실행하지 못한 명령, 이유, 남은 위험을 최종 응답에 남기도록 되어 있습니다.

최종 리뷰도 AI가 다시 수행합니다
작업이 끝나면 최종 diff를 다시 확인합니다.

확인 기준은 다음과 같습니다.

• 이슈와 스펙을 다시 확인했는지
• diff가 PR 범위 안에 있는지
• 스펙에 없는 기능이 추가되지 않았는지
• API 계약이 깨지지 않았는지
• 테스트가 충분한지
• 회귀 위험이 허용 가능한지
• 관련 없는 리팩터링이나 포맷 변경이 없는지
• CodeRabbit 제안을 과하게 반영하지 않았는지

이 단계는 사람이 PR을 리뷰하는 관점과 비슷합니다.
단순히 “구현이 끝났다”가 아니라 “PR로 올릴 수 있는 상태인가”를 다시 확인하는 과정입니다.

최종 응답 형식도 고정합니다
현재 AGENTS.md는 최종 응답 형식까지 지정합니다.

• Changed Files(변경 파일)
• Reason(변경 이유)
• Code(코드 변경 내용)
• CodeRabbit Results(코드래빗 결과)
• Codex Final Review(코덱스 최종 검토)
• Tests(테스트)

이 형식을 고정해두면 작업 결과를 매번 같은 기준으로 확인할 수 있습니다.
무엇이 바뀌었는지, 왜 바뀌었는지, 어떤 테스트를 했는지, 남은 위험은 무엇인지 빠르게 볼 수 있습니다.

 

전체 흐름이 동작하는 방식

현재 흐름은 하나의 프롬프트만으로 만들어지는 것이 아닙니다.

크게 보면 다음 요소들이 함께 작동합니다.
1. Codex 기본 개발 에이전트 동작
2. 프로젝트 루트의 AGENTS.md
3. Issue
4. Spec
5. GitHub / CodeRabbit 관련 작업 프롬프트
6. 프로젝트 규칙

Codex 기본 동작은 파일을 읽고, 코드를 수정하고, 테스트를 실행하고, diff를 확인하는 기반이 됩니다.

그 위에 AGENTS.md가 프로젝트 전용 규칙을 덮어씌웁니다.
예를 들어 한국어 응답,  commit / PR 규칙, 스펙 기반 구현, CodeRabbit 리뷰 사이클 같은 내용이 여기서 정해집니다.

Issue는 작업 목적과 범위를 고정합니다.
Spec은 구현 기준을 고정합니다.
CodeRabbit은 PR 이후 보조 리뷰어 역할을 합니다.

정리하면 다음과 같습니다.

1. Codex 기본 동작
  → 개발 작업을 수행하는 기본 능력입니다.
2. AGENTS.md
  → 이 프로젝트에서 반드시 따라야 하는 작업 규칙입니다.
3. Issue
  → 작업 목적과 범위를 고정합니다.
4. Spec
  → 구현 기준과 API 계약을 정합니다.
5. CodeRabbit
  → PR 이후 보조 리뷰를 수행합니다.

 

실제 개발 사이클

이 설정을 적용하면 실제 작업은 다음처럼 진행됩니다.

1. 이슈를 만듭니다.
2. 이슈에 문제, 기대 동작, 범위, 검증 방법을 적습니다.
3. 필요한 경우 스펙을 새로 만들거나 기존 스펙을 수정합니다.
4. AGENTS.md의 작업 규칙을 기준으로 삼습니다.
5. 이슈와 스펙을 읽습니다.
6. 구현해야 할 입력과 출력을 정리합니다.
7. Controller, Service, DTO, Repository 중 어떤 계층이 영향을 받는지 확인합니다.
8. 스펙에 필요한 코드만 수정합니다.
9. 테스트와 정적 검사를 실행합니다.
10. diff를 확인합니다.
11. 브랜치를 만들고 commit합니다.
12. PR을 생성합니다.
13. CodeRabbit 전체 리뷰를 요청합니다.
14. CodeRabbit 의견을 확인합니다.
15. 타당한 의견만 반영합니다.
16. 다시 테스트합니다.
17. 추가 commit을 push합니다.
18. CodeRabbit 증분 리뷰를 요청합니다.
19. 남은 의견을 다시 검토합니다.
20. 최종 diff와 위험을 정리합니다.

이 흐름의 핵심은 반복입니다.

1. 이슈
2. 스펙
3. 구현
4. 검증
5. 리뷰
6. 판단
7. 반영
8. 재검증

리뷰가 있다고 해서 무조건 반영하지 않고, 반영했다고 해서 바로 끝내지 않습니다. 다시 검증하고 다시 리뷰합니다.

 

이 방식의 장점

이 사이클을 사용하면 다음 장점이 있습니다.

• 스펙 밖 구현을 줄일 수 있습니다.
• PR 범위가 작고 명확하게 유지됩니다.
• CodeRabbit 제안을 무비판적으로 반영하지 않게 됩니다.
• API 계약을 깨뜨릴 위험을 줄일 수 있습니다.
• 최종 응답에서 변경 이유와 테스트 결과를 확인할 수 있습니다.
• 사람 리뷰어가 PR 의도를 이해하기 쉬워집니다.
• 나중에 이슈와 PR을 통해 변경 이유를 추적할 수 있습니다.

특히 AI와 함께 개발할 때 중요한 것은 속도보다 통제입니다.
AI가 빠르게 코드를 만들 수 있어도, 그 코드가 스펙과 이슈 범위 안에 있어야 의미가 있습니다.

 

정리

현재 작업 사이클은 단순 자동화가 아닙니다.
AGENTS.md와 프롬프트를 통해 AI의 작업 방식을 프로젝트에 맞게 제한하고, Issue와 Spec으로 작업 기준을 고정하며, CodeRabbit을 보조 리뷰어로 활용하는 구조입니다.

AI에게 코드를 맡기는 것이 아니라 AI가 따라야 할 작업 기준을 먼저 정하고, 그 기준 안에서 구현과 리뷰를 반복하게 만드는 방식입니다.

저는 이슈를 통해 작업 목적과 범위를 고정하고 스펙을 통해 구현 기준을 명확히 합니다.
AGENTS.md를 통해 AI가 따라야 할 작업 규칙을 정합니다.
CodeRabbit을 통해 보조 리뷰를 받고, 그 제안을 다시 이슈와 스펙 기준으로 검토합니다.

결국 이 흐름은 다음 목표를 가집니다.

스펙 → 구현 → 검증 → 리뷰

스펙을 먼저 읽고, 필요한 것만 구현하고, 테스트로 검증하고, 리뷰를 통해 다시 확인합니다.
이 과정을 반복하면 AI를 사용하더라도 PR의 목적과 코드 품질을 더 안정적으로 유지할 수 있습니다.

또한, 이러한 워크플로우를 자동화 함으로써 이슈를 처리하면 코드 구현부터 리뷰, 재검증까지 한번의 싸이클로 가져갈 수 있습니다.