localmind

Imported from shaul1991/localmind (AGENTS.md). Install upstream with npx skills add shaul1991/localmind. Copyright stays with the author.

AGENTS.md — localmind 작업 규약

이 저장소에서 작업하는 모든 AI 에이전트(Claude Code, Codex 등)가 따르는 규약이다. 작업 방법론(SDD 문서 체계·구현 착수·기록 연동)의 정본은 이 문서가 아니라 애드온이다 — 여기에는 localmind 고유의 것만 남긴다.

최상위 전제 — 왜 이 프로젝트가 존재하는가 (2026-07-23)

이 전제는 이 문서의 다른 모든 규칙·목표·게이트보다 최우선이다. 규칙 간 판단이 갈리면 이 전제로 되돌아와 해석한다.

• 이 프로젝트의 근본 목적은 AI에게 작업을 위임하기 위해, AI를 잘 사용하는 것이다.
• localmind는 그 목적을 위한 도구 중 하나로, 개인화 저장소(개인 second-brain) 겸 RAG 시스템으로 쓰려고 만든 것이다.
• 1차 사용자는 사람이 아니라 임무를 수행하는 AI다. 사람이 잘 쓰기 위한 도구이기 이전에, AI가 임무 수행을 잘 하기 위해 스스로 사용할 수 있는 도구여야 한다.
• 이는 아래 "오픈소스 대상 — 비개발자 포함"과 모순이 아니라 층위가 다르다: **AI에게 업무를 위임하는 주체는 모든 사람(비개발자 포함)**이고, localmind는 그 위임받은 AI가 일을 잘 할 수 있도록 만들어주는 **보조 도구(수단)**다. 사람 = 위임자·수혜자, AI = 도구의 1차 소비자.
• 따라서 모든 변경·규칙의 최종 기준은 "이것이 AI 위임·활용을 더 잘하게 하는가?"다. 아래 "범위 우선순위 — 코어 우선·메타 동결"을 포함한 하위 규칙들은 이 전제를 실현하는 수단이며, 이 전제와 충돌하는 방향으로 해석하지 않는다.

범위 우선순위 — 코어 우선·메타 동결 (2026-07-21)

이 저장소의 존재 목적은 다른 디바이스에서도 동일하게 쓰는 개인 second-brain(노트·색인· recall·MCP·동기화·백업)이다. 메타 계층(SDD 스킬·페르소나·rules·retro·critic 인프라·워크플로 템플릿)은 기능 동결 상태다:

• 메타 신규 확장은 금지한다. 허용 예외 셋뿐 — ① 결함 수정 ② governance-recalibration 리듬에 따른 파라미터 조정 ③ 코어 작업이 직접 요구하는 최소 변경.
• 새 작업 착수 시 "이 변경이 second-brain 사용자(디바이스 간 동일 사용)에게 무엇을 주는가?" 에 답한다 — 답이 없으면 메타 확장으로 간주하고 보류한다(작업 착수의 선행 게이트).
• 동결 해제는 사용자 명시 결정으로만 한다. 근거·실측: specs/202607210912-meta-freeze(메타 ~17k줄 vs 코어 ~4k줄, 2026.07 릴리스 8개 전부 메타 — 사용자 방향 결정 B).

작업 방법론 — 애드온이 정본 (2026-08-07)

방법론은 localmind-addons가 소유한다. 이 문서는 그것을 재서술하지 않는다 — 두 곳에 정본이 있으면 갱신되지 않는 쪽이 조용히 이긴다.

• 의식의 크기는 작업 크기에 비례한다 — 판정 기준의 정본은 sdd-5docs의 비례 원칙이다. 이 저장소가 더하는 것은 위 "범위 우선순위" 게이트 하나뿐이다.
• 위임은 완화가 아니다. TDD · 실패 테스트 선행 · 실행 관찰(도그푸드) · 자기검증 · base 확인 · 미충족의 정직한 보고 — 이 요구들은 위임처에서 동등하거나 더 강하게 유지된다. 축약을 근거로 게이트를 낮추지 않는다.
• 애드온이 없어도 막히지 않는다(비차단): 설치되지 않은 환경이면 일반 규율로 진행하고 그 사실을 보고에 명시한다. 포인터는 안내이지 하드 의존이 아니다.

원격 반영 — 브랜치·PR·CI

• main 직접 push는 금지 — feature 브랜치에 커밋·push하고 PR을 생성한다. 머지는 사람이 한다(2026-07-17 결정 D-6).
• push 이후 PR/CI 상태는 원격 GitHub가 SSoT다. PR 번호·CI 상태·run ID만 기록하기 위한 후속 commit은 만들지 않는다.
• CI 감시는 폴링 루프 대신 gh run watch <run-id> --exit-status(단일 블로킹 명령)를 쓰고, run 조회는 전체 sha만 사용한다(짧은 sha는 --commit 필터가 빈 결과 → 무한 대기 실측). 실패 시에만 즉시 알리고 green은 다음 보고에 부기한다. 끝난 감시 프로세스는 정리한다.
• CI 대기 중 유휴 금지 — CI가 전제인 단계(device-sync 등)만 뒤로 미루고 나머지는 병렬로 계속한다.

