에이전트 문서 작성

스킬·프롬프트·진입 지침의 작성·존치·감축·재활성화를 판단할 때 필요한 이유와 원천을 연결한다. 일상 작업은 현재 앱의 워크플로·담당 역할 지침·필요한 공통 스킬을 적용한다. 작성에는 writing-for-agents를 사용하고, 이 Map은 근거 부족·충돌·현행 기준 확인·갱신 시 필요한 원천을 선택하는 입구다. 문서가 바꿀 판단에서 내용의 소유권과 조회 시점을 정하며, 실행 본문 전체를 이 Map에 다시 복제하지 않는다. 일반 노트의 작성·연결은 [비공개 문서]을 따른다.

작성할 때 결정할 것

  • 문서가 바꿔야 할 판단이나 동작, 적용할 요청과 완료 결과를 먼저 정한다. 현재 사용자 요청·적용되는 계약·과거 사례에서 파생한 관례를 구분한다. 기존 승인 안의 작업을 문서가 다시 승인받게 하거나, 요청 범위를 새 작업으로 넓히지 않게 한다.
  • 환경이나 상위 지침이 이미 제공하는 사실은 해당 원천에서 확인한다. 문서에는 환경에서 알 수 없는 이유·적용 조건·필요한 예외를 남긴다.
  • 도구의 입력·출력이나 업무 상태를 판단에 쓸 때는 용어의 의미·기준 시점·성립 조건을 소유 문서에서 확인하게 한다. 현재 값과 의미의 정의를 구분하고, 같은 정의를 여러 진입 지침에 복제하지 않는다. 업무 맥락의 사례는 AI Agent의 활용도를 결정하는 업무 맥락 - SK AX에서 읽는다.
  • 진입 지침에는 언제 무엇을 읽을지 둔다. 작업을 선택한 뒤 필요한 절차와 일부 상황에서만 필요한 참고 자료를 구분한다. 같은 판단에 함께 필요한 내용은 모으고, 조건이 다른 상세는 연결한다.
  • 절차의 완료는 답변·판단·시스템 상태·산출물 중 목적에 맞는 관찰 가능한 결과로 구분한다. 조사량·단계 수·전수 확인은 잘못된 완료 판정의 실제 비용에 맞춘다.
  • 프로젝트 README를 작성·보강할 때는 프로젝트 README는 오래 유지될 설명과 원천 문서의 입구로 구성한다를 읽고 독자와 이용 방식에 맞춰 구성한다.

행동 지침의 표현과 적용 범위

  • 원하는 행동을 짧고 구체적인 긍정형으로 적는다. 금지문을 수정할 때는 권한·안전 경계를 보존하고 그 상황에서 허용되는 행동을 함께 안내한다.
  • 조건에 따라 행동이 달라지면 조건과 행동을 연결하고, 완료 판단이 필요하면 확인할 결과를 명시한다. 기록물은 보존이 필요한 작업에서 만든다.
  • 스킬·프롬프트·진입 지침과 Vault의 절차·운영 계약에 적용한다. 개념·근거·경험·성찰은 각 설명 목적에 맞게 구성한다.
  • 같은 상황에서 수행할 행동을 문장으로 식별할 수 있는지 대조한다. 특정 단어·긍정문·고정 순서만으로 모델 행동이 안정된다고 가정하지 않는다.

긍정형 작성의 채택 맥락은 2026-09-06 자격증 조사 지침을 바꾸고 스킬·프롬프트·Vault의 적용 지점을 검토하도록 한 사용자 요청이다. 당시 두 writing-for-agents 스킬에서 선택한 기준이며 모델 행동의 실험적 보장이나 사용자의 영구적 성향을 뜻하지 않는다.

디자인 판단을 설명할 때

적용 조건·선택·이유를 함께 남긴다. 예를 들어 반복해서 여는 메뉴에서 전환을 줄였다면, 어떤 사용 빈도에서 어떤 지연을 줄이려는 선택인지 설명한다. 수치나 효과 이름만 저장하면 다음 화면에서 적용할 조건을 복원하기 어렵다.

