정지섭의 프로젝트

이 프로젝트는 코딩 에이전트 활용 역량을 높이기 위해 기획과 설계부터 구현, 검증, 장애 분석까지 Codex와 협업하여 개발한 풀스택 커뮤니티 게시판입니다. 단순히 코드를 생성하는 방식이 아니라, 사용자가 제품 방향과 요구사항을 결정하고 에이전트가 설계안·영향 범위·검증 결과를 보고하면 이를 검토하고 승인하는 구조로 진행했습니다. 1. 에이전트 중심 개발 프로세스 저장소의 AGENTS.md에 기술 스택, 계층별 책임, 문서 동기화 규칙, 데이터베이스 안전 수칙과 완료 기준을 정의했습니다. 이를 통해 에이전트가 매 작업마다 동일한 개발 원칙을 따르고, 기존 코드나 사용자의 작업 내용을 임의로 훼손하지 않도록 통제했습니다. 백엔드와 UI·UX처럼 전문적인 판단이 필요한 작업에는 목적에 맞는 SKILL.md를 적용했습니다. 기능을 바로 구현하도록 지시하지 않고 요구사항 분석, 설계 제안서 작성, 사용자 검토와 승인, 구현, 자동 검증 순서로 작업을 분리했습니다. 2. 문서 기반 설계와 구현 backend/docs를 구현 계약으로 사용하여 REST API, 데이터베이스 테이블과 인덱스, 인증·보안 정책, 트랜잭션 범위와 운영 기준을 문서화했습니다. API가 변경되면 관련 문서와 OpenAPI, SQLAlchemy 모델, Alembic 마이그레이션, schema.sql과 seed.sql이 함께 변경되도록 에이전트의 작업 범위를 지정했습니다. 백엔드는 FastAPI의 router-service-repository 구조로 구성했습니다. Router는 HTTP 입출력, Service는 권한과 유스케이스 및 트랜잭션, Repository는 SQLAlchemy 비동기 데이터 접근을 담당하도록 역할을 분리했습니다. 프론트엔드는 React 19와 TypeScript를 기반으로 페이지, 도메인 기능, API 클라이언트, 공통 UI를 분리했습니다. 3. 주요 기능 JWT HttpOnly 쿠키와 회전식 Refresh Token, CSRF 검증을 적용해 브라우저 인증을 구현했습니다. 게시글은 리치 텍스트 편집을 지원하지만 서버에서 허용 목록 기반으로 HTML을 정제한 결과만 저장하고 출력하도록 구성했습니다. 본문 이미지와 일반 첨부파일은 별도의 API와 저장 정책으로 관리했습니다. 게시글 검색·필터·정렬·페이지네이션, 댓글과 1단계 대댓글, 좋아요, 작성자·관리자 권한 제어를 구현했습니다. 3. 에이전트를 활용한 품질 검증 기능 구현 후 에이전트가 pytest와 Vitest 테스트, ESLint, TypeScript 검사와 Vite 프로덕션 빌드를 실행하도록 했습니다. OpenAPI 경로와 설계 문서의 일치 여부, Markdown 상대 링크, Git diff 오류도 함께 검사했습니다. 데이터베이스 변경은 테스트 코드만 통과하는 것으로 끝내지 않았습니다. 별도의 빈 MySQL 스키마를 생성해 Alembic 전체 마이그레이션을 처음부터 적용하고, schema.sql 실행과 seed.sql 반복 실행 결과까지 확인했습니다. 검증에 사용한 임시 데이터베이스는 대상 이름을 명확히 확인한 후 제거하도록 해 실제 개발 데이터를 보호했습니다. 이 프로젝트를 통해 코딩 에이전트의 결과 품질은 프롬프트의 길이보다 명확한 작업 규칙, 문서화된 계약, 단계별 승인, 자동화된 완료 기준과 사용자의 지속적인 검토에 의해 결정된다는 점을 학습했습니다. 사용자는 제품 결정과 작업 지시 및 최종 검토를 담당하고, Codex는 설계 대안 제시, 구현, 테스트와 반복 검증을 수행하는 협업 구조를 구축했습니다.