PR 리뷰 대응 — 자동 리뷰어 (2026-07-23)

PR에 자동 리뷰어(CodeRabbit·Codex 등)가 남긴 리뷰는 다음 절차로 대응한다(PR #48 실전에서 확립):

1. 지적별 검증 — 리뷰를 그대로 믿지 않는다. 각 지적을 현재 코드·문서 기준으로 실측 검증한 뒤 수용/스킵을 판정한다. 리뷰어도 오탐을 낸다(실례: 코드 기본값과 권장값을 혼동한 지적 — 근거 반박으로 철회·Learning 등록을 받아냄).
2. 수용은 최소 수정 + 같은 패턴 전수 검색. 지적된 지점만 고치지 말고 동일 패턴을 저장소 전체에서 검색해 함께 고친다(실례: 도구 열거 누락 2곳 지적 → 전수 검색으로 3곳 수정).
3. 스킵은 사유와 함께 반박한다. 스코프 밖·저장소 관례·의도된 설계(제품 원칙 근거 — 예: 비차단·복원력)를 명시한다. 근거가 서면 리뷰어가 지적을 철회하고 Learning으로 등록해 같은 오탐의 재발이 줄어든다.
4. 스레드별 개별 회신 — 요약 코멘트로 갈음하지 않는다. 각 인라인 스레드에 봇 멘션 (@coderabbitai 등)으로 회신해야 봇이 스레드 단위 해소·철회를 처리한다. 수용 회신에는 수정 커밋 SHA를 명시한다.
5. 리뷰 대응 수정도 새 candidate다. 커밋·push 후 CI를 다시 감시하고(위 "원격 반영"의 gh run watch, full SHA), 영향받은 검증(스위트·스모크)을 재실행한다.
6. 대응 후 새 리뷰가 또 달렸는지 확인하는 것까지가 한 사이클이다 — 회신에 리뷰어가 후속 질문을 남겼으면 닫는 답을 남긴다.

버전·릴리스 (CalVer)

이 절은 PR 생성 이후 단계(머지 → 버전 확정 확인 → tag → release)를 정한다. 버전·릴리스 규칙의 정본(SSoT)은 이 절 한 곳이다 — 다른 문서(CHANGELOG 등)는 이 절로의 참조·요약만 담는다.

버전 형식 (CalVer)

• 형식은 YYYY.MM.MICRO — YYYY.MM은 릴리스(PR 머지) 시점의 연·월(월은 2자리, 예: 2026.07), MICRO는 그 달의 릴리스 순번.
• 그 달의 첫 릴리스는 MICRO = 0, 이후 릴리스마다 +1.
• git tag는 v 접두 없이 버전 그대로 쓴다(예: 2026.07.0).
• 버전에 SemVer 의미(호환성 시그널)는 없다 — 버전은 "언제 릴리스했나"만 말한다. 변경의 성격·긴급도는 release notes(CHANGELOG 항목)가 말한다.

MICRO 산정 — 정본은 git tag 목록

• **먼저 git fetch --tags**로 원격 태그를 동기화한 뒤, git tag -l 'YYYY.MM.*' --sort=-v:refname(머지 시점의 연·월)의 최상단 수치 + 1 — 수치 비교다, 사전순이 아니다(2026.07.10 > 2026.07.9). 매칭 태그가 없으면 0.
• CHANGELOG 헤더와 어긋나면 태그가 이긴다 — 태그가 릴리스 행위의 결정적·기계적 증거다. 어긋남을 발견하면 CHANGELOG를 태그에 맞춰 정정한다.
• 같은 날 두 번째 릴리스든 긴급 hotfix든 구분 없이 동일 취급, MICRO +1. 채널·접미 표기(-hotfix 류)는 도입하지 않는다.

관심사 분리 — 내용은 작업 중, 버전은 머지 직전

• 변경 내용 서술(CHANGELOG 항목·PR 설명)은 작업 중 PR에 누적한다 — 이때 버전 숫자는 적지 않는다.
• 버전 숫자 확정(package.json bump + CHANGELOG 버전 헤더 기입)은 PR 머지 직전에 한다(PR의 chore(release) 커밋). git tag는 머지 후 절차 4단계에서 verified main에 만든다. 작업이 달을 넘겨도 버전은 실제 릴리스(머지) 시점의 연·월이다.
• 버전 확정 커밋은 main으로 머지될 PR의 마지막 chore(release) 커밋으로 넣는다 (package.json bump는 잠금 파일 동반). 여러 PR 묶음 릴리스면 마지막으로 머지되는 PR에 넣고, 묶음의 모든 PR이 이미 머지된 뒤라면 chore(release) 단독의 경량 릴리스 PR을 만들어 머지한다.
• 월 경계 재확정: 버전 확정(stamp) 후 머지가 지연돼 월이 바뀌면 머지 전에 재확정(re-stamp) 한다 — "버전 = 머지 시점의 연·월"이 stamp 시점보다 우선한다.

릴리스 절차 — 5단계 (각 단계의 확인 항목을 통과해야 다음 단계로)

1. 머지 준비 — 머지 방법은 위 "원격 반영"을 따른다(여기서 재서술하지 않는다). 확인: 릴리스할 변경이 열린 PR에 있고, 그 PR의 마지막 커밋이 버전 확정 커밋인가?
2. PR 머지 — 확인: gh pr view <번호>의 state가 MERGED인가? (아래 안전장치 (b)의 판정 기준을 함께 적용한다.)
3. 버전 확정 커밋 포함 확인 — 머지된 main에 버전 확정 커밋이 들어갔는지 본다. 확인: main의 package.json version과 CHANGELOG 최신 버전 헤더가 릴리스할 버전과 같은가?
4. 태그 — stale 로컬 HEAD 오태그 방지: git fetch origin main --tags 후 git tag <CalVer> origin/main(예: git tag 2026.07.1 origin/main — 3단계에서 검증한 정확한 main 커밋 SHA를 대상으로 써도 된다)으로 만들고 태그를 push한다. 확인: 원격에 태그가 올라갔는가(git ls-remote --tags origin)?
5. 릴리스 생성 — gh release create <CalVer> --verify-tag(원격에 해당 태그가 이미 존재해야 생성된다 — 태그가 없으면 gh가 자동 생성해버리는 것을 방지), CHANGELOG의 해당 버전 항목을 release notes로 넣는다. 확인: gh release view <CalVer>가 조회되는가?

안전장치 2건

• (a) gh 계정 확인: PR 머지 등 gh CLI 쓰기 작업 전에 gh auth status로 현재 활성 계정을 확인한다 — 활성 계정 표시일 뿐 repo 권한 검증은 아니다. 실제 쓰기 작업 (예: 머지)이 권한 오류를 내면 소유자 계정으로 전환한다(gh auth switch).
• (b) 머지 완료 판정: "머지 완료"는 gh pr view의 state가 MERGED이고(AND) main의 HEAD가 실제로 이동했을 때만 성립한다 — PR state + main HEAD 변화 둘 다 확인. main이 불변이면 미머지다 — tag·release를 진행하지 않는다(빈 태그 방지).

이 저장소의 규율

방법론 일반이 아니라 localmind에서만 성립하는 규칙들이다.

• 도그푸드 측정 위생 (2026-07-23 회고): MCP 도구를 직접 호출하는 도그푸드·프로브·스모크는 QUERY_LOG를 격리 경로(임시 폴더 등)로 설정하고 실행한다 — 공용 ~/.localmind/query-log.jsonl은 실사용 측정 전용이다(검색 품질 리포트·brief 통계 왜곡 방지, specs/202607231810).
• 결정 로그 태그: 결정 노트는 capture_note에 tags: ["decision"]을 지정한다 — 이 태그가 결정 노트의 판별 신호이며 brief의 구형식 폴백이 이 태그로 수집한다(specs/202607231759). 상세는 스펙 문서가 정본 — 노트는 "왜 그렇게 정했더라?"를 검색으로 소환하기 위한 요약이다.
• Open questions 해결 표기: 스펙의 OQ를 해소하면 항목에 **취소선(~~…~~)**을 남기거나 확정 절로 이관한다 — 제자리 재서술만 하면 미해결로 계속 잡힌다.
• git commit/push는 사용자가 명시적으로 요청했을 때만 수행한다(예외: goal-impl 흐름이 review 게이트를 통과해 완료로 닫히는 경우).
• UI 작업의 기본 원칙(설치 마법사 public/wizard 등): 직관성 · 상태 가시성(로딩/성공/ 실패의 명시적 표면화) · 디버깅/트래킹 용이성 — 미적 완성도와 충돌하면 가시성·추적성이 우선한다.

오픈소스 대상 — 비개발자 포함, 특정 개인 아님

localmind는 누구나 설치해 쓰는 오픈소스 개인 second-brain 도구다. 비개발자도 사용자다.

• goal.md의 Stakeholders 등에 특정 인물(예: 저장소 소유자)을 사용자로 특정하지 않는다 — "단일 사용자(설치한 개인 누구나 — 비개발자 포함)"로 쓴다.
• 예시·AC에 실제 개인 절대경로를 넣지 않는다 — 플레이스홀더(/home/<user>/...)를 쓴다.
• 에러 메시지·MCP 도구 응답은 비개발자가 이해할 수 있는 평이한 한국어로 작성한다.