디자인 엔지니어링과 모션 판단 - Emil Kowalski의 Agents with Taste는 좋다고 느낀 이유를 언어로 설명해 판단 기준으로 전달하는 사례다. UI 작업의 원문 방문과 개인 선호 갱신은 UI 디자인을 따른다.

내용의 위치

내용소유하는 원천
개인 경험·지식·판단 이유와 후속 정정개인 원격 Vault의 Source·Atomic과 연결 Map
프로젝트 절차·설계 근거·작업 기록해당 프로젝트 원천과 로컬 Vault
팀의 확정 계약팀 저장소의 공식 문서
현재 값·명령·설정실제 파일·시스템·해당 버전의 공식 원천
계획·위임·리뷰·인수 등 현재 운영 절차현재 작업 앱의 워크플로
역할 고유의 현재 실행 절차담당 에이전트 지침과 직접 연결된 조건부 참고자료
여러 역할이 공유하는 판단·실행 절차공통 스킬
개인 학습·응시·지식 정리 계약해당 프로젝트와 개인 Vault의 현행 계약
이번 요청의 진행·미해결 항목·실행 증거현재 작업 맥락과 필요한 프로젝트 작업 기록

일회성 상태나 사례를 장기 지침으로 굳히지 않는다. 잔여 Claude 메모리는 이미 증류를 거친 기록이며 재승격 대기열로 취급하지 않는다. 장기 기록과 교체 가능한 절차의 관계는 장기 자산은 스킬보다 나를 설명하는 언어 기록이다에서 읽는다.

스킬의 존치와 재활성화

2026-10-12 승인된 정리 기준은 여러 역할이 실제로 공유하는 절차만 스킬로 남기고, 역할별 작업법은 담당 에이전트가 소유하게 하는 것이다. 개인 학습·응시·지식 정리는 해당 프로젝트·Vault 계약을 따르며, 필요한 조회를 줄이려 같은 절차를 스킬에 복제하지 않는다. 일반 인계·질문지·프로젝트 기반 안내처럼 상위 지침과 기본 수행으로 충분한 것은 다른 문서로 통째로 옮기지 않고 별도 절차를 없앤다. 긴 상세·스크립트·자산은 담당 역할의 조건부 자료로 유지할 수 있으며 스킬 등록 자체를 유지 근거로 삼지 않는다. 이는 지침 배치 기준이며 실제 작업 효과를 입증한 결과는 아니다.

이력 — 2026-09-30에는 일상 절차를 작업별 스킬의 실행 본문으로 우선 제공하고, 개인 근거 부족·지침 충돌·현행 계약 또는 갱신 확인·Vault 저장에 필요한 때 원격 Vault를 조회하도록 선택했다. 장기 언어 기록을 원천으로 두고 실행판을 바꿀 수 있다는 원칙을 유지하며, 직접 Vault 읽기를 기본으로 삼았던 전달 정책을 재선택한 것이다. 결정과 적용 범위는 Skill 중심 실행과 Vault 선택 조회 결정 - Codex 대화, 당시 승인 범위는 [비공개 문서]의 plan_version: 2에서 확인한다.

