From e0c9da9fa57944fe2f611e41c060b8111ba2462f Mon Sep 17 00:00:00 2001 From: Variet Date: Sun, 8 Mar 2026 08:29:59 +0900 Subject: [PATCH] fix: cross-file consistency (GUIDE.md, AGENT.md, README.md) --- .agents/AGENT.md | 3 ++- .agents/GUIDE.md | 48 +++++++++++++++++++++++++++++++++++------------- README.md | 15 ++++++++------- 3 files changed, 45 insertions(+), 21 deletions(-) diff --git a/.agents/AGENT.md b/.agents/AGENT.md index 6775bd3..148d8b9 100644 --- a/.agents/AGENT.md +++ b/.agents/AGENT.md @@ -44,7 +44,8 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. 1. `.agents/AGENT.md` (this file — behavior rules) 2. `.agents/references/known-issues.md` (past failure patterns) 3. `.agents/references/` (project-specific knowledge) -4. `.agents/workflows/` (action procedures) +4. `.agents/workflows/services.md` (service credentials & protocols) +5. `.agents/workflows/` (action procedures) ## PowerShell Notes diff --git a/.agents/GUIDE.md b/.agents/GUIDE.md index 59f0e21..0ec56d6 100644 --- a/.agents/GUIDE.md +++ b/.agents/GUIDE.md @@ -23,17 +23,32 @@ AI 에이전트는 다음과 같은 문제를 자주 일으킵니다: ``` .agents/ -├── AGENT.md ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙) -├── references/ ← 📚 프로젝트 지식 베이스 -│ ├── architecture.md ← 아키텍처 설명 -│ ├── tech-stack.md ← 기술 스택 & 버전 -│ ├── conventions.md ← 코딩 컨벤션 -│ └── known-issues.md ← 🔴 과거 실패 기록 (핵심!) -└── workflows/ ← ⚙️ 행동 절차 - ├── start.md ← 세션 시작 - ├── end.md ← 세션 종료 + 학습 기록 - ├── pre-task.md ← 작업 전 필수 체크리스트 - └── debug.md ← 디버깅 전용 절차 +├── AGENT.md ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙) +├── GUIDE.md ← 📖 이 가이드 +├── references/ ← 📚 프로젝트 지식 베이스 +│ ├── architecture.md ← 아키텍처 설명 +│ ├── tech-stack.md ← 기술 스택 & 버전 +│ ├── conventions.md ← 코딩 컨벤션 +│ └── known-issues.md ← 🔴 과거 실패 기록 (핵심!) +└── workflows/ ← ⚙️ 행동 절차 + ├── start.md ← 세션 시작 (룰 로딩 + devlog 복구) + ├── end.md ← 세션 종료 (devlog + known-issues + Vikunja + Git) + ├── pre-task.md ← 작업 전 필수 체크리스트 + ├── debug.md ← 디버깅 전용 절차 + ├── services.md ← 서비스 연동 정보 + AI 작업 프로토콜 + ├── check-gitea.md ← Gitea 현황 조회 + ├── check-vikunja.md ← Vikunja 태스크 조회 + └── helpers/ + ├── vikunja_helper.py ← Vikunja API 안전 래퍼 + └── wiki_helper.py ← Gitea Wiki 래퍼 +``` + +**프로젝트 루트에 자동 생성되는 디렉토리:** +``` +docs/devlog/ ← 📓 세션별 작업 기록 +├── YYYY-MM-DD.md ← Index (매일 1줄씩 누적) +└── entries/ + └── YYYYMMDD-NNN.md ← Entry (설계 결정/미완료 시만) ``` --- @@ -73,10 +88,17 @@ AI 에이전트는 다음과 같은 문제를 자주 일으킵니다: 4. 수정 및 검증 5. 기록 (known-issues에 추가) +### 📓 Devlog — 세션별 작업 기록 (start.md / end.md에서 관리) + +known-issues가 **실패만** 기록한다면, devlog는 **전체 세션 이력**을 기록합니다: +- **Index** (`docs/devlog/YYYY-MM-DD.md`): 매 작업마다 1줄 (필수) +- **Entry** (`docs/devlog/entries/YYYYMMDD-NNN.md`): 설계 결정/미완료/삽질 시만 (선택) +- **start.md**에서 자동으로 오늘/어제 devlog를 읽어 맥락 복구 + ### ▶️ `start.md` / ⏹️ `end.md` — 세션 관리 -- **start**: 에이전트 룰 로딩 + Git 상태 + 맥락 복구 -- **end**: 학습 기록 + Git commit/push +- **start**: 에이전트 룰 로딩 + devlog 맥락 복구 + Git 상태 + Vikunja TODO +- **end**: known-issues 업데이트 + devlog 기록 + Vikunja 동기화 + Git commit/push --- diff --git a/README.md b/README.md index 56fbf9b..a27f130 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,15 @@ git clone https://git.variet.net/Variet/agent_guide.git cp -r agent_guide/.agents/ your-project/.agents/ -# 2. {{PLACEHOLDER}} 값들을 프로젝트에 맞게 교체 -# - services.md → API URL, Token, Project ID -# - helpers/vikunja_helper.py → API_BASE, TOKEN, PROJECT_ID -# - helpers/wiki_helper.py → GITEA_BASE_URL, TOKEN, OWNER, REPO -# - check-gitea.md → Token, URL -# - references/ → 프로젝트별 아키텍처, 기술스택, 컨벤션 +# 2. 프로젝트별 값 2개만 교체 +# - {{GITEA_REPO}} → services.md, check-gitea.md, wiki_helper.py +# - {{VIKUNJA_PROJECT_ID}} → services.md, vikunja_helper.py (PROJECT_ID) +# - references/ → 프로젝트별 아키텍처, 기술스택, 컨벤션 채우기 -# 3. AI 에이전트에게 "시작" 또는 "/start" 명령 +# 3. docs/devlog/ 디렉토리 생성 +mkdir -p docs/devlog/entries + +# 4. AI 에이전트에게 "시작" 또는 "/start" 명령 ``` ## 파일 구조