agent-shell/agent-ops/rules/common/philosophy.md

Agent-Ops 철학

이 문서는 agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 읽는다. 일반 구현 작업에서는 읽지 않는다.

핵심

• agent-ops는 AI agent가 작업하기 위한 규칙이자 가이드다.
• 사람 문서처럼 장황하게 설명하지 않고, agent가 바로 실행할 수 있게 작성한다.
• 필요한 컨텍스트만 읽게 만든다. 모든 문서를 항상 읽게 만들지 않는다.
• 애매한 형식을 만들지 않는다. 경로, 상태, id, 입력, 출력은 판별 가능해야 한다.
• 문서는 짧고 단단해야 한다. 길어서 이해되는 문서보다 짧아서 헷갈리지 않는 문서가 낫다.

문서 작성

• 규칙과 스킬은 핵심만 쓴다.
• 같은 말을 여러 문서에 반복하지 않는다. 한 곳에 두고 링크한다.
• 설명보다 조건, 입력, 행동, 금지 사항을 우선한다.
• "적절히", "필요하면", "가능하면" 같은 말은 판별 기준이 없으면 쓰지 않는다.
• 예외가 있으면 예외 조건을 같이 쓴다.
• 긴 배경 설명은 README나 별도 참조 문서로 보내고, 실행 문서에는 실행 규칙만 남긴다.
• 룰 문서는 협업자가 직접 읽는 계약 문서이므로 한국어 한다체로 작성한다.
• README, GUIDE, roadmap 문서는 사람이 함께 검토하는 협업 문서이므로 한국어 설명체 또는 존댓말을 사용할 수 있다.
• 스킬 문서는 실행 안정성을 우선한다. 한국어 또는 영어를 사용할 수 있고, 이미 잘 동작하는 절차 계약은 언어 통일만을 위해 수정하지 않는다.
• path, filename, 상태값, id, regex, command, frontmatter key, runtime protocol token은 원문 ASCII 식별자를 유지한다.

라우팅

• 라우팅은 얕아야 한다.
• 1홉은 진입 파일에서 공통/프로젝트 규칙을 읽는 단계다.
• 2홉은 규칙에서 domain rule, roadmap rule, router를 따라가는 단계다.
• 3홉은 router에서 SKILL.md를 읽는 단계다.
• 4홉은 skill이 템플릿이나 참조 문서를 추가로 읽는 단계다.
• 4홉 이상이 필요하면 구조가 과하게 쪼개졌는지 먼저 의심한다. 필요하면 앞 문서에 바로 가는 링크를 추가한다.
• 깊은 링크 체인을 만들지 않고, 필요한 문서가 무엇인지 앞 문서에서 바로 보이게 한다.
• 일반 작업마다 router, 모든 skill, 전체 roadmap, archive를 읽게 만들지 않는다.

LLM과 런타임

• LLM은 의미 판단, 범위 판단, 요약, 설계 선택을 맡는다.
• 런타임은 파일명, 폴더명, 상태값, exit code처럼 결정적으로 판별 가능한 일을 맡는다.
• LLM 없이 처리할 수 있는 구간은 파일 규약으로 뺀다.
• 런타임 신호는 문서 본문보다 경로와 이름에 둔다.
• 런타임 신호를 만들 때는 agent가 본문을 읽지 않아도 판별 가능해야 한다.
• m-<milestone-slug> 같은 prefix는 런타임 판별을 위한 신호다.
• code-review는 PASS 산출물을 만들고 완료 이벤트 메타데이터를 남긴다.
• roadmap 반영 여부와 호출 타이밍은 런타임이 완료 이벤트를 보고 판단한다.

스킬 그룹 경계

• 스킬 그룹은 자기 라이프사이클 안에서만 강한 계약을 가진다.
• 스킬 그룹끼리는 다른 그룹의 내부 절차를 자동 호출하거나 전제하지 않는다.
• 그룹 간 연결은 사용자 명령, 런타임 이벤트, 또는 판별 가능한 파일 상태로만 한다.
• 구현 작업 그룹은 plan과 code-review의 PLAN/CODE_REVIEW 루프를 소유한다.
• 로드맵 그룹은 create-roadmap과 update-roadmap의 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신 흐름을 소유한다.
• Phase/Milestone 상태 전환, 구현 잠금 동기화, archive 이동, 완료 이벤트 반영처럼 결정적으로 판별 가능한 action은 Core/MCP 또는 런타임이 있으면 그쪽 책임으로 둔다.
• code-review가 남긴 PASS 완료 이벤트를 로드맵에 반영할지, 언제 반영할지는 런타임이 판단하고 Core/MCP action이 있으면 그쪽으로, 없으면 update-roadmap file-based fallback 흐름으로 넘긴다.
• cross-project 잠금이나 .agent-roadmap-sync 같은 workspace-level 상태는 로드맵 그룹, Core, 런타임의 공동 경계다. plan과 code-review에 의존성 동기화 규칙을 넣지 않는다.
• 새 스킬을 만들기 전에 기존 그룹의 자연스러운 입력, 상태 전환, 후처리 지점에 넣을 수 있는지 먼저 본다. 다만 다른 그룹 경계를 침범해야 하면 런타임 이벤트로 분리한다.

로드맵

• roadmap은 장기 기억이고, agent-task는 실행 상태다.
• current는 현재 작업 하나가 아니라 브랜치별 로컬 활성 Phase/Milestone 후보 창이다.
• Phase와 Milestone은 큰 방향과 기능 단위를 담는다.
• 구현 계획은 agent-task의 PLAN/CODE_REVIEW 루프에 둔다.
• 완료 후보는 바로 archive하지 말고 [검토중]으로 둔다.
• archive는 일반 작업에서 읽지 않는다. 과거 근거가 필요할 때만 링크를 따라 읽는다.

스킬

• skill은 절차 문서다.
• skill 하나에 책임 하나만 둔다.
• skill이 다른 skill을 자동으로 깊게 호출하는 구조를 만들지 않는다.
• skill 본문은 실행에 필요한 규칙만 둔다.
• 템플릿은 출력 형식이 흔들릴 때만 둔다.
• 스킬 업데이트 시 router, rules, template, 출력 형식이 같은 계약을 말하는지 같이 확인한다.
• plan과 code-review처럼 짝 계약을 양쪽에서 반복해 강제하는 구조는 의도된 중복으로 본다. 동작 중인 짝 계약은 일관성 정리만을 위해 합치지 않는다.

좋은 구조

• 진입 파일은 최소 규칙만 둔다.
• common rules는 공통 시작점만 둔다.
• project rules는 프로젝트 특화 판단만 둔다.
• domain rules는 특정 코드 영역 규칙만 둔다.
• skills는 반복 작업 절차만 둔다.
• roadmap은 장기 목표와 기능 단위만 둔다.
• agent-task는 실행 중인 작업 상태와 완료 산출물만 둔다.

경고 신호

• 같은 내용을 세 군데 이상 설명하고 있다.
• 어떤 문서를 읽어야 할지 문서 안에서 다시 찾아야 한다.
• 상태값이 사람은 이해하지만 런타임은 판별하기 어렵다.
• skill이 너무 많은 예외를 품고 있다.
• README가 내부 규칙 문서처럼 길어지고 있다.
• archive를 일반 작업 컨텍스트로 끌어오고 있다.
• LLM이 파일명만 봐도 될 일을 본문까지 읽어 판단하고 있다.