AI Coding Workflow

AI Coding Workflow

AI로 프로젝트를 진행하면 처음에는 속도가 빠르다.

요구사항을 입력하면 코드가 생성된다.

수정 요청을 하면 다시 코드가 바뀐다.

 

하지만 프로젝트가 커질수록 문제가 생긴다.

 

코드가 여러 곳에서 바뀐다.

왜 바뀌었는지 추적하기 어렵다.

처음 의도와 다른 리팩터링이 섞인다.

작업 방향성이 점점 흐려진다.

결국 사람이 AI가 만든 변경을 다시 해석하고 검증하는 데 더 많은 시간을 쓰게 된다.

 

이 문제는 단순히 프롬프트를 잘 쓰면 해결되는 문제가 아니다.

AI가 코드를 수정하는 방식을 통제할 수 있는 프로젝트 구조가 필요하다.

 

핵심은 다음과 같다.

"AI에게 바로 코드를 맡기지 않는다."

Spec → Plan → Task →  Code Change → Test → Review → Change Log →  Review → Merge

기본 원칙

1. 프로젝트 전체 규칙을 AGENTS.md에 고정한다.

2. 기능 단위로 spec을 작성한다.

3. 구현 전에 plan을 작성한다.

4. 작업을 작은 task로 나눈다.

5. 수정 가능한 파일을 제한한다.

6. 완료 기준을 테스트와 연결한다.

7. 변경 이유를 기록한다.

8. 중요한 의사결정은 ADR로 남긴다.

9. PR에서 최종 검증한다.

 

---

최소버전

처음 도입할 때는 이 정도면 충분하다.
AI가 바로 코드 수정하지 않고, spec → plan → task → test → change-log 흐름을 타게 만드는 최소 구조다.

 

project-root/
├── AGENTS.md                         # AI coding agent가 반드시 따라야 할 작업 규칙이다.
├── README.md                         # 사람이 프로젝트를 이해하고 실행하기 위한 기본 문서다.
│
├── docs/                             # 프로젝트 전체 기준 문서를 모아두는 곳이다.
│   ├── architecture.md               # 시스템 구조와 데이터 흐름을 설명한다.
│   ├── coding-rules.md               # 코드, SQL, 네이밍, 리팩터링 규칙을 정의한다.
│   └── testing-guide.md              # 테스트 실행 방법과 변경 유형별 필수 테스트를 정의한다.
│
├── specs/                            # 기능 또는 작업 단위 문서를 관리하는 곳이다.
│   ├── _template/                    # 새 기능을 시작할 때 복사해서 쓰는 기본 템플릿이다.
│   │   ├── spec.md                   # 요구사항, 범위, 하지 않을 일을 정의하는 템플릿이다.
│   │   ├── plan.md                   # 구현 전략과 수정 가능 파일을 정의하는 템플릿이다.
│   │   ├── tasks.md                  # 작업을 작은 단위로 나누는 템플릿이다.
│   │   ├── acceptance-tests.md       # 완료 판정 기준과 테스트 기준을 정의하는 템플릿이다.
│   │   └── change-log.md             # 실제 변경 내용과 이유를 기록하는 템플릿이다.
│   │
│   └── example-feature/              # 실제 기능 작업 문서 예시다.
│       ├── spec.md                   # 해당 기능의 요구사항과 작업 범위를 정의한다.
│       ├── plan.md                   # 해당 기능의 구현 계획과 수정 가능 파일을 정의한다.
│       ├── tasks.md                  # 해당 기능의 작업 단위를 정의한다.
│       ├── acceptance-tests.md       # 해당 기능의 완료 기준과 검증 방법을 정의한다.
│       └── change-log.md             # 해당 기능에서 실제로 바뀐 내용과 이유를 기록한다.
│
├── .github/                          # GitHub 관련 설정을 모아두는 곳이다.
│   └── pull_request_template.md      # PR에서 변경 목적, 테스트, 리스크를 검증하는 템플릿이다.
│
├── src/                              # 실제 애플리케이션 또는 파이프라인 코드가 있는 곳이다.
├── tests/                            # 테스트 코드가 있는 곳이다.
└── scripts/                          # 반복 실행할 검증 스크립트를 모아두는 곳이다.

 

 

최소버전에서 꼭 필요한 파일

파일	한줄 요약
AGENTS.md	AI가 따라야 할 작업 규칙을 고정한다.
docs/architecture.md	AI가 전체 구조를 잘못 추론하지 않게 한다.
docs/coding-rules.md	AI가 프로젝트 스타일과 다른 코드를 만들지 않게 한다.
docs/testing-guide.md	AI가 테스트를 생략하지 않게 한다.
specs/_template/spec.md	기능 요구사항을 먼저 문서화하게 한다.
specs/_template/plan.md	코드 수정 전에 구현 계획을 세우게 한다.
specs/_template/tasks.md	큰 작업을 작은 작업으로 나누게 한다.
specs/_template/acceptance-tests.md	완료 기준을 테스트 가능한 형태로 고정한다.
specs/_template/change-log.md	왜 바뀌었는지 기록하게 한다.
.github/pull_request_template.md	merge 전에 변경 범위와 테스트 결과를 검증한다.

 

---

 

메인버전

