diff --git a/README.md b/README.md index 7d6cf5a..8856699 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ agent-ops/ bump-version.sh rules/ common/ + philosophy.md rules.md rules-roadmap.md _templates/ @@ -112,6 +113,12 @@ agent-ops/ `agent-ops/roadmap/archive/**`는 완료 또는 폐기되어 현재 작업 후보에서 제외한 과거 Milestone 기록입니다. 일반 작업과 로드맵 분석에서는 읽지 않고, 사용자가 과거 기록 확인이나 복원을 명시적으로 요청한 경우에만 참조합니다. +## 설계 철학 + +agent-ops는 AI-first 작업 프레임워크입니다. 규칙, 스킬, 로드맵은 에이전트가 필요한 것만 읽고 바로 행동할 수 있게 짧고 명확해야 합니다. + +세부 원칙은 [`agent-ops/rules/common/philosophy.md`](agent-ops/rules/common/philosophy.md)에서 관리합니다. 이 문서는 일반 작업 진입점이 아니라, agent-ops 구조나 책임 경계를 설계하고 수정할 때만 읽는 참조 문서입니다. + ## 공통 스킬 공통 스킬 라우팅은 `agent-ops/skills/common/router.md`가 단일 기준입니다. @@ -191,6 +198,7 @@ AI 에이전트가 이 저장소를 이어서 작업할 때는 아래 경로를 | 경로 | 역할 | |------|------| | `agent-ops/rules/common/rules.md` | 모든 에이전트 진입 파일의 원본 | +| `agent-ops/rules/common/philosophy.md` | agent-ops 구조와 문서 작성 원칙 | | `agent-ops/rules/common/rules-roadmap.md` | 로드맵 사용 프로젝트의 추가 공통 규칙 | | `agent-ops/skills/common/router.md` | 요청 키워드와 공통 스킬 매핑 | | `agent-ops/skills/common/*/SKILL.md` | 반복 작업별 실행 절차 | diff --git a/agent-ops/.version b/agent-ops/.version index 3baec79..cf6931b 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.51 +1.1.52 diff --git a/agent-ops/rules/common/philosophy.md b/agent-ops/rules/common/philosophy.md index 80a2f45..83e436e 100644 --- a/agent-ops/rules/common/philosophy.md +++ b/agent-ops/rules/common/philosophy.md @@ -1,25 +1,28 @@ # Agent-Ops 철학 -이 문서는 agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 고칠 때만 읽어. -일반 구현 작업에서는 읽지 마. +이 문서는 agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 읽는다. +일반 구현 작업에서는 읽지 않는다. ## 핵심 - agent-ops는 AI agent가 작업하기 위한 규칙이자 가이드다. -- 사람 문서처럼 장황하게 설명하지 말고, agent가 바로 실행할 수 있게 써. -- 필요한 컨텍스트만 읽게 만들어. 모든 문서를 항상 읽게 만들지 마. -- 애매한 형식을 만들지 마. 경로, 상태, id, 입력, 출력은 판별 가능해야 한다. +- 사람 문서처럼 장황하게 설명하지 않고, agent가 바로 실행할 수 있게 작성한다. +- 필요한 컨텍스트만 읽게 만든다. 모든 문서를 항상 읽게 만들지 않는다. +- 애매한 형식을 만들지 않는다. 경로, 상태, id, 입력, 출력은 판별 가능해야 한다. - 문서는 짧고 단단해야 한다. 길어서 이해되는 문서보다 짧아서 헷갈리지 않는 문서가 낫다. ## 문서 작성 -- 규칙과 스킬은 핵심만 써. -- 같은 말을 여러 문서에 반복하지 마. 한 곳에 두고 링크해. -- 설명보다 조건, 입력, 행동, 금지 사항을 우선해. -- "적절히", "필요하면", "가능하면" 같은 말은 판별 기준이 없으면 쓰지 마. -- 예외가 있으면 예외 조건을 같이 써. -- 긴 배경 설명은 README나 별도 참조 문서로 보내고, 실행 문서에는 실행 규칙만 남겨. -- 반말이어도 된다. 명확한 명령형이 더 좋다. +- 규칙과 스킬은 핵심만 쓴다. +- 같은 말을 여러 문서에 반복하지 않는다. 한 곳에 두고 링크한다. +- 설명보다 조건, 입력, 행동, 금지 사항을 우선한다. +- "적절히", "필요하면", "가능하면" 같은 말은 판별 기준이 없으면 쓰지 않는다. +- 예외가 있으면 예외 조건을 같이 쓴다. +- 긴 배경 설명은 README나 별도 참조 문서로 보내고, 실행 문서에는 실행 규칙만 남긴다. +- 룰 문서는 협업자가 직접 읽는 계약 문서이므로 한국어 `한다`체로 작성한다. +- README, GUIDE, roadmap 문서는 사람이 함께 검토하는 협업 문서이므로 한국어 설명체 또는 존댓말을 사용할 수 있다. +- 스킬 문서는 실행 안정성을 우선한다. 한국어 또는 영어를 사용할 수 있고, 이미 잘 동작하는 절차 계약은 언어 통일만을 위해 수정하지 않는다. +- path, filename, 상태값, id, regex, command, frontmatter key, runtime protocol token은 원문 ASCII 식별자를 유지한다. ## 라우팅 @@ -28,16 +31,16 @@ - 2홉은 규칙에서 domain rule, roadmap rule, router를 따라가는 단계다. - 3홉은 router에서 SKILL.md를 읽는 단계다. - 4홉은 skill이 템플릿이나 참조 문서를 추가로 읽는 단계다. -- 4홉 이상이 필요하면 구조가 과하게 쪼개졌는지 먼저 의심해. 필요하면 앞 문서에 바로 가는 링크를 추가해. -- 깊은 링크 체인을 만들지 말고, 필요한 문서가 무엇인지 앞 문서에서 바로 보이게 해. -- 일반 작업마다 router, 모든 skill, 전체 roadmap, archive를 읽게 만들지 마. +- 4홉 이상이 필요하면 구조가 과하게 쪼개졌는지 먼저 의심한다. 필요하면 앞 문서에 바로 가는 링크를 추가한다. +- 깊은 링크 체인을 만들지 않고, 필요한 문서가 무엇인지 앞 문서에서 바로 보이게 한다. +- 일반 작업마다 router, 모든 skill, 전체 roadmap, archive를 읽게 만들지 않는다. ## LLM과 런타임 - LLM은 의미 판단, 범위 판단, 요약, 설계 선택을 맡는다. - 런타임은 파일명, 폴더명, 상태값, exit code처럼 결정적으로 판별 가능한 일을 맡는다. -- LLM 없이 처리할 수 있는 구간은 파일 규약으로 빼. -- 런타임 신호는 문서 본문보다 경로와 이름에 둬. +- LLM 없이 처리할 수 있는 구간은 파일 규약으로 뺀다. +- 런타임 신호는 문서 본문보다 경로와 이름에 둔다. - 런타임 신호를 만들 때는 agent가 본문을 읽지 않아도 판별 가능해야 한다. - `m-` 같은 prefix는 런타임 판별을 위한 신호다. - code-review는 PASS 산출물을 만들고 완료 이벤트 메타데이터를 남긴다. @@ -55,11 +58,12 @@ ## 스킬 - skill은 절차 문서다. -- skill 하나에 책임 하나만 둬. -- skill이 다른 skill을 자동으로 깊게 호출하는 구조를 만들지 마. -- skill 본문은 실행에 필요한 규칙만 둬. -- 템플릿은 출력 형식이 흔들릴 때만 둬. -- 스킬 업데이트 시 router, rules, template, 출력 형식이 같은 계약을 말하는지 같이 확인해. +- skill 하나에 책임 하나만 둔다. +- skill이 다른 skill을 자동으로 깊게 호출하는 구조를 만들지 않는다. +- skill 본문은 실행에 필요한 규칙만 둔다. +- 템플릿은 출력 형식이 흔들릴 때만 둔다. +- 스킬 업데이트 시 router, rules, template, 출력 형식이 같은 계약을 말하는지 같이 확인한다. +- plan과 code-review처럼 짝 계약을 양쪽에서 반복해 강제하는 구조는 의도된 중복으로 본다. 동작 중인 짝 계약은 일관성 정리만을 위해 합치지 않는다. ## 좋은 구조