AI 작업의 방향과 완료 기준을 관리하는 SDAD 워크플로우를 공유합니다

안녕하세요. 프로젝트를 진행하면서 정리한 AI 작업 운영 방식인 SDAD(SPEC-Directed AI Development)를 공유해 보려고 합니다.

AI에게 기능 구현이나 문서 작성을 맡기면 빠르게 결과를 얻을 수 있지만, 작업이 길어질수록 다음과 같은 문제가 생기곤 합니다.

• 처음 요청한 범위와 다른 방향으로 작업이 진행됨

• AI가 “완료했다”고 하지만 실제 테스트나 근거가 부족함

• 대화나 세션이 바뀌면 이전 작업의 맥락을 잃음

• 현재 어떤 작업이 진행 중이고 무엇이 남았는지 파악하기 어려움

• 사용자가 방향을 바꿨는데도 AI가 기존 계획을 계속 수행함

SDAD는 이런 문제를 줄이기 위해 만든 저장소 기반 AI 작업 운영 규칙입니다.

프로젝트 링크:

https://github.com/LiveTrack-X/spec-driven-ai-development

SDAD는 무엇인가요?

SDAD는 새로운 AI 모델이나 코딩 도구가 아닙니다.

AI가 작업할 때 다음 내용을 프로젝트 안에 명확하게 유지하도록 만드는 운영 방식입니다.

• 무엇을 만들어야 하는지: SPEC

• 현재 어디까지 작업할 수 있는지: 작업 범위

• 어떤 문서를 참고해야 하는지: 문서 경로

• 완료를 주장하려면 무엇을 확인해야 하는지: 검증과 증거

• 어떤 행동에서 사람의 승인이 필요한지: Owner Gate

• 다음 작업이나 세션이 어디서 이어받아야 하는지: Handoff

여기서 Owner는 AI에게 최종 방향과 권한을 부여하는 사람을 의미합니다.

구현 방법은 SDAD가 강제하지 않습니다. TDD, 일반적인 기능 개발 방식, 다른 에이전트 워크플로우 등 어떤 방법을 사용하더라도 그 위에서 작업 범위와 완료 근거를 관리할 수 있습니다.

어떻게 시작하나요?

파일을 수정할 수 있는 AI 코딩 도구에서 프로젝트를 연 뒤, 저장소 README의 Copy-Paste Start Prompt를 한 번 붙여 넣으면 됩니다.

Codex, Claude Code, Gemini CLI, Cursor, Copilot Chat이나 범용 AI 에이전트에서 사용할 수 있도록 구성했습니다.

AI는 현재 요청과 프로젝트 상태를 확인한 뒤 작업 규모를 선택합니다.

규모	적합한 상황
One-shot	현재 요청만 처리하고 관리 문서를 남길 필요가 없는 작업
Mini	작은 기능이나 버그 수정
Standard	여러 세션에 걸쳐 진행되거나 TODO·검토·상태 관리가 필요한 작업
Full	배포, 마이그레이션, 보안, 실제 데이터 등 사람의 승인이 중요한 작업

설치 이후에는 긴 시작 프롬프트를 매번 붙여 넣을 필요가 없습니다. 프로젝트에 설치된 규칙과 현재 상태를 읽어 작업을 이어갑니다.

단, 일반적인 웹 채팅처럼 프로젝트 파일을 직접 수정할 수 없는 환경에서는 계획과 SPEC 작성까지만 사용할 수 있습니다.

기본 작업 루프

SDAD의 기본 작업 흐름은 다음과 같습니다.

1. Plan

목표, 작업 범위, 완료 조건, 필요한 검증과 사람의 승인 지점을 정합니다.

2. Route

현재 작업에 필요한 문서와 코드만 선택해서 읽습니다.

프로젝트의 모든 문서를 무조건 읽는 것이 아니라, 현재 상태와 작업 목적에 필요한 정보만 불러오는 방식입니다.

3. Implement

변경 내용을 작고 검토 가능한 단위로 구현합니다.

4. Verify

테스트와 검증을 실행하고, 성공한 내용뿐 아니라 확인하지 못한 부분과 한계도 함께 기록합니다.

5. Report

변경된 파일, 실행한 검사, 결과, 남은 문제와 필요한 Owner 결정을 포함한 보고를 제출합니다.

Plan → Route → Implement → Verify → Report

AI가 단순히 “완료했습니다”라고 말하는 것만으로는 작업이 끝난 것으로 보지 않습니다.

