"이름이 아니라 문서에 근거 없는 기능은 만들지 않는다"
백로그에 적힌 작업 이름은 "Process CRUD API"였습니다. 이 이름만 보면 생성, 조회, 수정, 삭제를 전부 구현해야 할 것처럼 보였지만, 실제 API 명세 문서를 확인해보니 정의되어 있는 건 Create Action과 Graph 전용 Action 두 개뿐이었습니다. Process 자체의 Update나 Archive, Delete Action은 어디에도 근거가 없었습니다.
이름을 그대로 믿고 구현했다면 문서에 없는 기능을 만들게 될 뻔했습니다. 대신 스코프를 "Create + 목록 조회"로 명시적으로 제한했습니다. 여기에 더해, ownerRoleId가 실수로 다른 Project 소속 business_role을 잘못 참조하는 걸 막는 검증도 별도로 지시했는데, 이건 RLS가 막는 workspace/project 경계와는 다른 층위의 애플리케이션 레벨 검증이었습니다.
구현된 코드를 확인해보니, ownerRoleId 검증이 id와 project_id 두 조건을 동시에 거는 쿼리로 정확히 구현되어 있었습니다. workspace_id도 클라이언트가 보낸 값이 아니라 서버가 직접 조회한 project row에서 가져오도록 되어 있어, 값을 조작해서 다른 workspace를 노릴 수 없는 구조였습니다.
이 작업으로 확인한 건, 작업 이름이 실제 요구사항의 범위를 정확히 반영하지 않을 수 있다는 점입니다. "CRUD"라는 이름과 달리 문서에 실제로 있는 건 Create뿐이었고, 이름이 아니라 문서를 기준으로 판단하는 게 옳았습니다.
작업 이름이 실제 요구사항보다 넓게 붙여진 경우, 이름을 그대로 따라가면 문서에 없는 Update/Delete Action을 만들게 되는 위험이 있었습니다. 문서에 근거 없는 기능은 만들지 않는다는 원칙을 이번에 적용해, 이름이 아니라 실제 API 명세를 기준으로 스코프를 좁혔습니다.
관련 프로젝트
프로젝트 개요 비즈니스 프로세스 트랜스포메이션(BPR)을 지원하는 한국어 기반 웹 애플리케이션. 컨설팅 프로젝트의 AS-IS 프로세스 분석부터 TO-BE 설계, Blueprint 승인까지의 전체 워크플로우를 디지털화하는 플랫폼으로, EPIC 단위로 구조화된 백로그를 기반으로 개발 중. 역할 및 워크플로우 PM / Architect / Reviewer 역할 수행 Codex(구현 담당)에게 Task 단위 구현 프롬프트 설계 Codex 구현 결과를 git log, git grep, git status로 직접 검증 후 승인 승인 전에는 Codex가 commit하지 않는 엄격한 게이팅 프로세스 운영 한 번에 하나의 Backlog Task만 진행, Task 완료 전 다음 Task 착수 금지 기술적 의사결정 및 성과 워크스페이스/프로젝트 접근 권한을 DB 레벨(복합 FK, SECURITY DEFINER 트리거)과 애플리케이션 레벨(Server Action 권한 검증)의 이중 방어 구조로 설계 Hard Delete 미구현 원칙 하에 배열 필드 전체교체(replace)를 단일 트랜잭션 RPC로 처리하는 패턴 확립 및 재사용 AS-IS 프로세스 그래프의 순환 참조 탐지에 Tarjan SCC 알고리즘 적용, 차단 오류(Error)와 경고(Warning)를 분리한 이중 Validator 아키텍처 설계 도메인 규칙 위반을 커스텀 Postgres 에러 코드 체계(SIA0104)로 문서화하여 거버넌스 문서와 코드베이스 간 정합성 유지 AI 생성 데이터와 사람이 검증한 데이터를 구분하는 generatedbyai / verified 메타데이터 패턴을 여러 도메인 테이블에 일관되게 적용 진행 상태 ✅ EPIC-01 (인증 / 워크스페이스 / 프로젝트 접근) ✅ EPIC-02 (조직 / 산업 / 프로젝트) 🚧 EPIC-03 (AS-IS 프로세스 그래프) — 그래프 검증, Input/Output 스키마, Business Rule 스키마 구현 완료