# 🤖 The Antigravity Agent Lifecycle SOP (Final Master)

이 문서는 `new_gene` 템플릿 환경에서 코딩을 수행하는 모든 AI 에이전트(Antigravity, Claude Code, Gemini CLI 등)가 **무조건 준수해야 하는 최우선 행동 강령(Single Source of Truth)** 입니다. 과거 `antig_web`의 위대한 유산(Devlog, 오답노트)과 8대 최첨단 기민성 오픈소스가 완전히 결합된 최종 보루입니다.

---

## 1. 지식 동기화 룰 (SSOT Knowledge Sync)
작업 착수 전, 무지성 코딩을 금지하며 **인간이 수정한 위키를 1순위로 흡수**합니다.

*   **[Read] 전사 규정 탐색:** `.knowledge/global_wiki/` (Wiki.js Clone) 를 탐색해 프로젝트 언어(TS, Python 등) 컨벤션과 UI 토큰을 습득하십시오.
*   **[Read] 기획/언어 바인딩:** `.knowledge/project_wiki/tech_stack.md` 가 존재할 경우 이를 최우선으로 읽고, 만약 아직 위키 연동 전이라 파일이 없다면 절대 멈추지 말고 `package.json`이나 `PROJECT.md` 등 로컬 환경을 분석하여 언어와 패키지 매니저를 유추하십시오.
*   **[Sync] Git 충돌 방어망:** 로컬의 위키 파일을 열어보거나 수정하기 전, **무조건 `.knowledge/project_wiki` 폴더 안에서 `git pull --rebase origin main`을 실행하여 원격(웹) 수정본을 먼저 흡수**하십시오. (충돌 시 인간의 코드 우선).
*   **[Setup] 무결점 캡슐화 준수:** 에이전트 구동용 `mcp.json`은 `.agent/config/mcp.json`에 숨겨져 있으며, 에이전트 전용 패키지는 `.agent/env/package.json`에 숨겨져 있습니다. 루트(Root)를 오염시키지 말고 반드시 숨겨진 경로를 참조하십시오.

## 2. 기민성 극대화 개발 루프 (Agile Micro-Loop)
과거의 무차별적 `grep`이나 불안정한 스크립트를 버리고, 제공된 최전방 오픈소스 도구를 100% 활용해 디버그합니다.

*   **[Context] 네비게이션:** 수십 개의 파일을 읽지 마십시오. `.agent/skills/mcp-core/`의 공식 `mcp-server-filesystem`을 호출하여 필요한 파일만 정확히 추출하십시오.
*   **[Execution] 마이크로 병렬 처리:** 방대하고 위험한 코어 로직 수정 시, `.agent/skills/superpowers/` 의 `git worktree`로 격리 환경을 구축한 후 `.agent/skills/mini-swe` 의 초경량 요원에게 단일 파일 수정을 위임해 메인 브랜치가 깨지는 것을 막으십시오.
*   **[Vision QA] 렌더링 검열 (가짜 완료 금지):** 과거의 룰을 계승합니다. 프론트엔드 작업 후 브라우저 눈으로 검증하지 않았으면 "구현 완료"라고 확언하지 마십시오. `.agent/skills/browser_use/` 봇을 백그라운드로 돌려 섀도 돔(Shadow DOM)까지 파고들어 시각적 깨짐이 없는지 직접 입증하십시오.

---

## 3. 과거 유산 계승: 무결성 방어 룰 (Legacy Guardrails)

*   **[Rule A] 3진 아웃 오답노트 (Failure Protocol):** 한 번 에러 난 코드를 똑같이 쳐서 2번 실패하면 즉시 손을 떼십시오. 해당 에러의 원인과 우회로를 `.knowledge/project_wiki/devlog/known-issues.md` 에 등재하고 다른 접근법을 시도해야 합니다.
*   **[Rule B] P-C 디버깅 (Producer-Consumer):** 버그가 난 파일 1개만 열어서 고치는 것은 불법입니다. 해당 데이터를 생성한 놈(Producer)과 지우는 놈(Consumer) 양쪽 파일을 동시에 열어서 교차 검증한 후 원인을 잡으십시오.
*   **[Rule C] 메모리 병목 차단 (DB Lock):** `.agent/services/claude-mem/` 의 SQLite 로컬 메모리 DB 동시 접근 지시를 받으면, Read-Lock을 우회하는 3회 재시도(Retry) 지연 알고리즘을 사용해 서로 죽는 현상을 방어하십시오.

---

## 4. 작업 종료 및 배포: Devlog + Vikunja + Wiki 일체화
작업(Task/Phase)이 끝나고 "마무리/끝" 지시를 받으면 아래 절차로 에이전트 활동을 종료합니다.

1.  **Devlog (일일 개발 일지) 작성:** 단순 코드 외에 '설계 결정(왜 A 대신 B를 택했나)', '미완료 사항', '트러블슈팅'이 있었다면, 반드시 **`.knowledge/project_wiki/devlog/YYYY-MM-DD.md`** 에 양방향 링크(`[[문서명]]`)를 써서 기록합니다 (기존 과거 Devlog 시스템 완벽 계승).
2.  **Wiki 자동 동기화:** 아키텍처나 API가 변경된 경우 `.knowledge/project_wiki/` 내부 문서를 최신화한 뒤, 반드시 터미널에서 `node .agent/scripts/sync_wiki.js` 스크립트를 실행하여 Gitea Wiki 원격 저장소에 Push 하십시오 (토큰 노출 방지를 위해 날것의 curl이나 git push 금지).
3.  **Vikunja 하이라키 동기화 (PROJECT 모드 한정):** `.env.agent` 의 `AGENT_OPERATING_MODE`가 `PROJECT`일 경우에 한하여, 로컬의 Get-Shit-Done(GSD) `.planning/` 단계에서 한 에픽(Phase)이 완전히 끝났을 때 터미널에서 `node .agent/scripts/sync_vikunja.js "작업명/ID" "완료 사유/커밋해시"` 스크립트를 실행해 Vikunja 웹 대시보드에 1회 매핑 및 `Done` 처리를 수행하십시오. (TEST 모드일 경우 이 동기화를 강제로 스킵합니다).