구체적인 수리 지침에서 일반화된 설계·작업 원칙으로 (2026-09-14)
- 기간: 2026-09-14, 사용자 지시로 설계 원칙 정리·원문 게시·작업 전 필독 반영.
- 앱 반영: main 92b6d73, AGENTS.md 한 파일. 사용자 관리자 main 직행 지시와 순수 문서 CI 예외 적용. 앱 코드·DB·Edge 변경 없음.
- 문서 반영: 이 기록과 함께 문서 저장소 main으로 반영하는 변경. 실제 병합·게시 상태는 해당 PR 및 배포 기록을 따른다.
- 정본: 설계·작업 원칙, 문서 최상위 AGENTS.md, 앱 최상위 AGENTS.md.
- 검증 명령: Node 22에서
npm run check,npm run build:docs,npm run check:docs-artifact; 원칙 본문 일치 및 제목·설명 문단 확인. 새 제품 테스트나 자동 열람 강제 기능은 추가하지 않는다.
1. 배경
대량 통계 처리의 국소적인 수리와 전체 요청을 일부 사례로 축소한 완료 보고를 계기로, 사용자가 설계·작업 원칙의 명문화를 요청했다.
2. 문제 제기
원칙을 여러 절·표·구체적인 구현 예제로 적으면 판단 기준이 흐려지고 특정 방식에 고정될 수 있다. 지침 링크만 두면 작업의 첫 진입점에서 원문을 바로 확인하기 어렵다.
3. 해결 방안
23개 동등한 번호 항목에 제목과 설명을 분리했다. SOLID 전체와 목표 보존·완료 대조, 확장성·자원 사용·효율·멱등성·복구·일관성·동시성·재현성·검증·정직한 보고를 일반화했다. 배치·증분·특정 동시성 제어를 의무화하는 대신 요구와 근거로 대안을 선택하도록 했다. 기존안과 새로운 대안을 같은 기준으로 비교하고 작은 실험으로 불확실성을 확인한다.
4. 적용한 내용
앱과 문서 저장소 최상위 AGENTS.md에 원칙 원문을 넣었다. 모든 Barbelic 작업이 앱 AGENTS.md를 반드시 읽고 시작하도록 최상위·공통·저장소 경계 문서와 로컬 Codex 전역 지침에 명시했다. 문서 홈·README·메뉴에서 원칙 문서를 연결했다. 기존 앱 AGENTS 링크 전용 정책은 이번 사용자 지시에 따른 원문 보관 예외로 갱신했다.
5. 적용 결과
문서의 여러 계층·표·장애 사례를 23개 일반 원칙으로 정리했다. 앱 main에는 23개 원칙과 필독 지시가 직접 들어간다. 원문 동일성은 게시할 문서 및 앱 파일과 대조하며 검증 결과는 PR 본문에 남긴다. 제품 성능 개선이나 모든 세션의 실제 준수를 검증한 기록은 아니다.
6. 이번 개선으로 향상된 것
작업자는 첫 진입 파일에서 목표·설계·완료 판단 기준을 읽을 수 있다. 구체적인 구현 수단을 고정하지 않으면서 데이터 보호와 정확성, 더 나은 대안 탐색의 기준을 유지한다.
남은 것
작업별 실제 적용과 준수 여부는 해당 작업의 근거로 확인한다. 사용자가 중단시킨 HQ 조율·작업 간 메시지 전파·타이머는 재개하지 않는다.