이력 — 2026-10-10에는 사용 앱과 운영 절차의 소유자를 다시 선택했다. 계획·위임·리뷰·인수는 Mixdog 워크플로가 맡고, 당시 작업별 절차는 설치된 작업별 스킬이 맡았다. 운영용 agent-operations 스킬은 Mixdog에서 이미 제거됐고 과거 스냅샷을 근거로 되살리지 않으며, Codex·Claude에 남은 사본도 쓰지 않는다. 결정과 적용 범위는 Mixdog 중심 운영과 CLI 전역 지침 비우기 - Mixdog 대화에서 확인한다.

  • 공통 스킬은 실제로 공유하는 적용 조건·판단·행동·완료 기준을 소유한다. 역할별 절차나 개인·프로젝트 계약의 복사본을 만들지 않는다. 개인 경험·판단 이유·정정 이력은 Vault 원천에 남긴다.
  • 활성·비활성 상태 자체로 존치·폐기를 판단하지 않는다. 자동 호출은 구분되는 요청에 필요한 좁은 조건으로 정하고, 사용자가 선택하는 작업 방식은 명시 호출 전용으로 검토한다.
  • 재활성화 전 본문·참고 파일·호출 설명·현재 계약과 실제 경로를 대조한다. 이동·비활성화 전 명시 호출자와 참고 파일 의존성을 확인한다.
  • 작업 절차는 모델이 아니라 담당 역할을 기준으로 한다. 실제 모델·추론 수준이 노출되고 관찰된 필요에 맞는 보정이 있을 때만 작은 보정을 추가하며 모델명·추론 수준·작업 조합별 전체 사본을 늘리지 않는다.
  • 모델 업데이트, 원천의 계약 변경, 실제 반복 누락은 관련 지침을 재검토할 계기다. 모든 지침의 자동 재작성·모델 설정 변경·일괄 비교 실행으로 확대하지 않는다.
  • 실행판을 갱신할 때 원천 경로·기준 commit·변경 이유와 적용 범위를 추적한다. 개인 기록과 계약의 정본을 스킬로 대체하지 않으며, 현재 값·도구 스키마는 실제 환경에서 확인한다.

개인 근거·현행 Vault 계약을 확인해야 하면 [비공개 문서]에서 시작해 연결된 원천을 읽는다. 2026-09-30 시점에 공통 운영·작성·인계를 앱 사이에 전달하던 [비공개 문서]과 학습·응시·지식 정리·UI·프로젝트 기반의 [비공개 문서]은 그 시점 실행판의 기록이다. 현재 스킬 부재 때 대신 적용할 본문으로 쓰지 않는다. 업무별 이관의 당시 승인 범위는 [비공개 문서]의 plan_version: 1, 후속 결정은 업무별 Skill 확장과 Vault 선택 조회 적용 - Codex 대화에 이력으로 남는다. 각 앱의 형식·호출 설정은 그 앱에서 별도 적용하고 확인한다. 2026-09-20의 재평가와 실사용 관찰 선택은 원격 Vault 정본과 쓰기 운영 결정 - Codex 대화 > 활성·비활성 스킬의 재평가 — 2026-09-20에 보존한다. Claude Code의 당시 사용량 분석은 Claude Code 구독 사용량 분석과 토큰 절감 판단 - Claude 대화 > Vault 조회 구조와 스킬 전환 판단에서 읽으며 이번 방식의 비용 절감을 이미 입증한 근거로 쓰지 않는다.

실제 맥락과 판단 경계를 검토할 때

디자인 시스템 MCP 사례처럼 작업에 실제로 들어온 자료, 해당 판단을 담당하는 원천, 성공 기준을 함께 본다. 특정 문체나 길이의 효과를 모든 모델에 보장하는 근거로 쓰지 않는다.

조회 구조: 항상 전달되는 진입 지침·발견용 설명, 선택 후 읽는 본문, 조건부 참고 자료, 도구가 반환한 전체 출력을 구분한다. 현재 personal_vault의 vault_read는 문서 전체를 반환하므로 앵커나 소제목만 나눠서는 반환량이 줄지 않는다. 분리는 적용 조건이 다른 내용을 실제로 따로 읽게 할 때 검토하며, 같은 자료를 다시 읽는 횟수와 탐색 단계도 함께 본다.

다이어그램의 의미·축약·검증 - Diagram Design > 에이전트 문서를 줄일 때 보존할 입구의 사례처럼 줄인 뒤에도 호출 전 보이는 조건·어휘와 상세 원천으로 가는 경로를 보존한다. 특정 용량 제한이나 유형 목록을 모든 문서의 규격으로 적용하지 않는다.

현재 적용 가능성: 원문 충실도와 현재 유효성은 별도로 판단한다를 적용한다. 최신 commit은 저장본의 버전을, 원문 대조는 기록의 충실도를 확인한다. 현재 행동은 현행 계약과 사용자 요청으로 정하며, 외부 자료의 제안·과거 결정을 실행 권한으로 확대하지 않는다.

목적에 맞는 성과: 과업의 성과와 수행자의 학습 성과를 구분한다에 따라 산출물 완성과 사용자의 이해·판단 경험을 따로 본다. 설명·평가·성찰·멘토링은 현재 요청에 포함된 목적에 맞춰 구성한다.

