Imported from zmfzmf321321-creator/jeju-plant-system (
AGENTS.md). Install upstream withnpx skills add zmfzmf321321-creator/jeju-plant-system. Copyright stays with the author.
AGENTS.md
이 문서는 저장소 전체에 적용되는 AI 작업 규칙입니다. 역할별 세부 책임은 AI_ROLES.md, 현재 파일 구조와 기능 배치는 CODE_STRUCTURE.md를 참고합니다.
1. MD(총괄) 운영 원칙
사용자가 MD에게 작업을 요청하면 MD가 최종 책임자가 됩니다. MD는 바로 구현을 시작하지 말고 먼저 요청의 목표, 수정 범위, 의존성, 완료 조건, 검증 방법을 분석합니다.
이 저장소의 복합 작업은 사용자가 매번 "MD 역할로"라고 쓰지 않아도 MD 방식으로 처리합니다. 단순 질문, 짧은 진단, 한 파일의 작은 수정은 병렬화하지 않고 MD 또는 단일 담당 AI가 처리합니다.
MD의 책임은 다음과 같습니다.
- 사용자 요청과 현재 저장소 상태를 확인하고 작업 범위를 명확히 정합니다.
- 작업을 독립 단위로 나누고 각 단위의 담당 AI, 담당 파일, 완료 조건, 검증 명령을 지정합니다.
- 서로 의존하지 않고 파일 쓰기 범위가 겹치지 않는 작업만 2~3개 AI에 병렬 위임합니다.
- 선행 결과가 필요한 작업, 같은 파일을 수정하는 작업, 공통 인터페이스나 데이터 구조를 바꾸는 작업은 순차 처리합니다.
- 각 AI의 결과를 직접 검토하고 연결 지점을 통합한 뒤 전체 변경을 검증합니다.
- 작은 작업은 억지로 분할하지 않고 MD 또는 단일 담당 AI가 끝까지 처리합니다.
- 사용자가 이미 만든 변경을 보존하며, 요청과 무관한 수정·삭제·정리·포맷 변경을 하지 않습니다.
2. 병렬화 판단 기준
다음 조건을 모두 만족할 때만 병렬 작업으로 배정합니다.
- 각 작업이 다른 작업의 미완성 결과를 필요로 하지 않습니다.
- 수정 가능한 파일 또는 디렉터리가 서로 겹치지 않습니다.
- 공유 상태, API 계약, DOM ID, 데이터베이스 스키마 같은 공통 계약을 동시에 변경하지 않습니다.
- 각 작업의 완료 조건과 개별 검증 방법을 독립적으로 설명할 수 있습니다.
- 결과 통합 순서와 최종 검증 방법이 정해져 있습니다.
아래 작업은 병렬 처리하지 않습니다.
- 둘 이상의 AI가
assets/js/app.js를 수정하는 작업 - 한 AI가
index.html의 ID나 마크업을 바꾸고 다른 AI가 그 결과를 사용하는 JS/CSS를 수정하는 작업 - 마이그레이션 또는 RLS 변경과 그 스키마를 전제로 하는 애플리케이션 코드 변경
- 공통 설정, 전역 상태, 공유 유틸리티, 자산 경로를 동시에 바꾸는 작업
- 선행 작업의 설계나 출력이 확정되어야 시작할 수 있는 후속 작업
병렬 작업 수는 기본 2~3개로 제한합니다. 독립 작업이 하나뿐이거나 변경 규모가 작으면 단일 에이전트로 처리합니다. 병렬화 자체를 목표로 삼지 않습니다.
3. 저장소별 파일 소유권
기본 담당은 AI_ROLES.md를 따르되, MD가 요청마다 더 좁은 쓰기 범위를 지정합니다.
- UI 구조:
index.html - 디자인:
assets/css/styles.css - 설비 도면 자산:
assets/floor-plans/,assets/models/ - 데이터베이스:
supabase/migrations/ - 애플리케이션 기능:
assets/js/app.js - 품질검사: 전체 파일을 읽을 수 있지만, 별도 배정이 없으면 수정하지 않습니다.
assets/js/app.js는 인증, 설비 도면, 정비이력, 할 일, 자료실, AI 점검/OCR, 검색 기능이 함께 있는 공유 파일입니다. 역할이 서로 달라도 이 파일을 수정한다면 같은 쓰기 범위로 간주하고 순차 처리합니다.
담당 AI는 배정받은 파일만 수정합니다. 범위 밖 수정이 필요해지면 임의로 확장하지 말고 MD에게 이유, 대상 파일, 예상 영향을 보고합니다. MD가 의존성과 충돌을 다시 판단한 뒤 범위를 재배정합니다.
4. 작업 배정 계약
MD는 각 AI에 아래 항목을 빠짐없이 전달합니다.
[작업명]
- 역할: AI_ROLES.md의 담당 역할
- 목표: 사용자에게 제공할 동작 또는 결과
- 담당 파일: 수정 가능한 파일/디렉터리의 정확한 목록
- 읽기 참고: 수정하지 않고 참고할 파일
- 금지 범위: 건드리지 않아야 할 기능과 파일
- 완료 조건: 관찰 가능하고 확인 가능한 조건
- 검증 명령: 담당 AI가 실행할 명령과 수동 확인 항목
- 보고 형식: 변경 파일, 핵심 변경, 검증 결과, 남은 위험
- 의존성: 선행 작업, 입력 계약, 통합 시 주의점담당 파일은 가능한 한 파일 단위로 배타적으로 지정합니다. 디렉터리를 맡길 때는 필요한 하위 경로만 적습니다. "관련 파일 전체"처럼 경계가 모호한 배정은 사용하지 않습니다.
5. 담당 AI 실행 규칙
각 담당 AI는 작업 시작 전에 담당 파일의 현재 내용과 git status --short를 확인합니다. 기존 변경이 있으면 이를 사용자 작업으로 간주하고 덮어쓰거나 되돌리지 않습니다.
구현 중에는 다음 규칙을 지킵니다.
- 요청된 기능에 필요한 최소 범위만 변경합니다.
- 기존 데이터 구조, Supabase 테이블명, DOM ID, 전역 함수, 자산 경로를 임의로 바꾸지 않습니다.
- 다른 AI의 담당 파일을 수정하지 않습니다.
- 자동 포맷이나 대량 치환으로 무관한 줄을 바꾸지 않습니다.
- 예상하지 못한 기존 변경이나 충돌을 발견하면 작업을 멈추지 말고 우선 영향 범위를 분석한 뒤 MD에 보고합니다. 안전하게 병합할 수 없는 경우에만 판단을 요청합니다.
- 구조가 바뀌는 작업에서는
CODE_STRUCTURE.md갱신 필요성을 MD에게 알립니다. 해당 파일이 배정되지 않았다면 직접 수정하지 않습니다.
6. 의존 작업과 공유 파일 처리
의존 작업은 MD가 아래 순서로 진행합니다.
- 공통 계약과 선행 작업을 먼저 완료하고 검증합니다.
- 확정된 함수명, DOM ID, 데이터 형식, 스키마 또는 자산 경로를 후속 AI에 전달합니다.
- 후속 작업을 순차 실행하거나, 새로 독립성이 확보된 작업만 병렬 실행합니다.
- 공유 파일에 대한 여러 변경은 MD가 우선순위를 정해 하나씩 적용하고 각 단계마다 회귀 여부를 확인합니다.
같은 파일의 서로 다른 줄을 수정한다는 이유만으로 병렬 배정하지 않습니다. 특히 assets/js/app.js는 전역 상태와 함수 호출 관계가 많으므로 단일 소유자가 한 시점에 하나의 작업만 수행합니다.
7. 통합과 최종 검증
MD는 담당 AI의 보고만 믿고 완료 처리하지 않습니다. 각 결과에 대해 다음을 직접 확인합니다.
- 실제 변경 파일이 배정 범위와 일치하는지 확인
- 사용자 기존 변경이 보존되었는지 확인
- 완료 조건이 충족되었는지 diff와 실행 결과로 확인
- HTML, CSS, JS, 자산 경로, Supabase 호출 사이의 연결 지점 확인
- 병렬 결과 간 중복 구현, 이름 충돌, 계약 불일치 확인
- 요청 범위 밖 변경과 불필요한 생성 파일 확인
기본 검증 명령은 다음과 같습니다. 작업 성격에 맞는 추가 검증이 있으면 MD가 배정 계약에 명시합니다.
git status --short
git diff --check
node --check assets\js\app.jsnode --check는 assets/js/app.js가 변경되었거나 JS 연결에 영향이 있을 때 실행합니다. 화면 변경은 관련 뷰포트에서 직접 확인하고, Supabase 변경은 마이그레이션·RLS·호출 코드의 일치 여부를 함께 점검합니다. 실행할 수 없는 검증은 생략 사실과 이유를 최종 보고에 남깁니다.
8. 결과 보고 형식
각 담당 AI는 MD에게 다음 형식으로 보고합니다.
- 변경 파일: 실제 수정한 파일 목록
- 핵심 변경: 구현한 내용 1~3개
- 완료 조건: 충족/미충족과 근거
- 검증 결과: 실행 명령과 성공/실패 결과
- 남은 위험: 미검증 항목, 의존 작업, 통합 주의점MD의 사용자 최종 보고에는 전체 변경 파일, 통합된 결과, 수행한 검증, 남은 위험 또는 미검증 항목을 포함합니다. 여러 AI의 작업 로그를 그대로 나열하지 말고 사용자 요청 기준으로 하나의 결과로 요약합니다.
9. 모델 선택
특정 모델명이나 추론 강도를 이 문서에서 강제하지 않습니다. MD는 작업 난도, 위험도, 비용을 고려하고 AI_ROLES.md의 역할별 권장값을 참고해 사용 가능한 모델을 선택합니다. 모델 선택보다 작업 경계, 파일 소유권, 완료 조건, 검증 책임을 우선합니다.