검증 결과가 준비된 evidence-ready 상태와, 사람이 결과를 확인하고 받아들인 owner-accepted 상태를 구분합니다.

개발 워크플로우와의 관계

소프트웨어 개발에서는 다음과 같은 흐름을 사용할 수 있습니다.

Plan → Implement → Test → Ship → Merge → Release

SDAD는 이 흐름을 대체하려는 것이 아닙니다.

브랜치 생성, 테스트, 커밋, 머지, 배포 같은 실제 개발 절차는 기존 방식대로 진행하고, SDAD는 그 위에서 다음을 관리합니다.

• 현재 어떤 기능을 작업하고 있는가

• AI가 어디까지 진행해도 되는가

• 어떤 검증이 필요한가

• 언제 사람의 판단이 필요한가

• 다음 작업은 어디서 이어져야 하는가

그래서 소프트웨어 개발뿐 아니라 조사, 문서 작성, 분석, 장기적인 에이전트 작업에도 적용할 수 있도록 비교적 중립적인 구조로 만들었습니다.

최근 v3.2.2에서 보강된 부분

현재 적용 가능한 Owner의 지시는 이전 계획보다 우선합니다.

작업 도중 방향이 변경되면 AI는 기존 방향의 작업을 계속 밀어붙이지 않고, 영향을 받는 작업을 멈춘 뒤 다시 Plan → Route 단계로 돌아가 SPEC과 현재 상태를 정리해야 합니다.

또한 반복해서 발생하는 불편이나 중요한 통제 누락은 단순히 규칙을 계속 추가하는 방식이 아니라 다음 흐름으로 관리합니다.

문제와 근거 확인
→ 원인 분석
→ 가장 작은 지속 가능한 규칙 적용
→ 재발 방지 검증
→ 실제 사용
→ 유지 / 개선 / 통합 / 폐기 결정

장기간 작업에서는 현재 작업 단위와 Handoff의 연결도 더 명확하게 관리하도록 보강했습니다.

현재 상태를 보기 위한 SDAD Inspector

SDAD 프로젝트는 여러 상태 문서와 작업 기록을 사용하기 때문에, 사람이 파일을 하나씩 찾아보지 않고도 현재 상황을 확인할 수 있도록 별도의 컴패니언 앱을 만들고 있습니다.

https://github.com/LiveTrack-X/sdad-inspector

SDAD Inspector에서 프로젝트 폴더를 선택하면 다음 내용을 한 화면에서 확인하기 쉽게 보여줍니다.
 

• 현재 활성화된 SPEC과 작업 단위

• 남아 있는 TODO와 완료된 작업

• 현재 작업 단계

• 관련 문서와 검증 자료

• 다음 세션으로 이어지는 Handoff

• 각 상태 값이 어떤 파일에서 나온 것인지

Inspector는 프로젝트를 수정하거나 테스트를 대신 실행하는 도구가 아니라, 현재 상태를 사람이 이해하기 쉽게 보여주는 읽기 전용 뷰어입니다.

SDAD가 보장하지 않는 것

SDAD를 적용했다고 해서 코드가 자동으로 정확해지거나 생산성이 반드시 높아지는 것은 아닙니다.

SDAD Doctor 검사가 통과했다는 것도 문서와 상태 구조가 서로 일치한다는 의미이지, 다음을 증명하지는 않습니다.

• 기능이 올바르게 동작한다

• 테스트가 충분하다

• 생산성이 향상되었다

• Owner가 결과를 승인했다

• 실제 운영 환경에서도 안전하다

테스트, 코드 리뷰, CI/CD, 권한 관리와 최종 판단은 별도로 필요합니다.

저는 현재 SDAD로 AI 작업의 방향·범위·검증을 관리하고, Inspector로 사람이 현재 상태를 확인하는 방식으로 사용하고 있습니다.

 

다른 분들은 장기간 AI 작업에서 다음 내용을 어떻게 관리하고 계신지도 궁금합니다.

• 세션이 바뀌어도 작업 맥락을 유지하는 방법

• AI가 완료했다고 주장할 때 요구하는 검증 자료

• 사람의 승인을 어느 단계에 배치하는지

• 브랜치·머지·배포 흐름과 AI 작업 규칙을 연결하는 방법

각자의 워크플로우나 개선 의견이 있다면 공유 부탁드립니다!

추신 / 처음 작성을 모바일로 먼저하다보니 정돈이 안된 글이 먼저 올라갔어서 다시 수정해 올립니다.