확인의 범위: 문법·등록·링크·호출 경로 확인과 실제 작업에서의 유용성을 구분한다. 파일 길이·개수·문체·등록 성공만으로 품질 향상이나 매 턴 절감량을 주장하지 않는다. 아직 사용하지 않은 변경은 실사용 미확인으로 남긴다. 이번 개인 운영 개편은 별도 비교 실행을 만들지 않고 실제 요청된 작업에서 순차적으로 확인한다.

반복 누락이 관찰되면 원천 부재·탐색 실패·지침 충돌·실행 실패 중 원인을 확인해 해당 부분을 고친다. 원인을 확인하지 않은 사례를 전역 규칙이나 모든 작업의 고정 점검표로 늘리지 않는다.

연결된 도구와 작업 절차를 작성할 때

계획·승인·위임·리뷰·인수는 현재 앱의 워크플로가, 전문 작업법은 담당 역할이, 공유 절차는 공통 스킬이 소유한다. 개인 학습·응시·지식 정리는 해당 프로젝트·Vault 계약을 따른다. 문서는 이 소유자의 내용을 다시 쓰지 않고, 그 문서가 바꿀 판단과 필요한 원천만 연결한다. 계획 기록은 사용자 요청이나 프로젝트 요구가 있을 때 만든다. 이미 승인된 계획 기록이 있으면 저장 위치·저장 commit·plan_version을 구분해 이어서 쓴다. 현재 소유권은 위 「내용의 위치」를, Mixdog 중심 전환의 이전 근거는 Mixdog 중심 운영과 CLI 전역 지침 비우기 - Mixdog 대화를 따른다.

2026-09-30부터 2026-10-10 전환 전까지는 설치된 agent-operations 실행판과 원격 본문 [비공개 문서]이 이 역할을 맡았고, 승인 계획을 프로젝트 또는 개인 Vault 기록에 저장하도록 요구했다. 이 스킬은 현재 쓰지 않으며 해당 문서와 요구는 당시 운영 정책의 이력으로 읽는다. 그보다 앞선 이관은 [비공개 문서], 2026-09-30 전달 정책과 당시 앱별 적용 상태는 Skill 중심 실행과 Vault 선택 조회 결정 - Codex 대화에 남아 있다.

Paseo를 사용하던 시기의 Paseo 공식 가이드 - 설정과 작업 조율은 제공자·프로필·작업 공간·추가 프롬프트의 역할과 설정 저장·세션 적용의 차이를 보여준다. 다른 도구에서도 공식 기능, 특정 설치본에서 관찰한 동작, 개인 운영에서 채택할 절차를 구분해 지침의 위치와 내용을 정한다. Paseo 경로를 현재 운영 경로로 읽지 않는다.

당시의 Paseo 위임·교차 리뷰·스킬 운영 - 체험과 정정은 등록된 스킬을 자연어로 발견하는 일, 메인이 작업자에게 필요한 스킬을 명시하는 일, 본문을 읽고 결과에 적용하는 일이 다른 확인 대상임을 보여준다. 제공자별 목록 차이와 메인 자신이 쓸 스킬을 사용자가 알아야 하는 부담은 후속 판단으로 남아 있으며, 자동 호출 확대나 일괄 동기화를 채택한 것으로 읽지 않는다. 명시적 위임의 실제 입력은 해당 작업의 위임 brief가 소유한다.

규칙의 전달과 실행 검사를 검토할 때

하네스 설계의 외부 원천과 2026-11 반영

2026-11-02 검토에서 기존 WORKFLOW에 둘 곳이 없던 빈틈 네 개를 찾았다. 저장소 조회를 읽기 전용 검색에 맡기는 규칙과 여러 세션 작업의 진행 파일은 WORKFLOW 문구에 두었다. 병렬 실행 절제는 위임 방식 문구에 두었다. 모델 준수에 기대면 안 되는 규칙은 hook 규칙으로 시험했으나 정상 조회까지 매번 확인을 요구해 같은 날 지웠다. 에이전트 정의는 WORKFLOW와 겹치는 문장을 덜고 역할별 판단을 하나씩 더했다. 경위와 미확인 범위는 하네스 원천 재검토와 Mixdog 지침 반영 - Mixdog 대화에 있다.

