Update project files

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` | 반복 작업별 실행 절차 |

agent-ops/.version

@@ -1 +1 @@
-1.1.51
+1.1.52

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-<milestone-slug>` 같은 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처럼 짝 계약을 양쪽에서 반복해 강제하는 구조는 의도된 중복으로 본다. 동작 중인 짝 계약은 일관성 정리만을 위해 합치지 않는다.
 
 ## 좋은 구조