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

Agent-Ops 철학

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

핵심

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

문서 작성

• 규칙과 스킬은 핵심만 써.
• 같은 말을 여러 문서에 반복하지 마. 한 곳에 두고 링크해.
• 설명보다 조건, 입력, 행동, 금지 사항을 우선해.
• "적절히", "필요하면", "가능하면" 같은 말은 판별 기준이 없으면 쓰지 마.
• 예외가 있으면 예외 조건을 같이 써.
• 긴 배경 설명은 README나 별도 참조 문서로 보내고, 실행 문서에는 실행 규칙만 남겨.
• 반말이어도 된다. 명확한 명령형이 더 좋다.

라우팅

• 라우팅은 얕아야 한다.
• 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 반영 여부와 호출 타이밍은 런타임이 완료 이벤트를 보고 판단한다.

로드맵

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

스킬

• skill은 절차 문서다.
• skill 하나에 책임 하나만 둬.
• skill이 다른 skill을 자동으로 깊게 호출하는 구조를 만들지 마.
• skill 본문은 실행에 필요한 규칙만 둬.
• 템플릿은 출력 형식이 흔들릴 때만 둬.
• 스킬 업데이트 시 router, rules, template, 출력 형식이 같은 계약을 말하는지 같이 확인해.

좋은 구조

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

경고 신호

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