플랫폼별 작성·등록

공통 기준은 모델에 독립적으로 유지하고, 앱별 파일 형식·호출 정책·실제 설정은 작성 시점의 공식 원천과 설치본에서 확인한다. 한 플랫폼의 frontmatter나 설정을 다른 앱에 그대로 적용하지 않는다.

  • Mixdog: 설치된 writing-for-agents의 플랫폼 형식 항목과 실제 설치본 C:/Users/aica_/.mixdog/data/skills/에서 확인한다.
  • Codex 공식 스킬 문서
  • Claude Code 공식 스킬 문서
  • Codex 설치본의 skill-creator: 앞으로 Codex 스킬 작성을 명시적으로 요청받은 경우에만 그 세션이 제공한 경로에서 읽으며 일반 작성 기준과 플랫폼 필수 형식을 구분한다.

Codex 공식 문서와 설치된 skill-creator는 2026-09-20 재확인했다. Claude 공식 문서의 기존 확인일은 2026-09-06이다. 두 앱의 스킬을 다시 작성·등록할 때는 그 시점의 공식 문서를 재확인한다. 이름·설명과 본문은 다른 시점에 로드되므로 전체 파일 크기를 상시 입력량으로 계산하지 않는다.

2026-09-20 개편은 당시 공통 기준을 Codex에 먼저 적용한 선택이다. 2026-09-30 전환도 Codex부터 수행했고, Claude Code 적용은 Skill 실행판의 Claude Code 적용 - Claude 대화에 남았으며 Antigravity·Paseo 등 다른 앱의 적용은 대기 상태였다. 2026-10-10 사용자는 Mixdog과 웹 ChatGPT를 선택하고 Codex·Claude·Antigravity 앱과 CLI를 쓰지 않기로 했다. 그래서 이 대기 항목은 현재 적용 과제가 아니다. 세 앱의 전역 지침 파일은 보존한 채 내용만 비웠고, 앱·스킬·인증·설정은 제거하거나 비활성화하지 않았다. 쓰지 않기로 한 것과 설정을 끈 것은 다른 상태다. 로컬 지침이 웹 ChatGPT에 전달·적용되는지는 확인하지 않았고, 파일 저장만으로 실제 세션에서의 효과가 확인되지도 않는다. 근거와 범위는 Mixdog 중심 운영과 CLI 전역 지침 비우기 - Mixdog 대화에서 확인한다. 한 앱에서 확인한 결과를 다른 앱의 검증 결과로 보고하지 않는다.

검토 원천

  • 현재 Mixdog 설치본: C:/Users/aica_/.mixdog/data/skills/writing-for-agents/SKILL.md와 같은 폴더의 SKILL-MECHANICS.md·UPSTREAM.md·LICENSE.
  • 2026-09-06 확인한 Codex 로컬 스킬과 호출 방식 참고. 2026-09-06 확인 당시 로컬 파일은 정비본이었으며 원래 내용은 변경 전 사본에서 확인한다.
  • Claude 원본은 비활성 보관 위치 C:/Users/aica_/.claude/disabled-skills/writing-for-agents/SKILL.md에 보존한다.
  • 원본의 출처·라이선스는 UPSTREAM·LICENSE에 보존한다. 원본 전체의 번역·복제 대신 현재 작업의 선택 기준을 다시 쓴다.
  • 외장뇌 운영

보안·문서 그림 스킬 적용

2026-10-07 Codex에 적용한 이력이다. 당시 승인 범위와 검증·적용 상태는 [비공개 문서]에서 확인한다. iron-laws CLI 재사용과 Codex용 AI 보안 평가·문서 그림 실행판을 다뤘으며, Claude 원본이나 전역 실행 정책 변경은 포함하지 않았다. 이 기록은 현재의 작업이나 담당을 정하지 않는다.

백링크

그래프 뷰

이 문서로 이어지는 주제