rlaguswls13.github.io

Imported from rlaguswls13/rlaguswls13.github.io (AGENTS.md). Install upstream with npx skills add rlaguswls13/rlaguswls13.github.io. Copyright stays with the author.

Blog Agent Harness

문서 역할과 우선순위

이 문서는 이 저장소에서 작업하는 agent의 진입점입니다. 작업을 시작할 때 이 파일을 먼저 읽고, 절차의 상세 내용은 project/skills/, 정책·결정·근거는 .wiki/의 canonical 문서에서 확인합니다.

Kapa RAG 문서 프로필

이 문서는 Markdown heading과 표를 기준으로 의미 단위가 나뉩니다. Kapa 또는 다른 RAG 소비자는 문서 역할과 우선순위, 작업 시작, skill 라우팅, 검증 게이트, 변경 안전성, 세션 종료 heading을 section title과 citation anchor로 사용해야 합니다. HTML 주석 metadata만으로 문서의 의미를 판단하지 않습니다.

문서 경로와 검색 우선순위의 기계 판독 기준은 .wiki/rag/source-registry.json입니다. .wiki/raw/(작업한 원본 증거)는 근거가 필요할 때 보조 검색하고, worklog와 session-memory.md는 기본 검색에서 제외해 이력 질의에만 사용합니다.

이 문서에 대한 자주 묻는 질문

Q: 작업을 시작할 때 가장 먼저 읽을 문서는 무엇인가?

A: AGENTS.md를 먼저 읽고, docs/README.md와 변경 유형에 맞는 project/skills/ 및 .wiki/ 문서를 이어서 확인합니다.

Q: 상세 절차와 장기 정책은 어디에 있는가?

A: 반복 절차와 입력·출력·검증 계약은 project/skills/, 정책·결정·검증 근거·위험은 .wiki/, lifecycle 자동화는 project/hooks/가 소유합니다. 이 파일은 entrypoint이며 상세 규칙의 복사본이 아닙니다.

Q: 답변에 어떤 출처를 인용해야 하는가?

