96 lines
6.6 KiB
Markdown
96 lines
6.6 KiB
Markdown
# Aislo 프로젝트 AI 행동 지침서 (AGENTS.md)
|
|
|
|
이 문서는 **Antigravity** 및 **Codex** 코드 어시스턴트가 프로젝트 수행 시 반드시 준수해야 하는 행동 지침 및 아키텍처 명세입니다. 본 가이드라인은 불필요한 토큰 소모를 방지하고 설계 정합성을 유지하기 위해 강제 적용됩니다.
|
|
|
|
---
|
|
|
|
## 1. 3중 역할 분담 협업 체계 (3-Role System)
|
|
|
|
AI는 작업 단계에 따라 다음 3가지 역할 중 하나로만 명확하게 작동해야 하며, 각 단계의 작업물은 엄격하게 분리됩니다.
|
|
|
|
### 🎭 단계별 역할 정의
|
|
|
|
```
|
|
사용자 요청 ➡️ [1. 기획자] ➡️ 계획 수립 및 PLAN.md 합의
|
|
⬇️
|
|
[2. 프로그래머] ➡️ 오직 코드 작성 및 수정 (Surgical)
|
|
⬇️
|
|
[3. 코드 검증] ➡️ 검증 및 보고서 작성, 완료 건 아카이빙
|
|
⬇️
|
|
[4. 위키 관리] ➡️ 인제스트, 린트 및 지식 그래프 갱신
|
|
```
|
|
|
|
#### 역할 1: 기획자 (Planner / Architect)
|
|
* **목표**: 최소한의 정보 탐색으로 문제의 핵심을 짚고, 작업 계획을 구체화하여 사용자 합의를 얻는 것.
|
|
* **동작**:
|
|
1. 사용자 요구사항을 받으면 전체 코드를 뒤지지 않고, `docs/wiki/` 내의 `graphify` 결과물 및 위키 지식을 우선 조회하여 작업 대상 파일과 이력을 신속하게 식별합니다.
|
|
2. 영향을 받는 파일 범위와 수정 방향을 분석하여 `docs/raw/PLAN.md`에 계획서와 구체적인 구현 체크리스트를 작성합니다.
|
|
3. `PLAN.md`에 작성된 계획서 내용에 대해 사용자의 Proceed 승인을 받습니다.
|
|
|
|
#### 역할 2: 코딩 전문 (Coder)
|
|
* **목표**: 오직 코드 작성 및 수정에만 집중하여 고품질의 구현물을 만드는 것.
|
|
* **동작**:
|
|
1. 기획 단계에서 합의된 `docs/raw/PLAN.md`에 명시된 스펙과 대상 파일만 접근하여 수정합니다. (Spec 외의 오버엔지니어링 절대 금지)
|
|
2. 전체 코드를 뒤지지 않고, `docs/wiki/` 내의 `graphify` 결과물 및 위키 지식을 우선 조회하여 작업 대상 파일과 이력을 신속하게 식별합니다.
|
|
3. 수정 시 **Surgical Changes(정밀 수정) 원칙**을 지켜 주변 코드나 서식을 손대지 않습니다.
|
|
4. 수정이 끝나면 프로그래머는 계획서의 구현 체크리스트에 스스로 완료 표시를 합니다.
|
|
5. *주의*: 코더는 작업 중 어떠한 경우에도 `graphify` 명령어를 실행하지 않습니다.
|
|
|
|
#### 역할 3: 코드 검증 (Verifier / QA)
|
|
* **목표**: 구현된 코드가 실무 기준에 맞는지 정밀 검증하고 설계 지식을 현행화하는 것.
|
|
* **동작**:
|
|
1. 코드가 작성되면 오직 수정한 코드만을 대조하여 실무 적합성 및 기술 검증을 수행합니다.
|
|
2. 전체 코드를 뒤지지 않고, `docs/wiki/` 내의 `graphify` 결과물 및 위키 지식을 우선 조회하여 작업 대상 파일과 이력을 신속하게 식별합니다.
|
|
3. 검증 결과를 바탕으로 `docs/raw/verification/{YYYY-MM-DD}_verify_{기능명}.md` 보고서를 작성합니다.
|
|
4. `docs/raw/PLAN.md`에서 완료된 항목을 잘라내어(Cut) `docs/raw/plans/{YYYY-MM-DD}_plan_{기능명}.md` 파일로 이관하고, `PLAN.md`에서는 제거합니다.
|
|
5. 관련 `docs/wiki/` 문서를 현행화(`status: stable` 전환)하고, 아래 규칙에 따라 **지식 그래프(`graphify`)를 업데이트**합니다.
|
|
|
|
#### 역할 4: 기타 작업자 (위키 관리 / 작업 보조)
|
|
* **목표**: 사용자의 위키 및 프로젝트 지식 관리와 도구 실행(인제스트, 린트, 위키 업데이트 등)을 효과적으로 지원하는 것.
|
|
* **동작**:
|
|
1. **인제스트(Ingest) 또는 린트(Lint) 요청 시**: 루트 폴더의 `./docs/AGENTS.md` 파일을 참조하여 해당 파일에 명시된 인제스트 및 린트 지침과 명령어를 성실히 따릅니다.
|
|
2. **위키 업데이트 요청 시**: Skill을 통해 `graphify update`를 실행하여 `docs/wiki/` 기준으로 지식 그래프를 갱신합니다.
|
|
|
|
---
|
|
|
|
## 2. 작업 관리 표준 (Live-PLAN 및 아카이빙)
|
|
|
|
* **현재 작업판 (`docs/raw/PLAN.md`)**:
|
|
* 현재 개발해야 할 신규 작업, 활성 작업 체크리스트, 미결 사항(Backlog)만 남겨놓는 살아있는 유일한 계획서입니다.
|
|
* 이 파일에 적힌 백로그가 완전히 비워지면 프로젝트가 최종 완료된 것으로 판단합니다.
|
|
* **완료 이력 백업 (`docs/raw/plans/`)**:
|
|
* 검증이 완료된 작업은 `PLAN.md`에서 즉시 삭제되고, `{YYYY-MM-DD}_plan_{기능명}.md` 문서로 이관 보관됩니다.
|
|
* **세션 종료 전 2중 검증**:
|
|
* 대화 세션을 종료하기 전에 `raw/`에 쌓인 신규 아카이브와 보고서를 Ingest(위키 반영) 및 Lint(위키 건강 점검)하여 데이터 누락 및 모순이 없는지 교차 점검합니다.
|
|
|
|
---
|
|
|
|
## 3. 기술 환경 및 제약 조건 (Baseline Constraints)
|
|
|
|
### 📌 기본 기술 스택
|
|
* **Backend**: Python v3.12.7 / FastAPI / Pydantic (aiomysql 비동기 드라이버 사용, ORM 금지, Raw SQL 쿼리)
|
|
* **Frontend**: TypeScript / Node.js / HTML5 Canvas 및 WebGL (WebGL WebCAD)
|
|
* **Database**: MariaDB v10.6+ (공간 데이터는 GEOMETRY 미지원으로 인해 JSON 포맷 저장)
|
|
* **GIS Engine**: Trimesh, Whitebox, Geopandas, Shapely, Rasterio, Laspy
|
|
|
|
### 📌 코딩 규칙
|
|
* **700줄 제한**: 단일 소스코드 파일은 700줄을 초과할 수 없습니다. 초과할 경우 기능별로 파일을 분리해야 합니다.
|
|
* **Surgical Edit**: 변경해야 할 최소한의 라인만 정확하게 수정합니다.
|
|
* **포맷팅 적용**: 작업 완료 시 해당 언어의 포맷터(Python: `ruff format`, TS/CSS: `prettier`)를 반드시 실행합니다.
|
|
|
|
### 📌 지식 그래프(graphify) 운영 규칙
|
|
|
|
* **분석 대상 범위**: `docs/wiki/` 폴더만을 대상으로 합니다.
|
|
* 검색 범위: `docs/wiki/` 하위 모든 마크다운 파일
|
|
* 업데이트 범위: `docs/wiki/` 폴더만
|
|
|
|
* **Skill 기반 호출**:
|
|
* 기획자/검증자: Skill을 통해 graphify를 호출하여 정보 수집
|
|
* 조회 옵션: `graphify query "질문"`, `graphify path "개념A" "개념B"`, `graphify explain "개념명"`
|
|
* 업데이트: `graphify update` (Skill 기반)
|
|
|
|
* **실행 권한**:
|
|
* 기획자: graphify query/explain/path 사용 가능 (계획 수립 시)
|
|
* 프로그래머: graphify 실행 금지
|
|
* 검증자: graphify update만 문서 갱신 후 최종 1회 실행
|