프로젝트를 계속 운영하거나 데이터 프로젝트, API 프로젝트, 팀 협업까지 고려한다면 이 구조를 추천한다.

 

project-root/
├── AGENTS.md                         # AI coding agent가 반드시 따라야 할 작업 규칙이다.
├── README.md                         # 사람이 프로젝트를 이해하고 실행하기 위한 기본 문서다.
│
├── docs/                             # 프로젝트 전체 기준 문서를 모아두는 곳이다.
│   ├── architecture.md               # 시스템 구조, 계층, 데이터 흐름을 설명한다.
│   ├── coding-rules.md               # 코드 스타일, SQL 규칙, 네이밍 규칙을 정의한다.
│   ├── data-contracts.md             # 테이블, 컬럼, 키, 허용값, downstream 영향을 정의한다.
│   ├── testing-guide.md              # 테스트 명령어와 변경 유형별 필수 테스트를 정의한다.
│   ├── deployment.md                 # 배포 절차, 환경별 차이, 롤백 방법을 정의한다.
│   ├── troubleshooting.md            # 자주 발생하는 문제와 해결 방법을 정리한다.
│   └── data-quality-rules.md         # row count, null, duplicate 등 데이터 품질 기준을 정의한다.
│
├── specs/                            # 기능 또는 작업 단위 문서를 관리하는 곳이다.
│   ├── _template/                    # 새 기능을 시작할 때 복사해서 쓰는 기본 템플릿이다.
│   │   ├── spec.md                   # 요구사항, 배경, 범위, 제외 범위를 정의하는 템플릿이다.
│   │   ├── plan.md                   # 구현 전략, Allowed Files, 리스크를 정의하는 템플릿이다.
│   │   ├── tasks.md                  # 작업을 작은 단위로 나누는 템플릿이다.
│   │   ├── acceptance-tests.md       # 완료 기준, 자동 테스트, 수동 검증 기준을 정의하는 템플릿이다.
│   │   └── change-log.md             # 변경 내용, 변경 이유, 테스트 결과를 기록하는 템플릿이다.
│   │
│   └── feature-name/                 # 실제 기능 또는 변경 작업의 문서 묶음이다.
│       ├── spec.md                   # 해당 기능이 무엇을 해야 하는지 정의한다.
│       ├── plan.md                   # 해당 기능을 어떻게 구현할지 정의한다.
│       ├── tasks.md                  # 해당 기능을 작은 작업 단위로 나눈다.
│       ├── acceptance-tests.md       # 해당 기능이 완료됐는지 판단하는 기준을 정의한다.
│       └── change-log.md             # 해당 기능에서 실제로 바뀐 내용과 이유를 기록한다.
│
├── adr/                              # 중요한 기술적 의사결정을 기록하는 곳이다.
│   ├── 0001-template.md              # ADR 작성 형식을 정의하는 템플릿이다.
│   └── 0002-some-decision.md         # 실제 아키텍처 결정 기록 예시다.
│
├── .github/                          # GitHub 협업 규칙을 관리하는 곳이다.
│   └── pull_request_template.md      # PR에서 변경 목적, 범위, 테스트, 리스크를 검증한다.
│
├── scripts/                          # 반복 작업과 검증 명령어를 자동화하는 곳이다.
│   ├── init-feature.sh               # specs/_template을 복사해 새 기능 문서 폴더를 만든다.
│   ├── run_tests.sh                  # 프로젝트의 기본 테스트를 한 번에 실행한다.
│   ├── validate_schema.py            # 스키마나 데이터 계약 위반 여부를 검증한다.
│   └── compare_model_output.py       # 데이터 변경 전후 결과를 비교한다.
│
├── src/                              # 실제 애플리케이션, 서비스, 파이프라인 코드가 있는 곳이다.
└── tests/                            # unit test, integration test, regression test가 있는 곳이다.

 

디렉터리	한줄 요약
docs/	프로젝트 전체에 계속 적용되는 기준 문서를 둔다.
specs/	기능별 요구사항, 구현 계획, 작업 단위, 완료 기준을 둔다.
adr/	중요한 기술적 결정과 그 이유를 기록한다.
.github/	PR 리뷰와 협업 기준을 고정한다.
scripts/	반복 검증과 기능 문서 생성을 자동화한다.
src/	실제 코드가 위치한다.
tests/	AI 변경을 검증하는 테스트 코드가 위치한다.

 

---

최소버전과 메인버전 차이

구분	최소버전	메인버전
목적	혼자 쓰거나 작은 프로젝트에 빠르게 도입한다.	장기 운영, 데이터 프로젝트, 팀 협업까지 고려한다.
docs	architecture, coding-rules, testing-guide만 둔다.	data-contracts, deployment, troubleshooting, data-quality-rules
specs	spec, plan, tasks, acceptance-tests, change-log를 둔다.	동일하게 두되 feature별 운영을 더 엄격히 한다.
ADR	생략 가능하다.	중요한 결정 기록용으로 포함한다.
scripts	선택 사항이다.	init-feature, run_tests, validate_schema 등을 둔다.
PR template	권장한다.	필수에 가깝다.
적합한 상황	개인 프로젝트, PoC, 작은 기능 개발이다.	실서비스, 데이터 파이프라인, 장기 유지보수 프로젝트다.