A: 주장과 가장 가까운 heading의 repository path를 인용합니다. 이 파일의 공통 규칙은 AGENTS.md, 실행 절차는 해당 project/skills/<name>/SKILL.md, 정책·결정은 해당 .wiki/*.md, 자동화 동작은 해당 project/hooks/*를 출처로 사용합니다.

Q: 문서와 코드가 서로 다르면 무엇을 우선하는가?

A: 사용자의 현재 요청과 안전 제약, 이 파일의 공통 규칙, 관련 skill, 관련 wiki, 구현 코드와 테스트 순서로 판단합니다. 불일치가 남으면 추측하지 말고 검증 결과와 위험을 기록합니다.

Q: 이 문서가 답하지 않는 질문에는 어떻게 해야 하는가?

A: 문서에 근거가 없으면 사실을 만들어내지 말고 확인할 수 없음이라고 명시합니다. 관련 canonical source나 실제 검증 결과를 찾은 뒤 답변하고, source가 없으면 문서화 gap으로 기록합니다.

우선순위는 다음과 같습니다.

1. 사용자의 현재 요청과 안전 제약
2. 이 AGENTS.md의 저장소 공통 규칙
3. 작업 유형에 맞는 installed skill과 project/skills/ task skill
4. 관련 .wiki/ 정책·결정·검증 근거
5. 구현 코드와 기존 테스트의 실제 동작

docs/README.md는 project/skills/, project/hooks/, .wiki/의 관계를 설명하는 문서 surface controller입니다. 이 파일에 pipeline의 세부 절차를 복사하지 말고 해당 canonical 문서로 이동합니다.

검색용 주제와 동의어

이 문서가 다루는 주제는 다음 검색어로도 찾을 수 있습니다: agent harness, agent workflow, skill routing, quality gate, content validation, session memory, canonical wiki, RAG metadata, Kapa source group, safe change.

작업 시작: 컨텍스트와 영향 범위

실행 순서·영향 범위 조사·failing-first 규칙의 canonical 정의는 project-rag로 이전됐습니다 → .wiki/agent-harness-rules.md의 Execution order. 이 저장소에서만 유효한 진입 절차는 다음과 같습니다.

1. 이 파일, docs/README.md, 관련 .wiki/ 문서를 읽습니다.
2. .agent/session-handoff.md가 있으면 읽고, 현재 작업을 그 파일의 Current status와 Remaining tasks에 반영합니다.
3. 이후 단계(소비자·managed path·hook·외부 연동 조사 → skill 호출 → 동작 변경 시 failing-first 증거 → 최소 변경 → 범위에 맞는 검증)는 .wiki/agent-harness-rules.md를 따릅니다. 순수 문서·주석 변경에는 문장 검색 테스트를 만들지 않습니다.

공통 세션 handoff 계약

에이전트 종류와 실행 도구에 관계없이 작업 중간 상태는 .agent/session-handoff.md에 기록합니다. 이 파일은 글로벌 skill이 아니라 저장소 루트의 공통 baton이므로 Claude Code, Antigravity, Codex 등 다음 에이전트가 같은 형식으로 이어받을 수 있습니다.

• 작업을 시작하면 status: active로 바꾸고 updated_at, 현재 진행 상황, 변경된 기능, 남은 태스크를 기록합니다.
• 막힌 경우 status: blocked로 바꾸고 필요한 사용자 결정이나 외부 조건을 명시합니다.
• 세션을 넘길 수 있는 상태면 status: ready로 바꾸고 다음 에이전트가 먼저 할 일을 적습니다.
• 실행한 검증, 기존 실패, 위험, 결정 이유를 함께 기록합니다. 비밀·token·PII·긴 로그는 기록하지 않습니다.
• 기록은 append/update 방식으로 유지하고, handoff 파일을 삭제하거나 비워서 인수인계 정보를 잃지 않습니다.

세션 종료 시 마지막 baton을 받은 에이전트는 .agent/session-handoff.md의 존재와 status를 확인합니다. 파일이 존재하고 status가 active, blocked, ready이면 기록을 바탕으로 다음 두 작업을 요청합니다.

1. 최종 Wiki에 결정·검증·위험·남은 태스크를 반영합니다.
2. 변경 diff와 검증 증거를 대상으로 PR review를 요청합니다.

node project/hooks/session-end.mjs는 이 확인 결과를 handoff 객체로 반환합니다. requestFinalWiki 또는 requestPrReview가 true이면 요청을 생략하지 말고 후속 작업으로 남깁니다.

단계형 skill 호출

반복해서 handoff 절차를 프롬프트에 적지 않도록 project/skills/session-handoff-workflow를 옵션과 함께 호출합니다.

$session-handoff-workflow start "작업 내용"
$session-handoff-workflow checkpoint
$session-handoff-workflow continue
$session-handoff-workflow finish

옵션이 없으면 현재 handoff 상태에 따라 start, continue, finish를 자동 선택합니다.

Canonical agent surfaces

surface별 책임 표(무엇을 어디에 두는가)의 canonical 정의는 project-rag로 이전됐습니다 → .wiki/index.md의 Ownership 절. 요약하면 재현 가능한 절차는 project/skills/, host lifecycle 자동화는 project/hooks/, 정책·결정·검증 증거·위험·durable memory는 .wiki/, legacy docs 매핑은 docs/README.md가 소유합니다. 관련 정보가 여러 곳에 있으면 실행 절차는 skill, 정책·결정은 wiki, 자동화 동작은 hook을 source of truth로 삼고, 중복 설명을 만들지 말고 canonical 링크를 남깁니다.

.wiki/는 이 저장소 디렉터리 안에 존재하지 않는다. .wiki/xxx로 표기하는 모든 경로는 물리적으로 D:\obsidian-storage\project-rag\blog\xxx(환경변수 $PROJECT_RAG_PATH 설정 시 $PROJECT_RAG_PATH\blog\xxx)를 가리킨다 — 그 blog\ 폴더 자체가 .wiki 루트이며, 그 안에 .wiki라는 이름의 하위 폴더가 한 번 더 있는 게 아니다(.wiki/index.md → blog\index.md, .wiki/rag/source-registry.json → blog\rag\source-registry.json). 그쪽 git으로만 버전 관리되고 이 저장소의 원격에는 절대 올라가지 않는다. npm run wiki:index(scripts/wiki/build-rag-index.mjs의 stripWikiPrefix())와 project/hooks/session-end.mjs가 이 매핑을 자동으로 처리해 읽고 쓴다.

Central RAG vault (범용 룰·스킬 전용)

저장소 루트의 Markdown은 agent 진입점 AGENTS.md, host adapter CLAUDE.md, 제품 안내 README.md만 유지합니다. 새 장기 정책·설계 Markdown을 저장소에 추가하지 않고 외부 .wiki/로 이전하는 절차의 canonical 정의는 .wiki/agent-harness-rules.md의 Maintenance and security에 있습니다(이전 시 .wiki/docs-migration.json, .wiki/index.md, 관련 참조를 함께 갱신). 현재 디자인 계약은 .wiki/architecture/design-system.md가 소유하고 실제 구현은 src/app/globals.css에서 검증합니다.

이 프로젝트 고유의 정책·스키마·방향성은 위 표대로 이 프로젝트의 .wiki/(외부, 바로 위 설명 참고)가 canonical이다. 그와 별도로, 여러 프로젝트에 걸쳐 재사용하는 범용 코딩/보안/DB 규칙과 SOP는 같은 vault 루트(project-rag)의 다른 폴더를 참조한다.

• 경로: 환경변수 $PROJECT_RAG_PATH가 설정되어 있으면 그 값을 우선 사용하고, 없으면 D:\obsidian-storage\project-rag를 사용한다.
• 참조 내용: 01-global-rules/(범용 하드 제약), 02-global-skills/(범용 SOP)만 참조한다. 00-global-maps/가 있으면 색인 진입점으로 참고한다. blog/.wiki/(이 프로젝트 전용)는 이 절이 가리키는 대상이 아니다 — 바로 위 canonical surfaces 설명을 따른다.
• 이 vault는 이 저장소의 git 이력과 무관하다. 이 프로젝트의 canonical 정책·결정·스키마(.wiki/, project/skills/)를 01-global-rules/·02-global-skills/의 내용으로 대체하거나 덮어쓰지 않는다 — 충돌 시 이 프로젝트의 .wiki/가 우선한다.
• 경로가 존재하지 않거나 접근 불가능하면 조용히 건너뛰고 이 저장소 자체 규칙(AGENTS.md, .wiki/agent-harness-rules.md)만으로 계속 작업한다 — 중앙 볼트 부재를 이유로 작업을 막지 않는다.

작업 유형별 skill 라우팅

콘텐츠·pipeline 관련 작업은 먼저 project/skills/blog-content-pipeline, project/skills/release-gate, project/skills/session-memory-wiki를 확인합니다. 세부 도메인에 해당하면 thumbnail-contract, google-adsense-operations, google-search-console-operations, google-search-feeds도 확인합니다.

검증 게이트

검증 게이트 정책(기본 명령, build:local/validate:export 조건, 브라우저 viewport·light/dark, e2e/lighthouse)은 project-rag로 이전됐습니다 → .wiki/agent-harness-rules.md의 Validation gate · UI and quality boundaries. 실행 명령의 canonical 목록과 순서는 project/skills/release-gate가 소유하고, 화면 변경 검증은 blog-verification과 omo:visual-qa로 수행합니다. 실행 결과·기존 실패·잔여 위험은 .wiki/session-memory.md 또는 .wiki/raw/{topic}-{YYYYMMDD}.md에 기록합니다.

변경 안전성 계약

변경 안전성 규칙(Notion page_id/source_id 식별자, schema quarantine, staging→live 원자적 promote, secret 취급, 무관한 사용자 변경 금지, 생성 파일 취급)은 project-rag로 이전됐습니다 → .wiki/agent-harness-rules.md의 Pipeline boundaries · Maintenance and security.

세션 종료와 durable memory

세션 종료 시 host agent는 구조화된 session_end event를 node project/hooks/session-end.mjs에 전달합니다. event 스키마, redaction, commit 범위(project/skills·project/hooks만), 기억 품질 규칙은 project-rag로 이전됐습니다 → .wiki/agent-memory.md. .wiki/는 이 저장소 안에 없고 D:\obsidian-storage\project-rag\blog\가 유일한 원본이며 그 자체 git으로만 버전 관리되어 이 프로젝트의 원격 저장소에는 올라가지 않습니다.

규칙을 변경하기 전에는 .wiki/raw/에서 관련 topic의 최신 gate review·승인 기록과 .wiki/docs-migration.json의 surface 매핑을 확인합니다. 규칙 변경과 그 근거는 .wiki/raw/{topic}-{YYYYMMDD}.md에도 남깁니다.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.