AI Project Control Board 구축 하기

프로젝트 소개

AI Project Control Board는 AI coding agent와 함께 프로젝트를 진행할 때 필요한 문서, 작업 상태, 검증 기준을 한 화면에서 관리하는 로컬 웹앱입니다.
AI와 개발을 함께할 때는 단순히 “코드를 작성해줘”라고 요청하는 것만으로는 부족합니다.

요구사항, 구현 계획, 작업 범위, 테스트 기준, 변경 기록을 명확히 남겨야 작업이 안정적으로 이어집니다.

이 프로젝트는 이런 문서 기반 개발 흐름을 비개발자도 이해할 수 있도록 시각화하는 데 초점을 맞췄습니다.

만들게 된 배경

AI coding agent는 빠르게 코드를 작성할 수 있습니다. 

하지만 작업 범위가 불명확하면 기존 구조를 깨뜨리거나, 충분한 검증 없이 기능을 완성했다고 판단할 위험이 있습니다.

(마침!  아래 글에서 AI 프로젝트를 진행할 때 도움이 되는 템플릿을 구축했기 때문에 이것의 테스트겸 진행 하였습니다.)
이 프로젝트에서는 다음 문제를 해결하고자 했습니다.

- 현재 프로젝트가 어떤 단계에 있는지 한눈에 보기 어렵다.
- spec.md, plan.md, tasks.md 같은 문서를 직접 찾아 읽어야 한다.
- AI에게 전달할 작업 지시문과 완료 기준이 매번 달라진다.
- 변경 내역과 테스트 결과가 흩어져 있어 비개발자가 검토하기 어렵다.

이를 해결하기 위해 문서 중심의 AI 개발 템플릿을 시각적인 컨트롤 보드로 만들었습니다.

 

핵심 기능

워크플로우 단계 시각화

요구사항, 계획, 작업, 테스트, 변경 기록, 결정 기록을 왼쪽 내비게이션으로 구분했습니다. 

사용자는 현재 프로젝트가 어느 단계에 있는지, 다음에 무엇을 확인해야 하는지 빠르게 파악할 수 있습니다.

기능별 Spec 관리

각 기능은 specs/<feature-name>/ 폴더 아래에서 관리됩니다. 기능별로 다음 문서를 두도록 구조화했습니다.

spec.md
plan.md
tasks.md
acceptance-tests.md
change-log.md

이 구조를 통해 화면의 기능 카드와 실제 문서 경로가 1:1로 연결되도록 했습니다.

문서 상태 동기화

초기에는 앱 내부 데이터만으로 상태를 표시했습니다.

이후 실제 Markdown 문서 상태와 보드 화면을 연결하는 방식으로 개선했습니다.
scripts/board-sync.js는 실제 문서 파일을 읽어 .control-board/state.json과 src/board-state.json을 생성합니다. 

문서가 추가되거나 변경되면 보드에서도 최신 상태를 확인할 수 있습니다.

작업 맵과 칸반 보드

작업 화면에서는 기능과 태스크의 관계를 마인드맵 형태로 보여줍니다.

홈 화면에서는 기능 상태를 칸반 보드로 나누어 표시했습니다.

이를 통해 검토 필요, 진행 중, 승인됨, 막힘 상태를 쉽게 구분할 수 있습니다.

검증과 인수인계 흐름

테스트 기록, 변경 로그, ADR을 별도 화면으로 구성했습니다.

기능을 구현하는 데서 끝내지 않고, 어떤 검증을 했는지와 어떤 위험이 남아 있는지 함께 남기는 구조입니다.

 

기술 스택

이 프로젝트는 로컬 우선 정적 웹앱으로 설계했습니다.

HTML
CSS
JavaScript
localStorage
Node.js 기반 동기화 스크립트
Markdown 문서 기반 프로젝트 템플릿

초기 버전에서는 백엔드나 복잡한 빌드 도구 없이 브라우저에서 바로 실행할 수 있도록 구현했습니다.

 

주요 설계 결정

가장 중요한 결정은 로컬 우선 정적 앱으로 시작한 것입니다.
비개발자가 사용하는 도구이기 때문에 설치 과정이나 서버 실행이 복잡하면 안 된다고 판단했습니다. 

그래서 첫 버전은 src/index.html을 브라우저에서 여는 것만으로 실행되게 만들었습니다.
제품 전체 문서와 기능별 문서를 분리한 것도 중요한 결정이었습니다. 

처음에는 하나의 spec에 모든 내용을 누적했지만, 기능이 늘어나면서 관리가 어려워졌습니다. 

이후 기능별 spec 폴더를 도입해 각 기능의 요구사항, 계획, 작업, 테스트, 변경 기록을 독립적으로 추적할 수 있게 했습니다.

검증 방식

기능 구현 후에는 다음 방식으로 검증했습니다.

node --check src/app.js
./scripts/run_tests.sh
상태 파일 JSON 파싱 검증
필수 spec 폴더 및 문서 존재 여부 확인
보드 상태 동기화 스크립트 실행 확인

특히 작업 완료 전에는 node scripts/board-sync.js를 실행해 실제 문서 상태와 보드 상태가 어긋나지 않도록 확인했습니다.

---

배운 점

이 프로젝트를 만들며 가장 크게 배운 점은 AI 협업에서 중요한 것이 단순한 자동화가 아니라, 작업의 기준을 명확히 세우는 일이라는 점입니다.
AI는 빠르게 결과물을 만들 수 있습니다. 

하지만 무엇을 기준으로 작업해야 하는지, 어떤 파일을 수정할 수 있는지, 완료 기준은 무엇인지가 명확해야 안정적으로 활용할 수 있습니다.
이 프로젝트에서도 기능 구현만 보여주는 것보다 설계 결정, 변경 이유, 검증 결과를 함께 남기는 편이 프로젝트의 완성도를 더 잘 보여준다는 점을 체감했습니다.

 

마무리

AI Project Control Board는 AI coding agent와의 협업을 더 안전하고 예측 가능하게 만들기 위한 보드입니다.
단순히 AI에게 코드를 맡기는 방식이 아니라, 

요구사항, 작업 범위, 테스트 기준, 변경 기록을 문서와 UI로 연결해 프로젝트를 관리하는 방식에 초점을 맞췄습니다. 

이를 통해 비개발자도 AI 개발 흐름을 검토할 수 있고, 개발자는 더 명확한 기준 안에서 작업할 수 있는 구조를 만들고자 했습니다.

https://github.com/yaho-nice1/AI-Project-Control-Board

GitHub - yaho-nice1/AI-Project-Control-Board

 

---

TMI

처음 UI를 설계할 때는 AI가 화면을 너무 자유롭게 만들어서, 원하는 형태로 고정하는 데 시간이 꽤 걸렸다.
이후에는 원하는 UI를 직접 그리고, 그 이미지를 프롬프트와 함께 구글의 Stitch에 전달해 화면 초안을 만들었다.

그 결과물을 바탕으로 적용하니 프론트 작업을 훨씬 쉽게 마무리할 수 있었다.
프론트 화면을 2~3분 만에 뽑아주는 걸 보며 기술 발전 속도가 정말 빠르다는 것을 체감했다.

 

아주 마음대로 뽑아놓은 codex

 

stitch 의 은총...!

 

이후 조금 더 수정한 완성본.. 감격스럽다

 

이제 다른 프로젝트도 이 템플릿 기준으로 마이그레이션 해서 사용해도 좋을 것 같다..