112 lines
9.9 KiB
Markdown
112 lines
9.9 KiB
Markdown
## 나는 누구인가
|
|
- 이름:
|
|
- 하는 일: 임도설계 실무자. Aislo(라이다 데이터 기반 임도 설계·견적 자동화 웹앱) 프로젝트의 기획·설계자.
|
|
- 핵심 가치: 코드를 직접 작성하거나 깊이 이해하지는 못하지만, 도메인 전문성을 바탕으로 결과물(화면, 산출물)을 보고 실무적으로 맞는지 검증할 수 있다. 이 검증력을 근거로 AI에게 방향성과 구체적 지시를 내린다.
|
|
|
|
## 나의 역할들
|
|
|
|
### 임도설계 실무자 (도메인 전문가)
|
|
- 하는 일: 임도 설계 실무 지식을 바탕으로 요구사항을 정의하고, AI가 만든 결과물이 실무 기준에 맞는지 검증한다.
|
|
- 주요 관심사: 결과물의 실무적 타당성, 설계 로직의 정확성.
|
|
|
|
### 프로젝트 기획·설계자
|
|
- 하는 일: AI 코드 어시스턴트에게 방향성과 지시를 제공하고, 계획서 작성과 검토를 주도한다.
|
|
- 주요 관심사: AI와의 소통 효율, 문서·컨텍스트 구조화, 반복되는 방향성 이탈 방지.
|
|
|
|
## 나의 비전과 목표
|
|
- 이루고자 하는 것: 라이다 데이터를 활용해 임도 설계를 자동화하는 웹앱(Aislo)을 완성한다. 동시에, 개발 과정에서 문서(백엔드/프론트엔드/DB/구조/계획서/검증보고서)가 비대해져 컨텍스트·토큰을 낭비하지 않도록, 페이지 단위로 구조화·연결된 위키 체계를 구축한다.
|
|
- 타겟 독자/고객:
|
|
- 1차: AI 코드 어시스턴트 자신 — 코드 작성 전후로 필요한 부분만 효율적으로 찾아 읽는 용도.
|
|
- 2차: 6개월~1년 후의 AI 세션 및 팀원 — 프로젝트 구조, 설계 이유, 사용된 함수·변수, DB 정보를 스스로 파악해 개선하거나 인수인계받는 용도. (본인이 직접 위키를 다시 찾아볼 일은 거의 없음)
|
|
|
|
## AI에게 기대하는 것
|
|
- 코드 작성 전후로 관련된 위키·계획서만 효율적으로 찾아 읽고, 문서 전체를 뒤지지 않기.
|
|
- 계획서 작성 → 코드 작업 → 계획서 체크리스트 점검 → 코드 검증 → 검증보고서 작성 → 계획서 업데이트의 흐름을 주기적으로 관리하기.
|
|
- 같은 실수나 배경 설명을 반복하지 않기 — 이전 결정사항과 컨텍스트를 유지하기.
|
|
- 함수·변수 단위, DB 컬럼 단위까지 추적 가능하도록 문서화하기.
|
|
|
|
## 작업 규칙
|
|
- 톤: 간결하고 명확하게. 불필요한 수식어 없이 핵심만
|
|
- 언어: 한국어 기본
|
|
- 결과물 형태: 계획서와 검증보고서는 각각 하나의 파일로 구성하여 지속 업데이트한다. 문서는 비대해지지 않도록 페이지 단위로 구조화하고, 하위에 관련 백엔드·프론트엔드·DB·API·의존성 정보를 연결한다.
|
|
|
|
---
|
|
|
|
## Wiki Schema (위키 운영 규칙)
|
|
|
|
> 이 규칙은 `docs/` 볼트에만 적용된다. 프로젝트 루트의 docs 폴더 상위의 `.agent/` 폴더(실제 코딩 라우팅용)와는 완전히 독립적이며, 서로 건드리지 않는다. 위키가 충분히 성숙하면 그때 `.agent`를 대체할지 판단한다.
|
|
|
|
### 레이어 구조
|
|
- **raw/** — 불변 원본. 계획서·검증보고서·행동지침 등을 유형별로 넣는다. AI는 이 폴더를 절대 수정하지 않는다.
|
|
- **wiki/** — AI가 raw를 읽고 편집·유지하는 산출물. 페이지(B01~B09) 기준 폴더 + 개념(concepts) 폴더로 구성.
|
|
- **output/** — 최종 결과물(보고서, 슬라이드 등).
|
|
|
|
### 위키 관리자(Librarian) 역할
|
|
AI는 이 볼트에서 "위키 관리자"로 행동한다. 단순 챗봇이 아니라, raw를 읽고 wiki를 지속적으로 편집·정리·연결하는 책임을 진다. wiki는 사용자가 아니라 AI가 쓰고 관리한다.
|
|
|
|
### 운영 방식
|
|
- **Ingest** (원본 반영): raw/에 새 파일이 들어오면 → 내용을 읽고 핵심을 파악 → 관련된 `wiki/pages/B0x_*/`와 `wiki/concepts/*.md`를 갱신 → `wiki/index.md` 갱신 → `wiki/log.md`에 기록.
|
|
- **Query** (질의 응답): 코드 작업 전후로 질문을 받으면 → `wiki/index.md`를 먼저 확인 → 관련 페이지만 열어서 답변 → raw/는 위키에 없는 정보가 필요할 때만 최후 수단으로 참조. 답변 중 새로 정리된 내용(비교, 분석 등)은 대화에 흘려보내지 말고 관련 wiki 페이지에 다시 파일링한다.
|
|
- **Lint** (건강 점검): 요청 시 위키 전체를 점검 — 페이지 간 모순, 오래된 내용(최근 raw로 갱신되지 않은 부분), 고아 페이지(연결 없음), 빠진 크로스링크를 찾아 보고한다.
|
|
|
|
### 위키 규칙
|
|
1. **raw/는 절대 수정 금지** (불변 원본)
|
|
2. wiki 페이지 생성·삭제 시 **index.md 필수 업데이트**
|
|
3. 모든 오퍼레이션마다 **log.md에 기록**
|
|
4. 내부 참조는 **위키링크(`[[페이지명]]`)** 형식 사용
|
|
5. 모든 wiki 페이지에 **YAML frontmatter** 작성. `status`는 반드시 아래 3개 값 중 하나만 사용:
|
|
- `draft` — 계획서만 반영됨, 아직 검증 안 됨
|
|
- `stable` — 검증보고서로 확인된 내용까지 반영됨
|
|
- `stale` — raw에 새 자료가 들어왔는데 아직 이 페이지에 반영 못함 (Lint 시 최우선 처리 대상)
|
|
그 외 `related_pages`, `last_updated`도 함께 기록한다. **`wiki/pages/B0x_이름/`, `wiki/pages/A0x_이름/` 하위 파일은 다음 규칙을 따른다:**
|
|
- **파일명 형식:** `{page_id}_{기능명}.md` (예: `A01_frontend.md`, `B05_backend.md`, `B03_db.md`)
|
|
- **frontmatter에 `page_id` 필드 필수:** `page_id: A01_Home` 또는 `page_id: B05_wf2_Route` — 폴더 밖에서 파일 하나만 봐도 어느 페이지 소속인지 식별 가능해야 한다.
|
|
- concepts 페이지에는 이 규칙을 적용하지 않는다(페이지 단위가 아니므로).
|
|
6. 모순 발견 시 **양쪽 소스 모두 인용**하고 어느 쪽이 최신인지 명시. **계획서와 검증보고서가 충돌하면 검증보고서를 채택한다** (검증보고서 = 실제 코드가 검증된 상태, 계획서 = 그 시점의 의도). 계획서 쪽 내용은 지우지 말고 "계획 당시 의도"로 표시해 남긴다.
|
|
7. 소스 요약은 사실만 기록, 해석·종합은 concepts 페이지에서
|
|
8. 질의 시 **index.md 먼저**, raw/는 마지막 수단
|
|
9. **새 페이지 생성보다 기존 페이지 업데이트를 우선**
|
|
10. index 항목은 한 줄, 120자 이내로 요약
|
|
11. **공유 자원은 1차 정의를 concepts에만 둔다.** 공유 자원이란 두 페이지 이상이 함께 쓰는 것 전부를 말한다 — DB 테이블·컬럼, 공통 함수(`common_util_*`), API 엔드포인트, Pydantic 요청/응답 스키마, 외부 라이브러리(의존성), workflow 상태 등. 페이지의 `db.md`/`backend.md`/`api.md`/`dependencies.md`에는 정의를 복사하지 않고, "이 페이지가 무슨 용도로 쓰는지" + `[[concepts/해당개념#항목명]]` 위키링크만 남긴다.
|
|
12. **concepts 페이지에는 사용처(역참조) 목록을 직접 적는다.** 예: `db_schema.md`의 "routes 테이블" 항목 아래에 `사용처: [[B05_wf2_Route]], [[B06_wf3_ProfileCross]]`. 새 페이지가 그 자원을 쓰게 되면 concepts 쪽 사용처 목록도 함께 갱신한다 (Obsidian 자동 백링크에만 의존하지 않음).
|
|
13. **함수·API·테이블 등 개별 항목은 표 형식으로만 기록한다** (서술문 금지). 최소 컬럼: `항목 | 위치(파일:줄번호) | 역할`. 코드 AI가 grep 없이 바로 해당 위치로 이동할 수 있어야 한다.
|
|
|
|
| 항목 | 위치 | 역할 |
|
|
|---|---|---|
|
|
| `generate_dem()` | `B04_wf1_Surface/B04_wf1_Surface_Engine.py:142` | 포인트클라우드 → DEM 변환 |
|
|
|
|
14. **페이지 하나(파일 하나)는 100줄을 넘지 않는다.** 넘으면 즉시 하위 주제별로 분할한다 (예: `concepts/db_schema.md` → `concepts/db_schema/routes.md`, `concepts/db_schema/input_files.md` ...). 분할 시 상위 페이지는 하위 페이지로 가는 링크 목록만 남기고, `index.md`도 함께 갱신한다.
|
|
|
|
### 폴더 구조
|
|
```
|
|
docs/
|
|
├── raw/ (불변 원본)
|
|
│ ├── plans/ 계획서
|
|
│ ├── verification/ 검증보고서
|
|
│ └── guidelines/ 행동지침
|
|
├── wiki/
|
|
│ ├── index.md 전체 카탈로그 (카테고리별 한 줄 목록)
|
|
│ ├── log.md 연대기 로그 (append-only)
|
|
│ ├── pages/ 페이지(B01~B09) 기준 — 프로젝트 구조의 B01~B09 폴더와 1:1 대응
|
|
│ │ └── B0x_이름/
|
|
│ │ ├── frontend.md
|
|
│ │ ├── backend.md
|
|
│ │ ├── db.md
|
|
│ │ ├── api.md
|
|
│ │ └── dependencies.md
|
|
│ └── concepts/ 페이지를 관통하는 공통 개념 (DB 스키마, 인증/RBAC, 저장 경로 규칙, 공통 유틸, API 공통, 의존성, 공통 스키마, workflow 상태 등)
|
|
└── output/ 최종 산출물
|
|
```
|
|
- 페이지 하위 파일은 raw 반영 시 **필요한 것만 생성**한다 (5개를 미리 다 만들지 않음).
|
|
- `wiki/pages/`의 카테고리는 프로젝트의 실제 B01~B09 폴더명과 항상 일치시킨다.
|
|
|
|
## graphify
|
|
|
|
This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
|
|
|
|
Rules:
|
|
- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
|
|
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
|
|
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
|
|
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
|