mustflow 1.15.97

package/templates/default/locales/ko/.mustflow/docs/agent-workflow.md

@@ -0,0 +1,506 @@
+---
+mustflow_doc: docs.agent-workflow
+locale: ko
+canonical: false
+revision: 25
+lifecycle: mustflow-owned
+authority: workflow-policy
+---
+
+# Agent Workflow
+
+이 문서는 에이전트가 이 저장소에서 어떤 순서로 문서를 읽고, 수정하며, 실행하고, 검증해야 하는지에 관한 공통 작업 정책을 설명합니다.
+
+`AGENTS.md`는 반드시 준수해야 하는 간단한 첫 진입 규칙이며, 이 문서는 그 규칙을 실제 작업 흐름으로 상세히 풀어 설명합니다. 실제 실행 명령은 이 문서가 아니라 `.mustflow/config/commands.toml`에 정의되어 있습니다.
+
+## 문서의 역할
+
+이 문서는 다음 내용을 담당합니다.
+
+- 작업 시작 전 확인해야 할 문서 흐름
+- 상위 작업 공간과 하위 저장소 규칙 간 우선순위
+- 반복 입력의 안정성 유지 정책
+- 장기 작업에서 하네스가 따라야 할 작업 계약 경계
+- 계층형 압축 기억 정책과 요약 기억의 권위 한계
+- 명령 의도 상태별 실행 정책
+- 장기 실행 프로세스 방지 정책
+- 완료 주장 검토 및 검증 약화 방지 정책
+- 저장소별 선호값 해석 정책
+- 수정, 검증, 실패 대응, 보안의 공통 기준
+- 스킬 문서와 설정 파일 갱신 기준
+
+이 문서는 실제 테스트, 빌드, 규칙 검사 명령을 직접 나열하지 않습니다. 명령은 저장소마다 다르므로 `.mustflow/config/commands.toml`의 명령 의도 계약을 기준으로 판단합니다.
+
+## 기준 문서 역할
+
+mustflow 문서는 각각 명확한 역할을 갖습니다. 단순히 편하게 고치기 좋다는 이유로 낮은 권위의 파일에 더 강한 규칙을 옮기지 않습니다.
+
+| 문서 | 역할 | 권위 | 생명주기 |
+| --- | --- | --- | --- |
+| `AGENTS.md` | 첫 진입점이며 반드시 지켜야 하는 간단한 저장소 규칙입니다. | 사용자 직접 지시와 호스트 안전 규칙 아래에서 가장 높은 저장소 내부 지침입니다. | 사용자가 수정 가능하며, 설치 방식에 따라 mustflow 관리 파일 또는 관리 블록입니다. |
+| `.mustflow/docs/agent-workflow.md` | 읽기, 수정, 검증, 보고, 실패 대응에 관한 공통 작업 정책입니다. | `AGENTS.md`를 상세히 풀어 설명하지만 실행 명령은 정의하지 않습니다. | mustflow가 소유하는 Markdown 문서입니다. |
+| `.mustflow/config/mustflow.toml` | 문서 루트, 보호 경로, 예산, 승인, 보존, 새로고침 등 작업 설정입니다. | mustflow 동작을 정의하는 기계 판독 설정입니다. | mustflow가 소유하는 TOML 파일입니다. |
+| `.mustflow/config/commands.toml` | 명령 의도 계약입니다. | 설정된 의도를 통해 프로젝트 명령 실행을 허용하는 유일한 기준입니다. | 명령 계약 변경 시 수정하는 저장소별 TOML 파일입니다. |
+| `.mustflow/config/preferences.toml` | 스타일, 언어, Git 제안, 테스트 작성 성향, 검증 선택, 버전 영향의 기본값입니다. | 권한이 아닌 낮은 권위의 선호값입니다. | 저장소별로 사용자가 조정할 수 있는 TOML 파일입니다. |
+| `.mustflow/context/INDEX.md` | 작업별 문맥 파일을 선택하는 라우터입니다. | 선택형 문맥만 고르며 정책 설명서는 아닙니다. | mustflow가 소유하는 Markdown 문서입니다. |
+| `.mustflow/context/PROJECT.md` | 신중한 프로젝트 사실, 미지점, 도메인 관습을 기록합니다. | 사용자 지시, 코드, 테스트, 명령 계약, 설정된 정책보다 낮은 권위의 참고 자료입니다. | 사용자가 수정 가능한 문맥 문서입니다. |
+| `.mustflow/skills/INDEX.md` | 작업에 맞는 절차 문서를 선택하는 라우터입니다. | 선택 계약만 담당하며 자세한 절차는 `SKILL.md`에 둡니다. | mustflow가 소유하는 Markdown 문서입니다. |
+| `.mustflow/skills/<name>/SKILL.md` | 반복 작업의 입력, 허용 범위, 검사, 보고 형식을 담은 절차입니다. | 절차 안내일 뿐이며 명령 실행 권한을 부여하거나 다른 규칙을 덮어쓰지 않습니다. | mustflow가 소유하는 Markdown 문서이며, 필요 시 언어별로 설치됩니다. |
+| `REPO_MAP.md` | 넓은 탐색과 하위 저장소 진입점을 위한 생성 앵커 지도입니다. | 현재 파일과 현재 지시보다 낮은 생성 탐색 보조 자료입니다. | 생성 파일이며 `repo_map` 의도 또는 `mf map`으로 갱신합니다. |
+
+## 에이전트 작업 순환
+
+작업은 다음 순환을 따릅니다. 이 순환은 `.mustflow/config/mustflow.toml`의 `[agent_loop].phases`에도 기계가 읽을 수 있는 값으로 선언되어 있습니다.
+
+1. `orient`: 필수 mustflow 문서, 현재 루트, 보호 경로, 작업 범위를 확인합니다.
+2. `plan`: 수정 전 작은 계획을 세우며, 명령이나 관습을 추측하지 않습니다.
+3. `act`: 요청 범위 내에서 가장 작은 안전한 변경을 수행합니다.
+4. `verify`: `.mustflow/config/commands.toml`에 선언된 단발성 명령만 사용합니다.
+5. `report`: 변경 파일, 실행한 명령, 건너뛴 명령, 검증 결과, 남은 위험을 보고합니다.
+6. `handoff`: 안전하게 종료할 수 없으면 추측하지 않고 후속 작업이나 확인 질문을 남깁니다.
+
+## 기준 문서와 읽기 흐름
+
+필수 읽기 흐름은 다음 순서를 따릅니다.
+
+1. `AGENTS.md`
+2. `.mustflow/docs/agent-workflow.md`
+3. `.mustflow/config/mustflow.toml`
+4. `.mustflow/config/commands.toml`
+5. `.mustflow/config/preferences.toml`이 있으면 읽기
+6. `.mustflow/skills/INDEX.md`
+7. 현재 작업과 맞는 `.mustflow/skills/<name>/SKILL.md`
+8. 관련 소스, 테스트, 문서 파일
+
+`REPO_MAP.md`는 넓은 저장소 탐색이 필요할 때만 읽습니다. 이 파일은 전체 파일 목록이 아니라 `AGENTS.md`, `README.md`, `package.json`, `SKILL.md`, 주요 설정 파일 같은 앵커를 찾아 에이전트가 처음 볼 위치를 줄이기 위한 생성 지도입니다. 전체 파일 목록이 필요하면 `git ls-files`나 편집기 파일 탐색기를 사용합니다. `node_modules`, `dist`, `build`, `.git`, 캐시, 대용량 산출물은 제외합니다.
+
+`mf context --json`을 사용할 수 있으면 현재 mustflow 루트의 읽기 순서, 명령 의도, 기능 표면, 마지막 실행 요약을 빠르게 확인할 수 있습니다. 이 출력은 얇은 색인일 뿐이며, 필수 문서와 실제 설정 파일 읽기를 대신하지 않습니다.
+
+`mf doctor` 또는 `mf doctor --json`을 사용할 수 있으면 수정 전에 현재 mustflow 루트의 설치 상태, 검사 결과, 실행 가능한 명령 의도, 다음 단계를 읽기 전용으로 확인합니다. 이 명령은 첫 방향을 잡기 위한 진단 명령이며, 파일을 쓰지 않습니다.
+
+## 프로젝트 문맥
+
+`.mustflow/context/`는 에이전트를 위한 작업별 프로젝트 문맥을 담습니다. 일반 문서 보관함이 아닙니다.
+
+- 프로젝트, 제품, 도메인, UI, 백엔드, 데이터, 보안, 운영 문맥이 필요한 작업일 때만 `.mustflow/context/INDEX.md`를 읽습니다.
+- 문맥 색인에서 선택된 파일만 읽습니다.
+- 문맥 파일은 사용자 직접 지시, 현재 코드, 테스트, 명령 계약, 설정된 정책보다 낮은 권위의 참고 자료입니다.
+- 빠진 프로젝트 목표, 비목표, API 약속, 데이터 규칙, 디자인 토큰을 추측해 생성하지 않습니다.
+- `DESIGN.md`가 있으면 UI 작업에서 참고하는 선택적 외부 시각 디자인 참조로 봅니다. 그 안의 디자인 토큰을 `.mustflow/context/`에 중복 기록하지 않습니다.
+- 문맥이 현재 파일이나 명령 계약과 충돌하면 충돌을 보고하고 더 높은 권위의 출처를 따릅니다.
+
+## 스킬 활성화
+
+스킬은 자율 실행 도구가 아니라 작업 절차 문서입니다. 스킬을 활성화한다는 것은 현재 명령 계약 내에서 해당 `.mustflow/skills/<name>/SKILL.md`를 읽고 그 절차를 따른다는 뜻입니다.
+
+작업 시작 시점과 첫 수정 전에는 다음 순서를 따릅니다.
+
+1. `.mustflow/skills/INDEX.md`를 읽습니다.
+2. 현재 사용자 요청과 예상 변경 파일을 색인의 시나리오와 비교합니다.
+3. 맞는 시나리오가 하나 이상 있으면 해당 `SKILL.md`를 읽은 뒤 그 범위를 수정합니다.
+4. 맞는 스킬이 없으면 새 스킬을 추측하지 않고 `AGENTS.md`와 `.mustflow/config/commands.toml`을 기준으로 가장 작은 안전한 변경을 수행합니다.
+
+작업 중 새 근거가 생겨 작업 유형이 바뀌면 그때 스킬을 다시 선택합니다. 예를 들어 설정된 명령이 실패하면 실패 원인 추적 스킬을, 테스트 계약이 바뀌면 테스트 유지보수 스킬을, 문서나 워크플로가 바뀌면 문서 수정 스킬을 읽습니다.
+
+여러 스킬이 동시에 맞으면 변경 범위별로 가장 구체적인 스킬을 따르며, 각 스킬이 선언한 명령 의도만 합쳐서 검토합니다. 스킬은 원시 셸 명령, 장기 실행 프로세스, 작업 범위 밖 쓰기를 허용하지 않습니다.
+
+스킬을 사용했거나 사용할 수 있어 보이는 스킬을 일부러 건너뛰었다면, 다음 사용자 업데이트나 최종 보고에서 스킬 이름과 선택 이유를 간략히 밝힙니다. 스킬 선택 기록만을 위해 버전 관리되는 작업 로그를 만들지 않습니다.
+
+## 상위/하위 규칙 우선순위
+
+현재 작업 경로에 더 가까운 `AGENTS.md`가 더 구체적인 규칙입니다. 상위 작업 공간의 `AGENTS.md`와 하위 저장소의 `AGENTS.md`가 함께 적용되는 경우, 규칙 종류에 따라 다음 기준을 따릅니다.
+
+- 사용자 직접 요청, 시스템 지침, 개발자 지침은 항상 mustflow 문서보다 우선합니다.
+- 코드 스타일, 테스트 방식, 빌드 방식, 문서 작성 방식은 하위 저장소 규칙을 우선합니다.
+- 실제 실행 명령은 현재 작업 대상 저장소의 `.mustflow/config/commands.toml`을 우선합니다.
+- 보안, 비밀정보, 개인정보, 파괴적 명령, 수정 가능 경로, 저장소 경계 규칙은 누적 적용하며 더 엄격한 규칙을 따릅니다.
+- 보고 형식은 상위 작업대 요구와 하위 저장소 요구를 함께 만족하되, 충돌 시 더 구체적인 하위 저장소 요구를 우선합니다.
+
+상위 작업대에서 하위 독립 저장소로 들어가 작업할 때는 다음 순서를 따릅니다.
+
+1. 하위 저장소의 `AGENTS.md`를 읽습니다.
+2. 하위 저장소의 `.mustflow/config/mustflow.toml`을 읽습니다.
+3. 하위 저장소의 `.mustflow/config/commands.toml`을 읽습니다.
+4. 하위 저장소의 `.mustflow/skills/INDEX.md`에서 작업과 맞는 스킬을 확인합니다.
+5. 명시 요청이 없으면 선택한 하위 저장소 밖의 파일을 수정하지 않습니다.
+
+상위 `REPO_MAP.md`가 `Nested Repositories` 섹션을 제공하더라도, 그 섹션은 하위 저장소 내부 규칙을 대신하지 않습니다. 하위 저장소에서 실제 작업을 시작하면 그 저장소의 `AGENTS.md`와 `.mustflow/**`가 작업 방식과 명령 계약의 기준입니다.
+
+## 작업 시작 전 확인
+
+작업을 시작하기 전에 다음을 확인합니다.
+
+- 현재 변경 파일이 있는지 확인합니다.
+- 사용자 요청의 실제 수정 범위를 좁힙니다.
+- 작업 대상 경로가 `.mustflow/config/mustflow.toml`의 보호 경로에 포함되는지 확인합니다.
+- 필요한 명령 의도가 `.mustflow/config/commands.toml`에 등록되어 있는지 확인합니다.
+- mustflow 자체 상태가 불명확하면 `mustflow_doctor` 의도 또는 `mf doctor --json`으로 읽기 전용 진단을 먼저 확인합니다.
+- 작업과 맞는 스킬이 있으면 해당 `SKILL.md`를 읽습니다.
+- 명령 의도가 실행 가능하지 않으면 임의 대체 명령을 찾지 말고, 건너뛴 이유를 보고합니다.
+
+## 입력 안정성 정책
+
+반복해서 읽는 문서는 앞부분이 안정적이어야 합니다.
+
+- 안정적인 공통 규칙은 `AGENTS.md`와 이 문서에 둡니다.
+- 실제 실행 명령은 `.mustflow/config/commands.toml`에만 둡니다.
+- 작업별 절차는 `.mustflow/skills/*/SKILL.md`에 둡니다.
+- 생성 파일과 자주 바뀌는 정보는 필수 읽기 순서 앞쪽에 두지 않습니다.
+- 생성 시각, 해시, 최근 변경, 파일 수, 긴 로그 같은 변동 값은 문서 상단에 두지 않습니다.
+- 전체 대화 원문, 전체 터미널 출력, 원시 JSONL 이벤트 로그는 `.mustflow/` 안에 계속 덧붙이지 않습니다.
+- 실행 결과는 `.mustflow/state/runs/latest.json`처럼 작은 실행 영수증으로 남기고, 지식 문서는 원문 로그가 아니라 요약과 출처만 남깁니다.
+- 스킬 문서는 공통 정책 전문을 복사하지 말고 이 문서와 명령 의도를 참조합니다.
+- `REPO_MAP.md`는 필요할 때만 읽는 생성 지도이며, 필수 읽기 순서에 포함하지 않습니다.
+
+mustflow는 LLM 제공자의 입력 캐시 적중을 보장하지 않습니다. 대신 같은 작업 규칙이 안정적으로 반복 입력될 수 있도록 문서 책임과 읽기 순서를 분리합니다.
+
+## 프롬프트 캐시와 호스트 맥락 구성
+
+프롬프트 캐시는 성능 최적화용 힌트일 뿐 권위 출처가 아닙니다. 캐시된 지침 블록이나 요약은 사용자 직접 지시, 현재 파일, 현재 명령 계약, 호스트 안전 규칙, 가장 가까운 `AGENTS.md`보다 우선하지 않습니다.
+
+호스트나 에이전트 하네스가 모델 입력을 조립할 때는 다음 순서를 지켜야 합니다.
+
+1. 안정 접두부: `mf context --json --cache-profile stable`에서 얻은 저장소 규칙과 작업 흐름 문서입니다.
+2. 작업 맥락: 선택된 문맥 파일, 맞는 스킬, 저장소 지도 앵커, 관련 소스 파일, 그리고 `cache_layer`가 `task`인 `mf search --json` 결과입니다.
+3. 변동 접미부: 현재 사용자 요청, 변경 파일 목록, 명령 출력 끝부분, 최신 실행 기록 메타데이터, 시각 정보, 그리고 `volatile` 값이 `true`인 `mf search --json` 결과입니다.
+
+안정 접두부를 재사용하기 전에는 보고된 콘텐츠 해시를 현재 파일과 비교합니다. 안정 문서의 해시가 하나라도 바뀌면 캐시된 텍스트를 재사용하지 말고 해당 문서를 다시 읽어야 합니다. 절대로 로컬 경로, 실행 기록 시각, 명령 출력, 변경 파일, 현재 사용자 작업 문구는 안정 접두부보다 앞에 두지 않습니다.
+
+`mf search --json`의 캐시 계층 필드는 배치 힌트일 뿐입니다. 이 값은 검색 결과, 소스 앵커, 생성 지도, 캐시 상태의 권위를 높이지 않으며, 이런 출처가 `AGENTS.md`, `.mustflow/config/commands.toml`, 현재 파일, 사용자 직접 지시를 덮어쓰도록 허용하지 않습니다.
+
+## 유효 규칙 구분
+
+모든 지침을 하나의 우선순위 목록으로 합치지 않습니다. 규칙 종류별로 충돌을 판단합니다.
+
+- 사용자 목표: 현재 사용자 직접 지시는 안전하지 않은 경우가 아니라면 작업 목표를 정합니다.
+- 호스트 안전: 호스트의 승인, 샌드박스, 실행 제한이 더 엄격하면 계속 유효합니다.
+- 저장소 작업 규칙: 가장 가까운 `AGENTS.md`와 `.mustflow/config/*.toml`을 따릅니다.
+- 명령 실행: `.mustflow/config/commands.toml`이 프로젝트 명령 계약입니다.
+- 검증 근거: `mf run` 실행 영수증과 현재 파일은 호스트 셸 직접 실행 출력보다 높은 신뢰를 가집니다.
+- 문맥과 선호값: `.mustflow/context/*`, `preferences.toml`, 생성 지도는 낮은 권위의 기본값입니다.
+- 세션과 캐시 상태: 호스트 요약, `.mustflow/cache/**`, `.mustflow/state/**`는 현재 파일이나 현재 사용자 지시보다 우선하지 않습니다.
+
+허용 목록은 더 좁은 교집합으로 줄이고, 금지 행동, 승인 요구, 개인정보 규칙, 파괴적 명령 규칙은 누적합니다. 유효 규칙이 불명확하면 추측하지 말고 멈춘 뒤 충돌을 보고합니다.
+
+## 지침 새로고침 정책
+
+긴 세션에서는 작업 시작 때 읽은 지침이 뒤쪽 대화, 도구 출력, 맥락 압축에 밀릴 수 있습니다. mustflow는 이를 대화 횟수 파일로 처리하지 않고, 지침을 다시 확인해야 하는 지점으로 다룹니다.
+
+mustflow 지침은 다음 지점에서 다시 확인합니다.
+
+- 세션 시작
+- 새 작업 시작
+- 첫 파일 수정 전
+- 현재 작업과 명령 의도에 대한 신선한 명령 수준 새로고침이 없을 때 명령 실행 전
+- `AGENTS.md` 또는 `.mustflow/**` 수정 후
+- 작업 루트 변경 또는 하위 독립 저장소 진입 후
+- 맥락 압축이나 요약 후
+- 최종 보고 전
+- 설정된 대화 횟수, 도구 호출 수, 출력 크기 기준 초과 시
+
+`.mustflow/config/mustflow.toml`의 `[refresh]`는 어떤 수준으로 다시 확인할지 선언합니다.
+
+- `light`: `AGENTS.md`와 `.mustflow/docs/agent-workflow.md`를 다시 읽습니다.
+- `command`: `AGENTS.md`와 `.mustflow/config/commands.toml`을 다시 읽습니다.
+- `edit`: 민감한 수정 전에 `AGENTS.md`, `.mustflow/config/mustflow.toml`, `.mustflow/docs/agent-workflow.md`를 다시 읽습니다.
+- `report`: 최종 보고 전에 `AGENTS.md`, `.mustflow/config/mustflow.toml`, `.mustflow/config/preferences.toml`을 다시 읽습니다.
+- `skill`: `AGENTS.md`와 `.mustflow/skills/INDEX.md`를 다시 읽습니다.
+- `full`: mustflow 필수 읽기 순서 전체를 다시 읽습니다.
+
+`before_command_run`은 현재 명령 의도에 대한 신선도 확인 지점입니다. 명령 계약이 바뀌지 않았다면 같은 명령을 반복할 때마다 모든 파일을 다시 읽으라는 뜻이 아닙니다.
+
+대화 횟수, 메시지 수, 세션 활동 상태를 프로젝트 파일에 쓰지 않습니다. 에이전트 호스트가 새로고침 상태를 추적한다면 Git에 포함되는 프로젝트 문서가 아니라 로컬 캐시나 호스트 상태 저장소를 사용해야 합니다. 스킬 문서는 새로고침 절차를 설명할 수 있지만, 대화 종료 훅처럼 항상 실행되는 제어 장치로 보지 않습니다.
+
+## 문맥 압축 정책
+
+`compaction`은 기본 데이터 수집 기능이 아니라 향후 하네스나 호스트가 지켜야 할 안전 정책입니다. 기본 템플릿은 이 기능을 꺼 둔 상태에서 안전 규칙만 선언합니다.
+
+프로젝트 내에 숨겨진 내부 추론, 비밀정보, 전체 대화 전문, 전체 터미널 출력, 원본 이벤트 로그, 원본 명령 로그를 저장하지 않습니다. 향후 호스트가 요약을 만들더라도 요약은 출처가 있어야 하며, 현재 파일과 현재 사용자 지시보다 낮은 권위를 가집니다.
+
+## 하네스 계약 경계
+
+mustflow는 자율 에이전트 실행 환경이 아닙니다. mustflow는 여러 에이전트 하네스가 저장소에 들어왔을 때 읽고 따를 수 있는 저장소 내부 작업 계약층입니다.
+
+- 사고 계약: `AGENTS.md`, 이 문서, 스킬 문서는 모델이 따라야 할 작업 절차를 설명합니다.
+- 실행 계약: `.mustflow/config/commands.toml`과 `mf run`은 안전한 명령 실행 경계를 정합니다.
+- 세션 계약: 실행 영수증, 제한된 체크포인트, 작은 인계 문서는 복구와 검토 근거를 남깁니다.
+
+저장소가 명시적으로 선택 기능을 추가하지 않았다면 `workers/`, `personas/`, 여러 에이전트 조정 폴더, 원시 이벤트 로그, 자율 반복 실행기를 만들지 않습니다.
+
+## 장기 작업 단계
+
+장기 작업이나 이어받아야 하는 작업은 다음 단계를 분리합니다.
+
+1. 계획: 작업 목표, 저장소 규칙, 명령 계약, 완료 기준을 읽습니다.
+2. 작업: 현재 단위에서 가장 작은 안전한 변경을 수행합니다.
+3. Verify: 설정된 단발성 명령 의도만 실행하며, 가능하면 `mf run`을 사용합니다.
+4. 판정: 원래 완료 기준, 변경 파일, 명령 계약, 실행 영수증을 기준으로 결과를 평가합니다.
+5. 인계: 작업이 미완료, 차단, 계속 진행 필요 상태이면 작은 인계 내용을 남깁니다.
+
+판정 단계는 작업자가 “완료”라고 말한 사실만으로 충분하다고 보지 않습니다. 원래 목표와 완료 기준, 변경 파일, 명령 계약, 실행 영수증을 근거로 판단합니다.
+
+## 선호값 해석 정책
+
+`.mustflow/config/preferences.toml`은 저장소별 기본 선호값입니다.
+
+이 파일의 값은 사용자 직접 지시, 시스템 지침, 개발자 지침, 하위 `AGENTS.md`, 기존 파일 스타일보다 낮은 기본값입니다. 선호값을 이유로 기존 코드 전체를 재포맷하거나, 요청과 무관한 파일을 변경하거나, 운영 로그와 사용자 노출 문자열을 임의로 번역하지 않습니다.
+
+언어 관련 값은 대상별로 해석합니다.
+
+- `language.agent_response`: 최종 보고와 대화 응답의 기본 언어입니다.
+- `language.docs`: 새 문서나 mustflow 문서를 작성할 때 기본 언어입니다.
+- `language.code_comments.mode`: 코드 주석 언어 관습 판단 방식입니다.
+- `language.code_comments.fallback`: 기존 관습이 없을 때 사용할 코드 주석 언어입니다.
+- `language.logs.mode`: 콘솔 로그와 오류 메시지 언어 관습 판단 방식입니다.
+- `language.logs.fallback`: 기존 로그 관습이 없을 때 사용할 로그 언어입니다.
+- `language.user_facing_text.mode`: 사용자에게 노출되는 문자열의 언어 관습 판단 방식입니다.
+
+기존 관습이 보이지 않는 신규 저장소나 초기 저장소에서는 각 항목의 `fallback` 값을 사용합니다. 사용자 대화 언어를 근거로 코드 주석, 로그, 오류 메시지, 커밋 메시지 언어를 자동 결정하지 않습니다.
+
+`fallback`도 없고 기존 관습도 보이지 않으면 다음 기준을 사용합니다.
+
+- 코드 주석, 로그, 오류 메시지, 식별자, 커밋 메시지는 영어를 기본값으로 둡니다.
+- mustflow 문서와 에이전트 보고는 선택된 mustflow 문서 언어를 따릅니다.
+- 포매터나 설정 파일이 없으면 넓은 서식 관습을 새로 만들지 않습니다.
+
+## Git 행동 정책
+
+Git 기록을 바꾸는 행동은 기본적으로 금지합니다.
+
+- `git.auto_stage = false`: 사용자 요청 없이 스테이징하지 않습니다.
+- `git.auto_commit = false`: 사용자 요청 없이 커밋하지 않습니다.
+- `git.auto_push = false`: 사용자 요청 없이 푸시하지 않습니다.
+
+이 값들은 저장소 선호값이지 권한이 아닙니다. 사용자 직접 지시, `.mustflow/config/commands.toml`, `.mustflow/config/mustflow.toml`의 승인 정책보다 우선하지 않습니다. 특히 `git.auto_commit = true`는 푸시 권한을 뜻하지 않으며, `git.auto_push = true`는 `mf init`으로 설정할 수 없습니다.
+
+스테이징, 커밋, amend, rebase, reset, push 등 Git 상태나 기록을 바꾸는 작업은 사용자가 명시적으로 요청한 경우에만 수행합니다.
+
+커밋 메시지 추천은 Git 실행 권한이 아니라 최종 보고 품질을 높이기 위한 설명 규칙입니다. `git.commit_message.suggest = "when_changes_made"`이고 파일을 수정했다면 최종 보고에 권장 커밋 메시지를 포함할 수 있습니다. 이 제안은 참고용이며, 실제 커밋이 생성되었다고 표현해서는 안 됩니다.
+
+커밋 메시지를 제안할 때는 다음을 지킵니다.
+
+- 에이전트가 이번 작업에서 바꾼 내용만 기준으로 삼습니다.
+- 기존 사용자 변경사항을 섞어 하나의 커밋 메시지로 요약하지 않습니다.
+- 여러 논리 변경이 섞였으면 최대 `git.commit_message.max_suggestions` 안에서 분할 커밋을 제안합니다.
+- 브랜치명, 원격 저장소 URL, 고객명, 비밀 경로, 내부 이슈명 등 민감할 수 있는 세부 정보는 포함하지 않습니다.
+- 검증 결과는 커밋 메시지보다 최종 보고의 검증 항목에 둡니다.
+
+## 버전 영향 정책
+
+버전 영향 설정은 저장소 선호값입니다. 버전 파일을 수정할지 판단할 때 이 값을 따르지만, 사용자 직접 지시, 호스트 안전 규칙, `.mustflow/config/mustflow.toml`의 승인 관문보다 우선하지는 않습니다.
+
+코드, 템플릿, 스키마, CLI 동작, 패키지 메타데이터, 사용자에게 보이는 문서, 설치 출력, 테스트가 변경되면 `.mustflow/config/preferences.toml`의 `[release.versioning]`을 확인합니다.
+
+- `impact_check = true`: 현재 변경이 패키지나 템플릿 버전 변경을 요구하는지 보고합니다.
+- `suggest_bump = true`: 근거가 분명할 때 패치, 마이너, 메이저 중 알맞은 판올림을 제안합니다.
+- `auto_bump = true`: 영향이 분명하고 버전 기준 원본을 찾았으며 더 엄격한 사용자, 호스트, 승인 규칙이 막지 않을 때 알맞은 패키지나 템플릿 버전 판올림을 적용합니다.
+- `auto_bump = false`: 사용자가 버전 판올림이나 릴리스 준비 작업을 요청하지 않으면 패키지와 템플릿 버전 파일을 그대로 둡니다.
+- `require_user_confirmation = true`: 버전 파일을 수정하기 전에 사용자에게 확인합니다.
+- `require_user_confirmation = false`: `auto_bump = true`이면 별도 확인 단계를 추가하지 않습니다.
+
+버전 변경을 제안하거나 적용하기 전에는 이 저장소의 버전 기준 원본을 먼저 찾습니다. `package.json`만 버전 파일이라고 가정하지 않습니다. 저장소 언어와 프레임워크에 맞는 매니페스트, 릴리스 문서, 기존 판올림 패턴을 확인한 뒤 어떤 파일이 기준 원본이고 어떤 파일이 파생 파일인지 판단합니다.
+
+자주 쓰이는 버전 원천 후보는 다음과 같습니다.
+
+- JavaScript 또는 TypeScript: `package.json`과 패키지 메타데이터를 중복 기록하는 lockfile.
+- Python: `pyproject.toml`, `setup.cfg`, `setup.py`, 패키지의 `__version__` 파일.
+- Rust: `Cargo.toml`. `Cargo.lock`은 저장소가 lockfile 변경을 릴리스 메타데이터로 다룰 때만 함께 봅니다.
+- Go: 릴리스 태그와 릴리스 문서를 먼저 확인합니다. `go.mod`는 모듈 경로나 도구 메타데이터가 관련될 때만 봅니다.
+- Java 또는 Kotlin: `pom.xml`, `build.gradle`, `build.gradle.kts`, `gradle.properties`.
+- .NET: `*.csproj`, `Directory.Build.props`, `*.nuspec`.
+- Ruby, PHP, Dart, Swift: `*.gemspec`, `lib/**/version.rb`, `composer.json`, `pubspec.yaml`, `Package.swift`.
+- 컨테이너, 차트, 애플리케이션: `Chart.yaml`, 이미지 라벨, 앱 매니페스트, 릴리스 노트, 배포 메타데이터.
+- mustflow 템플릿: 패키지 메타데이터, 템플릿 매니페스트, 문서 예시, 설치 버전을 검증하는 테스트.
+
+버전을 바꿀 때는 `sync_*` 선호값에 따라 패키지 메타데이터, 템플릿 매니페스트 버전, 문서 예시, 테스트를 같은 변경 안에서 맞춥니다.
+
+## 명령 실행 정책
+
+`.mustflow/config/commands.toml`은 실행 명령의 기준 원본입니다.
+
+에이전트는 다음 조건을 모두 만족하는 명령 의도만 실행합니다.
+
+- `status = "configured"`
+- `lifecycle = "oneshot"`
+- `run_policy = "agent_allowed"`
+- `stdin = "closed"`
+- `timeout_seconds`가 양의 정수
+- `argv` 또는 `mode = "shell"`과 `cmd`로 실행 명령이 선언됨
+- `cwd`가 현재 mustflow 루트 안에 있음
+
+새 설정에서는 `manual_only`를 명령 의도의 `status` 값으로 사용합니다. `run_policy = "manual_only"`는 기존 설정 호환을 위해 읽을 수 있지만, 새 템플릿에서는 만들지 않습니다.
+
+명령 의도가 없거나 `unknown`, `not_applicable`, `manual_only`, `disabled`이면 대체 명령을 추측하지 않고 건너뛴 이유를 보고합니다.
+
+명령 의도 상태의 의미는 다음과 같습니다.
+
+- `configured`: 실행 가능한 명령이 선언되어 있습니다.
+- `unknown`: 아직 명령 계약이 없습니다.
+- `not_applicable`: 이 저장소에는 해당 검증이 필요하지 않습니다.
+- `manual_only`: 사람이 직접 판단해서 실행해야 합니다.
+- `disabled`: 명령은 알려져 있지만 현재 실행하면 안 됩니다.
+
+`configured` 의도는 가능하면 `argv` 배열로 선언합니다. 셸 문법이 꼭 필요할 때만 `mode = "shell"`과 `cmd`를 사용합니다.
+
+명령 생명주기의 의미는 다음과 같습니다.
+
+- `oneshot`: 실행 후 종료되어야 하는 명령입니다.
+- `server`: 로컬 서버처럼 계속 떠 있는 명령입니다.
+- `watch`: 파일 변경을 감시하며 종료되지 않는 명령입니다.
+- `interactive`: 사용자 입력을 기다리는 명령입니다.
+- `browser`: 브라우저나 UI 프로세스를 여는 명령입니다.
+- `background`: 백그라운드로 남는 명령입니다.
+
+에이전트가 기본으로 실행할 수 있는 생명주기는 `oneshot`뿐입니다. `server`, `watch`, `interactive`, `browser`, `background`는 직접 실행하지 않습니다. 개발 서버, 감시 모드, 브라우저 UI, `npm run dev`, `bun dev`, `playwright test --ui`, `chrome`, `chromium` 같은 명령은 끝나는 검증 명령으로 취급하지 않습니다.
+
+셸 백그라운드 실행도 금지합니다. `&`, `nohup`, `disown`, `start`, `Start-Process`, 브라우저 직접 실행처럼 프로세스를 남길 수 있는 방식은 사용하지 않습니다.
+
+실행 가능한 의도에는 다음 정보가 있어야 합니다.
+
+- 실행 방식
+- 작업 디렉터리
+- 명령 생명주기
+- 실행 정책
+- 제한 시간
+- 표준 입력 처리 방식
+- 성공 종료 코드
+- 쓰기 경로
+- 네트워크 사용 여부
+- 파괴적 작업 여부
+
+쓰기 경로가 있거나 파괴적일 수 있는 명령은 실행 전에 영향 범위를 확인합니다. 프로젝트 테스트, 빌드, 규칙 검사처럼 저장소별 동작을 수행하는 명령은 계약에 없으면 발견하거나 추측해 실행하지 않습니다. `mf help`, `mf status`, `mf doctor --json`, `mf context --json`처럼 mustflow 상태를 읽기만 하는 검사 명령은 작업 맥락 확인용으로 사용할 수 있습니다.
+
+단발성 명령은 해당 실행기를 우선적으로 사용하십시오. `mf run`은 `oneshot` 의도만 실행해야 하며, 장기 실행 생명주기를 가진 의도는 거부해야 합니다. 제한 시간을 넘긴 명령은 실패로 보고하며, mustflow가 시작한 프로세스만 정리 대상입니다. 포트 번호만 보고 임의 프로세스를 종료하지 않습니다.
+
+`mf run`으로 명령을 실행하면 `.mustflow/state/runs/latest.json`에 간결한 실행 결과 기록을 남깁니다. 자동화가 결과를 읽어야 하거나 최종 보고 근거가 필요하면 `mf run <intent> --json`을 사용합니다. 실행 결과 기록에는 의도 이름, 실제 실행 방식, 작업 디렉터리, 제한 시간, 종료 코드, 시간 초과 여부, 표준 출력/오류 끝부분이 포함됩니다.
+
+`mf run` 명령 의도는 순차로 실행합니다. 설정된 다른 의도가 아직 실행 중이면 두 번째 `mf run`을 시작하지 않습니다. 비어 있지 않은 `writes`를 선언한 의도는 배타적인 검증 단계이므로, 다른 `mf run`을 실행하기 전에 종료될 때까지 기다립니다. 특히 의도가 `dist/` 같은 패키지 산출물을 다시 쓰는 경우 중요합니다. 로컬 `mf` 실행 파일이 그 산출물에서 로드될 수 있기 때문입니다.
+
+설치된 mustflow 문서 흐름을 갱신할 때도 원시 `mf update`를 직접 실행하지 말고 설정된 갱신 의도를 사용합니다. 먼저 `mustflow_update_dry_run`으로 계획을 확인하고, 차단된 로컬 변경이나 수동 검토 항목이 없으며 작업이 실제 적용을 요구할 때만 `mustflow_update_apply`를 실행합니다. 적용 의도는 여전히 `mf update`의 안전 정책을 따라 템플릿 매니페스트 경로, 백업, 잠금 파일 항목만 쓰고 로컬 변경은 거부합니다.
+
+호스트 셸은 명령을 실행할 수 있지만, 프로젝트 명령을 직접 실행한 결과가 곧 mustflow 검증 근거가 되지는 않습니다. `mf run`을 우회한 명령 출력은 사용자가 명시적으로 수동 우회를 승인했고 최종 보고에 mustflow 실행 영수증이 없음을 밝힌 경우가 아니라면 낮은 신뢰도의 참고 정보로만 봅니다.
+
+실행 결과 기록은 검증 증거이지만 기준 원본은 아닙니다. 명령이 무엇이어야 하는지는 `.mustflow/config/commands.toml`을 따르며, 실행 결과 기록은 특정 시점에 무엇이 실행되었고 어떻게 끝났는지 보고할 때 사용합니다.
+
+## 수정 정책
+
+- 요청과 직접 관련된 파일만 수정합니다.
+- 기존 변경 사항을 되돌리지 않습니다.
+- 보호 경로, 외부 의존성, 생성 산출물은 명시 요청 없이 수정하지 않습니다.
+- 생성 파일은 가능하면 직접 편집하지 않고 선언된 명령 의도로 갱신합니다.
+- 루트의 `config/`, `docs/`, `skills/`는 프로젝트 자체 경로일 수 있으므로 mustflow 문서로 가정하지 않습니다.
+- mustflow 문서 흐름에 속한 파일은 기본적으로 `AGENTS.md`와 `.mustflow/**`입니다.
+
+## 문서 검수 대기열
+
+에이전트가 사용자에게 보이는 문서, 워크플로 문서, 템플릿 문서, 문맥 문서, 스킬 문서를 생성하거나 수정하면 사용자가 추적하지 말라고 명시한 경우를 제외하고 `mf docs review add <path>`로 해당 문서를 기록합니다. 대기열은 `.mustflow/review/docs.toml`에 저장되며 필요할 때만 생성됩니다.
+
+검수 완료 주체는 사람, LLM, 도구, 외부 프로세스일 수 있습니다. 특정 LLM 제품 목록을 고정으로 관리하지 말고, 넓은 검수자 종류와 자유 형식의 검수자 식별자, 제공자, 모델, 명령 의도, 요약만 기록합니다.
+
+검수된 문서를 기본 목록에서 숨기되 기록을 남기려면 `mf docs review approve <path> --reviewer-kind <kind> --reviewer-id <id>`를 사용합니다. 검수자가 확신을 가지고 승인할 수 없으면 `needs-human`을, 저장소가 의도적으로 검수에서 제외하는 문서에는 `ignore`를 사용합니다.
+
+## 검증 정책
+
+- 코드 변경 후에는 관련 테스트나 규칙 검사 의도가 `configured`인지 확인하고 실행합니다.
+- 문서만 변경한 경우에도 링크, 명령 의도 이름, 경로가 맞는지 확인합니다.
+- 설정 파일을 변경한 경우에는 형식과 실제 경로를 함께 확인합니다.
+- mustflow 문서 흐름, 스킬, 명령 계약, 저장소 지도를 변경한 경우 가능하면 `mf check --strict`를 실행합니다.
+- 실행하지 못한 검증은 이유를 숨기지 않고 보고합니다.
+
+검증 명령을 실행할 수 없을 때는 대체 명령을 추측하지 않습니다. 대신 실행하지 못한 의도 이름, 상태, 이유를 보고합니다. 명령 의도가 `configured`라도 `lifecycle = "oneshot"`이 아니면 검증 명령으로 실행하지 않고, 장기 실행 명령이라 건너뛰었다고 보고합니다.
+
+## 검증 선택 정책
+
+검증 범위는 `.mustflow/config/preferences.toml`의 `[verification.selection]`을 참고합니다. 이 값은 명령 실행 권한이 아니라, 어떤 configured 명령 의도를 검토할지 정하는 기본값입니다.
+
+검증은 위험 크기에 비례해야 합니다. 바뀐 표면을 덮는 `test_related`, `test_fast`, `build`, 문서 전용 검증이 설정되어 있으면 넓은 전체 테스트보다 먼저 사용합니다. 전체 테스트는 여러 영역을 가로지르는 동작, 릴리스 위험, 더 좁은 검증 누락, 또는 설정된 정책이 명시적으로 요구하는 경우에 사용합니다. 더 좁은 의도가 적절하지만 `unknown`, `manual_only`, 또는 미선언 상태라면 느린 전체 테스트를 조용히 기본값으로 삼지 말고 그 공백을 보고합니다.
+
+- `strategy = "risk_based"`: 바뀐 동작, 공개 표면, 명령 계약, 위험 영역을 덮는 가장 작은 검증을 우선합니다.
+- `strategy = "targeted"`: 사용자 지시, 스킬, 정책이 더 넓은 검증을 요구하지 않으면 직접 관련된 검증을 우선합니다.
+- `strategy = "full"`: 적용 가능한 configured 검증 묶음을 폭넓게 우선합니다.
+- `prefer_related_tests = true`: 넓은 테스트보다 더 좁고 관련 있는 테스트 의도를 먼저 찾습니다.
+- `skip_docs_only_full_test = true`: 문서만 변경된 경우 문서 검증이 해당 표면을 덮으면 넓은 테스트를 생략할 수 있습니다.
+- `skip_translation_only_full_test = true`: 원본 동작이 변경되지 않은 번역 전용 변경은 넓은 테스트를 생략할 수 있습니다.
+- `skip_copy_only_full_test = true`: 동작, 스키마, 템플릿, 명령 계약이 변경되지 않은 문구 변경은 넓은 테스트를 생략할 수 있습니다.
+- `report_skipped = true`: 최종 보고에 생략한 검증과 이유를 남깁니다.
+
+동작, 보안, 데이터, 명령 계약, 릴리스 산출물, 생성 템플릿이 변경된 근거가 있으면 생략 설정으로 위험을 숨기지 않습니다. 관련 configured 의도로 올리거나, 필요한 의도가 없다고 보고합니다.
+
+`mf check --strict`는 기본 구조 검사에 더해 스킬 문서의 원시 셸 명령 블록, `REPO_MAP.md`의 생성 시각, 원격 저장소 주소, 브랜치 같은 변동성 높은 메타데이터, 명령 출력 제한 설정, 보존 정책, 생성 파일 크기, 원시 JSONL 로그 흔적, 최신 실행 영수증 형식을 확인합니다. 이 검사는 에이전트가 불안정한 입력이나 추측 가능한 실행 예시를 기준으로 작업하지 않도록 돕는 보조 검증입니다.
+
+## 검증 약화 방지
+
+작업을 완료한 것처럼 보이게 만들기 위해 검증을 약화하지 않습니다.
+
+에이전트는 다음 행동을 하지 않습니다.
+
+- 실패하는 테스트를 삭제해 검증을 통과시키기
+- 이유 설명 없이 단언이나 기대값을 느슨하게 만들기
+- 관련 검증 의도를 건너뛰기
+- 실패를 피하기 위해 명령 의도를 `not_applicable`로 바꾸기
+- 구현 뒤 완료 기준을 바꾸기
+
+의도한 동작이 변경되었거나, 기존 테스트가 잘못되었거나, 새 동작에 맞는 검증이 필요할 때는 테스트를 수정할 수 있습니다. 이 경우 최종 보고에서 이유를 설명합니다.
+
+## 테스트 관련성 정책
+
+테스트는 현재 동작 계약을 검증하는 장치이지, 영구 보존해야 하는 산출물이 아닙니다.
+
+새 테스트를 얼마나 적극적으로 만들지는 `.mustflow/config/preferences.toml`의 `[testing.authoring]`을 참고합니다. 기본값인 `new_test_policy = "evidence_required"`는 공개 동작 변경, 회귀 위험, 설정 규칙, 스키마 계약, 보안이나 데이터 경로처럼 동작 계약을 검증해야 한다는 근거가 있을 때만 새 테스트를 추가하라는 뜻입니다. 이 선호값은 테스트 작성 성향을 안내할 뿐이며, 필요한 검증을 약화하거나 유효한 테스트 삭제를 정당화하지 않습니다.
+
+에이전트는 다음 행동을 하지 않습니다.
+
+- 오래된 테스트가 기대한다는 이유만으로 삭제된 기능을 다시 구현하기
+- 의도적으로 제거된 기능의 테스트를 계속 보존하기
+- 검증을 통과시키기 위해 실패하는 테스트를 삭제하기
+- 동작 변경 설명 없이 단언을 약하게 만들기
+- 테스트를 통과시키기 위해서만 스냅샷을 갱신하기
+
+검증하던 동작이 의도적으로 제거되었거나, 공개 계약이 변경되었거나, 테스트가 제거된 구현 세부사항만 검증하거나, 더 강한 테스트가 같은 위험을 이미 검증하거나, 스냅샷이 낡은 경우에는 테스트를 수정하거나 제거할 수 있습니다.
+
+테스트를 추가, 수정, 삭제했거나 낡은 테스트 후보를 발견했다면 최종 보고에 검증하려는 동작 계약, 영향받은 테스트, 실행한 명령 의도, 건너뛴 명령 의도, 남은 테스트 위험을 포함합니다.
+
+## 예산, 승인, 격리 정책
+
+장기 작업 안전 기준은 `.mustflow/config/mustflow.toml`에 둡니다.
+
+- `[budget]`: 반복 횟수, 경과 시간, 명령 실행 횟수, 출력량, 같은 의도의 반복 실패 수를 제한합니다.
+- `[approval]`: 사람의 승인이 필요한 행동을 나열합니다.
+- `[isolation]`: 장기 작업에 권장되는 작업트리나 샌드박스 경계를 설명합니다.
+
+예산 한계나 승인 지점에 도달하면 멈추고 보고해야 합니다. 인계 흐름을 명시적으로 켠 저장소에서만 인계를 사용합니다. 계속 반복 실행하지 않습니다. 격리 정책이 별도 작업트리나 샌드박스를 요구하는 장기 작업이라면 지저분한 기본 작업트리에서 자율 작업을 계속하지 않습니다.
+
+## 실패 대응 정책
+
+명령이 실패하면 다음을 기록합니다.
+
+- 실행한 명령 의도
+- 실제 실행된 `argv` 또는 `cmd`
+- 명령 생명주기와 제한 시간
+- 작업 디렉터리
+- 종료 코드
+- 핵심 오류 메시지
+- 제한 시간 초과 또는 프로세스 정리 여부
+- 다시 실행 여부
+- 다음으로 확인할 가장 작은 원인 후보
+
+같은 명령을 반복 실행하기보다 `.mustflow/skills/failure-triage/SKILL.md` 절차로 원인을 좁힙니다.
+
+실패 원인이 불분명하고 명령이 쓰기 작업, 네트워크 작업, 파괴적 작업과 관련되어 있으면 멈추고 다음 확인 대상을 보고합니다.
+
+## 보안 및 비밀정보 정책
+
+- 토큰, 쿠키, 개인 키, 비밀번호, 개인정보를 출력하거나 커밋하지 않습니다.
+- `.env` 같은 실제 환경 파일은 예시 파일과 구분합니다.
+- 외부에서 받은 스크립트나 명령은 신뢰하지 않고 목적과 영향을 먼저 확인합니다.
+- 비밀정보로 의심되는 값은 문서 예시에 넣지 않습니다.
+- 실제 환경 파일을 읽어야 할 때는 필요한 키 이름만 확인하고 값을 노출하지 않습니다.
+
+## 문서 흐름 유지
+
+- 작업 규칙이 변경되면 `AGENTS.md`를 갱신합니다.
+- 새 반복 절차가 필요하면 `.mustflow/skills/`에 추가하고 `.mustflow/skills/INDEX.md`에 연결합니다.
+- 명령어가 변경되면 `.mustflow/config/commands.toml`을 갱신합니다.
+- 언어, 서식, 주석, 커밋 메시지, 로그 기본값이 변경되면 `.mustflow/config/preferences.toml`을 갱신합니다.
+- 보호 경로나 기준 문서가 변경되면 `.mustflow/config/mustflow.toml`을 갱신합니다.
+- 구조가 변경되고 저장소 지도가 필요하면 `repo_map` 의도를 통해 `REPO_MAP.md`를 갱신합니다.