eomsangdon/Aislo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35edf528f6b7d44c4d7db69da44cbf6f6a79bc0b
Aislo/docs/AGENTS.md
T
eomsangdon f533082537 260715_0
2026-07-15 18:33:33 +09:00

9.9 KiB
Raw Blame History

나는 누구인가

  • 이름:
  • 하는 일: 임도설계 실무자. 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 변환
  1. 페이지 하나(파일 하나)는 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).
Reference in New Issue View Git Blame Copy Permalink