GitHub Copilot 에이전트 코딩 통제 지침서

🚫 절대 금지 사항

파일 및 프로젝트 구조 관련

• 파일 재생성 금지: 기존 파일이 있다면 절대 새로 생성하지 말고 수정만 진행
• 무분별한 개발서버 시작 금지: npm run dev, yarn dev 등 터미널 명령어 무단 실행 금지
• 프로젝트 구조 임의 변경 금지: 기존 폴더 구조와 파일 위치를 존중하고 따라야 함
• 설정 파일 무단 수정 금지: package.json, tsconfig.json, next.config.js 등 함부로 건드리지 말 것

코딩 패턴 관련

• 단일 파일 몰아넣기 금지: 하나의 컴포넌트 파일에 모든 로직을 집약하는 행위 엄금
• 관념적 코딩 금지: 실제 동작하지 않는 추상적이거나 가상의 코드 작성 금지
• 과도한 복잡화 금지: 간단한 기능을 불필요하게 복잡하게 구현하는 행위 금지
• 임의 설계 변경 금지: 기존 아키텍처와 설계 패턴을 무시하고 독단적으로 변경 금지

✅ 필수 준수 사항

의존성 체인 검증

1. 타입스크립트 파일 작성 전 필수 확인

   • 해당 모듈의 실제 export 구조 확인
   • 임포트할 메서드/타입의 정확한 이름과 경로 확인
   • 의존성 패키지의 실제 API 문서 참조

2. 메서드명 정확성 검증

   • 추측성 메서드명 사용 금지
   • 실제 존재하는 메서드만 사용
   • 오타나 잘못된 카멜케이스 방지

3. 임포트 경로 검증

   • 상대 경로와 절대 경로 정확성 확인
   • 존재하지 않는 경로로의 임포트 금지
   • 순환 참조 방지

백엔드 연동 규칙

1. API 엔드포인트 정확성

   • 실제 백엔드 API 스펙에 맞는 요청만 작성
   • 임의의 엔드포인트 생성 금지
   • 요청/응답 타입 정의 필수

2. 데이터베이스 구조 준수

   • 기존 DB 스키마와 일치하는 데이터 구조만 사용
   • 존재하지 않는 테이블이나 컬럼 참조 금지
   • 관계형 데이터 무결성 고려

프론트엔드 컴포넌트 규칙

1. 컴포넌트 분리 원칙

   • 단일 책임 원칙 준수
   • 재사용 가능한 컴포넌트와 페이지별 컴포넌트 구분
   • 적절한 props 인터페이스 정의

2. 상태 관리 일관성

   • 기존 상태 관리 패턴 준수
   • 전역 상태와 로컬 상태 적절히 구분
   • 불필요한 상태 중복 방지

🔍 코드 작성 전 검증 체크리스트

타입스크립트 파일 작성 시

• [ ] 임포트할 모듈이 실제로 존재하는가?
• [ ] 사용할 메서드가 해당 모듈에 실제로 정의되어 있는가?
• [ ] 타입 정의가 정확하고 일관되는가?
• [ ] 기존 코드 스타일과 일치하는가?

백엔드 연동 코드 작성 시

• [ ] API 엔드포인트가 실제로 구현되어 있는가?
• [ ] 요청 데이터 형식이 백엔드 스펙과 일치하는가?
• [ ] 에러 처리가 적절히 구현되어 있는가?
• [ ] 인증/권한 체크가 필요한 API인가?

컴포넌트 작성 시

• [ ] 해당 기능이 기존 컴포넌트에 추가될 수 있는가?
• [ ] 새 컴포넌트 생성이 정말 필요한가?
• [ ] props 인터페이스가 명확하게 정의되었는가?
• [ ] 컴포넌트 간 의존성이 최소화되었는가?

⚠️ 특별 주의사항

하드코딩 허용 범위

• 소개 페이지: 정적 콘텐츠의 하드코딩 허용
• 상수 값: 설정 관련 상수는 별도 파일에 정의
• 더미 데이터: 개발 중 임시 데이터는 명확히 표시하고 분리

금지된 개발 습관

• 코드 작성 후 "일단 돌아가면 된다" 식 접근
• 실제 테스트 없이 "동작할 것이라 예상" 하는 코드 작성
• 에러 메시지 무시하고 강제로 진행
• 타입 에러를 any로 회피하는 행위

문제 발생 시 대응 방법

1. 에러 분석: 에러 메시지를 정확히 읽고 원인 파악
2. 문서 참조: 공식 문서나 타입 정의 확인
3. 점진적 해결: 한 번에 모든 것을 고치려 하지 말고 단계별 해결
4. 기존 코드 활용: 프로젝트 내 유사한 구현 패턴 참조

📋 코드 리뷰 기준

필수 점검 항목

• 실제 동작 가능성 100% 확신
• 타입 안정성 확보
• 기존 아키텍처와의 일관성
• 성능 및 유지보수성 고려
• MVC 아키텍처 준수: 각 계층의 역할과 책임 명확히 분리
• 설치된 패키지 활용: 의존성 체인 정확성 검증
• 토스트 시스템 적용: console.log 대신 사용자 친화적 알림
• 라라벨 스타일 효율성: 최고 효율적인 구조와 패턴 적용

리젝트 기준

• 추측성 코드 구현
• 테스트되지 않은 API 호출
• 불필요한 복잡성 도입
• 기존 패턴과의 불일치
• console.log 사용: 디버깅용 console.log 발견 시 즉시 리젝트
• MVC 패턴 위반: 계층 간 역할 혼재 또는 잘못된 의존성
• 새 파일 무분별 생성: 기존 파일 수정 가능한 상황에서 새 파일 생성
• 패키지 의존성 오류: 설치되지 않은 패키지 사용 또는 잘못된 메서드 호출

---

이 지침서를 준수하지 않는 코드는 즉시 리젝트되며, 재작업을 요구합니다. 특히 MVC 아키텍처 위반, console.log 사용, 새 파일 무분별 생성은 무조건 리젝트됩니다.

 

 

필요한 부분만 수정해서 사용하시면 좋을 거 같네요!