2025-09-20
오늘 배운 것
📝 AI 코드 지침서
📌 1. 왜 지침서가 필요한가?
- AI를 활용해 코드를 작성/리팩토링할 때, 허용 범위와 금지 영역을 명확히 구분하지 않으면 위험 발생
- 예: 보안 설정(application.yml) 수정, 시크릿 키 노출
- 사람 리뷰어와 AI가 협업할 때 기준이 없으면, 산출물이 들쭉날쭉해져서 관리 어려움
- 따라서 AI도 일관된 규칙을 따르도록 전용 컨벤션을 만들 필요가 있음
📌 2. 지침서 작성 시 고려할 점
🔹 라우팅(Routing)
- AI가 작업 전 어떤 문서/컨벤션을 확인해야 하는지 정의
- Frontend / Backend 분리
- PRD, 아키텍처, conventions, docs 참조 위치 지정
🔹 코드 작성 범위(Code Scope)
- AI가 어디를 수정 가능/불가한지 명확히
- 주석 태그(
DO-NOT-TOUCH, CHANGE-ZONE, EDIT-ALLOWED, SENSITIVE) 활용
- 태그 없는 영역은 원칙적으로 읽기 전용
- 코드: 언어 블록 + 한글 설명 주석
- 문서: Markdown 표준 (헤더, 목록, 표)
- 테스트: 각 기술 스택별 전략(Jest, JUnit)
- API: JSON + 공통 응답 스키마(BaseResponse)
- 로그/주석: 변경 이유 기록
🔹 리팩토링 & 최적화
- 우선순위: 안전성 > 가독성 > 성능
- 불필요한 변경 금지
- 대규모 리팩토링은 반드시
record.md, PROMPTLOG.md 기록
- 회고 시 재분석
🔹 로깅 & 회고
- 모든 성공/실패 기록은
PROMPTLOG.md에 남김
- 요약은
record.md, 심화 분석은 retrospectives/
- 회고 템플릿 (Keep / Problem / Try) 활용
- 실패 원인 → 개선 포인트 → 다음 사이클에 반영
🔹 보안 & 민감정보
- 환경 변수/시크릿 절대 수정 금지
- 실제 값 대신 가짜 데이터(FAKE_API_KEY 등) 사용
- 민감정보 로그/출력 금지
- 보안 위반 발생 시 반드시 회고에 기록
📌 3. 느낀 점
- AI와 협업할 때 사람처럼 “규칙”을 주는 게 핵심
- “무엇을 하면 안 되는지”보다 “허용되는 영역을 제한적으로 열어두는 방식이 안전함
- 단순 코드 스타일 가이드가 아니라 AI 워크플로우 가이드가 되어야 함
- 회고록과 로그 기록을 남기면, 반복된 실패/성공 패턴을 데이터로 관리 가능
- 결국 AI는 “도구”가 아니라 팀원의 역할에 가깝기 때문에, 컨벤션 설계가 필수
✅ 앞으로의 적용 아이디어
- 새로운 프로젝트 시작 시, ai-guidelines 디렉토리 템플릿을 복사해 바로 활용
- 팀별 컨벤션 + AI 지침을 묶어 MCP(멀티 에이전트 협업) 가이드북으로 확장
- 회고 주기(1~2주)마다 AI 활용 개선안을 규칙 문서에 업데이트
