From a9af8a68b3069a86ec1603898c4aed6e23d77e29 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 25 May 2026 13:10:51 +0900 Subject: [PATCH] sync: agent-ops from agentic-framework v1.1.53 --- agent-ops/.version | 2 +- agent-ops/rules/common/philosophy.md | 48 +++++++++++++++------------- 2 files changed, 27 insertions(+), 23 deletions(-) diff --git a/agent-ops/.version b/agent-ops/.version index 3baec79..36a0393 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.51 +1.1.53 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처럼 짝 계약을 양쪽에서 반복해 강제하는 구조는 의도된 중복으로 본다. 동작 중인 짝 계약은 일관성 정리만을 위해 합치지 않는다. ## 좋은 구조