hustyladislav/에이전트용-문서-작성

에이전트가 사용하는 모든 문서(스킬, AGENTS.md / CLAUDE.md, 포인터가 가리키는 문서)를 작성하기 위한 참고 자료입니다. 문서의 포장 방식은 다를 수 있지만, 작성법은 동일합니다. 즉, 에이전트는 매 실행마다 동일한 프로세스를 따르기 때문에 동일한 레버(lever)를 사용하여 각 문서를 예측 가능하게 만들 수 있습니다.

작성 중인 문서가 스킬인 경우, 머리말(frontmatter), 호출 선택, 라우터 스킬에 대한 내용은 SKILL-MECHANICS.md를 읽어보세요.

컨텍스트 포인터

컨텍스트 포인터는 에이전트의 컨텍스트 내에 유지되며, 컨텍스트 외부 자료의 이름과 해당 자료에 도달하기 위한 조건을 인코딩하는 참조입니다. 스킬의 description이 그 예이며, AGENTS.md의 한 줄이 문서를 지칭하는 것도 동일한 객체입니다. 포인터의 *표현(wording)*이 대상(target)보다 더 중요하게, 에이전트가 해당 자료에 도달하는 시점과 신뢰성을 결정합니다. 강력한 대상이지만 표현이 약한 포인터는 변동성 버그(variance bug)를 유발합니다. 따라서 먼저 표현을 다듬고, 그래도 안 되면 자료를 인라인으로 포함시키는 것이 좋습니다.

포인터는 두 가지 작업을 수행합니다. 자료가 무엇인지 명시하고, 해당 자료에 도달하도록 트리거해야 하는 **분기(branches)**를 나열합니다. (분기란 문서가 처리하는 고유한 사례를 말하며, 실행 경로에 따라 다른 분기를 거치게 됩니다.) 항상 로드되는 포인터의 모든 단어는 매 턴마다 비용이 발생하므로, 본문보다 더 엄격하게 가지치기해야 합니다.

• 첫 단어를 전면에 배치하세요. 포인터는 트리거링 작업이 수행되는 곳입니다.
• 분기당 하나의 트리거. 하나의 분기를 다른 이름으로 부르는 동의어는 하나의 분기를 두 번 작성한 것과 같습니다. 이를 통합하고 진정으로 구별되는 분기만 유지하세요.
• 본문이 이미 전달하는 정체성은 제거하세요.

두 가지 부하

추가하는 모든 문서와 포인터는 다음 두 가지 예산 중 하나를 소비합니다.

• 컨텍스트 부하는 항상 로드되는 자료가 에이전트의 창(window)에서 차지하는 비용입니다. AGENTS.md의 한 줄, 스킬 description 등 매 턴마다 컨텍스트에 존재하며 토큰과 주의력을 소비합니다.
• 인지 부하는 인간이 부담하는 비용입니다. 즉, 어떤 문서가 존재하는지, 그리고 각각을 언제 참조해야 하는지에 대한 인간의 부담입니다. 인간이 인덱스 역할을 합니다. 최소화해야 할 비용이 아닙니다. 이는 인간의 판단력(agency)에 대한 대가이므로, 인간의 판단이 중요한 곳에서는 지출하고, 그렇지 않은 곳에서는 제거하세요.

포인터를 통해서만 도달할 수 있는 자료는 포인터 자체의 한 줄 비용만으로 컨텍스트 부하를 피할 수 있습니다. 포인터가 전혀 없는 자료는 전적으로 인지 부하에 의존합니다.

정보 계층 구조

문서는 두 가지 콘텐츠 유형으로 구성됩니다. 단계(steps)(에이전트가 수행하는 순서화된 작업)와 참조(reference)(요청 시 참조하는 정의, 규칙, 사실)입니다. 이 둘은 자유롭게 혼합됩니다. 예를 들어 모든 단계로만 구성된 레시피, 모든 참조로 구성된 검토 규칙이나 이 스킬, 또는 둘 다를 포함할 수 있습니다. 핵심 결정은 각 정보 조각을 정보 계층 구조 중 어디에 배치할지입니다. 이는 에이전트가 해당 자료를 얼마나 즉시 필요로 하는지에 따라 순위가 매겨진 사다리입니다.

1. 인파일 단계(In-file step) 는 1차 계층입니다. 에이전트가 수행하는 순서대로의 작업입니다.
2. 인파일 참조(In-file reference) 는 요청 시 참조됩니다. 종종 정당하게 평평한 피어 집합(예: 검토의 모든 규칙이 하나의 단계에 있는 경우)이며, 이는 잘못된 것이 아니라 훌륭한 구성입니다.
3. 공개된 참조(Disclosed reference) 는 별도의 파일로 밀어내어 컨텍스트 포인터를 통해 도달하며, 포인터가 실행될 때만 로드됩니다. 동일한 폴더 내의 형제 파일부터 완전히 외부 참조(어디든 위치할 수 있고 모든 문서가 가리킬 수 있음)까지 다양합니다.

너무 적게 밀어내면 상위 계층이 비대해지고, 너무 많이 밀어내면 에이전트가 실제로 필요로 하는 자료를 숨기게 됩니다. 이러한 긴장감이 바로 의사 결정의 전부입니다.

점진적 공개(Progressive disclosure) 는 사다리 아래로(주 파일 밖으로, 포인터 뒤로) 이동하여 상위 계층을 읽기 쉽게 유지하는 방법입니다. 주로 토큰 최적화가 아닌 계층 구조를 보호하는 방법입니다. 분기 처리는 가장 명확한 공개 테스트입니다. 모든 분기가 필요로 하는 것은 인라인으로 유지하고, 일부 분기만 도달하는 것만 포인터 뒤로 밀어내세요. 문서에 단계가 있을 때, 공개되어야 할 인파일 참조는 단계를 묻어버려 단계에 주의를 기울이는 것을 동전 던지기처럼 만듭니다. 이는 가독성 문제일 뿐만 아니라 변동성 레버(variance lever)이기도 합니다.

공동 배치(Co-location) 는 파일 내 동반자 개념입니다. 사다리가 정보 조각이 얼마나 아래에 위치할지 결정한다면, 공동 배치는 그 위치에 무엇을 함께 배치할지 결정합니다. 개념의 정의, 규칙, 주의사항을 여러 곳에 흩어 놓지 말고 하나의 제목 아래에 유지하여, 한 부분을 읽을 때 관련 내용이 함께 따라오도록 하세요. 테스트는 다음과 같습니다. 문서는 에이전트를 위해 작성된 문서처럼 읽혀야 합니다. 그룹화된 자료는 그렇게 읽히지만, 흩어진 자료는 그렇지 않습니다. (중복과는 다릅니다. 중복은 하나의 의미를 두 곳에서 반복하는 것이고, 흩어짐은 하나의 의미를 여러 곳으로 조각내는 것입니다.)

비대화(Sprawl) 는 여기서 발생하는 실패 모드입니다. 모든 줄이 살아있고 고유하더라도 문서가 단순히 너무 긴 상태를 말합니다. 과도한 정보에 주의력이 분산되고, 모든 추가 줄은 관련성을 유지해야 하는 또 하나의 부담이 됩니다. 해결책은 사다리입니다. 참조를 포인터 뒤로 공개하고, 분기나 시퀀스별로 분할하여 각 경로가 필요한 것만 전달하도록 하세요.

단계와 완료 기준

모든 단계는 완료 기준으로 끝납니다. 이는 에이전트에게 작업이 완료되었음을 알리는 조건입니다. 다음 두 가지 속성이 이를 레버로 만듭니다.

• 명확성: 에이전트가 완료와 미완료를 구분할 수 있습니까? 모호한 경계(예: "이해 도달")는 조기 완료를 유발합니다. 즉, 단계가 진정으로 완료되기 전에 끝내고, 주의력이 완료하는 것 자체로 쏠리는 현상입니다. 아직 눈에 보이는 이후 단계(사후 완료 단계)가 당기는 힘을 제공하고, 기준의 명확성이 저항이 됩니다. 다음 순서로 방어하세요. 먼저 경계를 명확히 하세요(국소적이고 저렴합니다). 그것이 본질적으로 모호하고 그리고 서두르는 현상이 관찰되는 경우에만, 시퀀스를 분할하여 이후 단계를 숨기세요. 숨김은 실제 컨텍스트 경계(핸드오프 또는 하위 에이전트 디스패치)를 통해서만 작동합니다. 인라인 호출은 이후 단계를 컨텍스트에 남겨두고 아무것도 지우지 않습니다.
• 요구 수준: 얼마나 많은 것을 요구하는지. "수정된 모든 모델이 설명됨"은 "변경 목록 생성"보다 훨씬 철저한 작업을 강제합니다. 요구 수준은 조사 작업을 결정합니다. 이는 작업 내에서 에이전트가 수행하는 조사 작업으로, 별도의 단계로 작성되지 않고 표현에 잠재되어 있습니다. 또한 단계에 국한되지 않습니다. "모든 규칙 적용됨"은 평평한 참조 본문에 바인딩되는 것처럼 "모든 단계 완료됨"은 시퀀스에 바인딩되며, 이것이 모든 참조 문서가 여전히 완전성 기준을 갖는 방식입니다.

가장 강력한 기준은 확인 가능하고(exhaustive) 동시에 완전한(comprehensive) 것입니다.

분할 시점

하나의 문서를 두 개로 분할하는 것은 두 가지 부하 중 하나를 소비하므로, 분할이 그만한 가치가 있을 때만 분할하세요.

• 시퀀스별 분할: 사후 완료 단계가 에이전트로 하여금 현재 단계를 서두르게 만드는 경우, 단계 시퀀스를 분할하세요. 이후 단계를 시야에서 숨기면 현재 작업에 더 많은 조사 작업을 수행하게 됩니다. 반대의 경우도 조심하세요. 시퀀스를 병합하면 각 단계의 이후 단계가 뒤따르는 내용에 노출되어 조기 완료를 유발할 수 있습니다.
• 호출별 분할(스킬 특화): SKILL-MECHANICS.md를 참조하세요.

선행 단어

선행 단어는 모델의 사전 훈련에 이미 존재하는 간결한 개념으로, 에이전트가 문서를 실행하는 동안 함께 생각하는 도구입니다(예: lesson, fog of war, tracer bullets). 문장이 아닌 토큰으로 반복됨으로써 분산된 정의를 축적하고, 모델이 이미 보유한 사전 지식을 활용하여 가장 적은 토큰으로 전체 행동 영역을 고정합니다. 나만의 단어를 만드는 것도 명확히 정의하면 작동하지만, 인공적인 단어는 사전 지식을 활용하지 못합니다. 사전 훈련된 단어가 무료로 제공하는 것을 정의 토큰으로 지불해야 합니다. 따라서 먼저 기존 단어를 찾아 사용하세요.

선행 단어는 두 가지를 고정합니다. 본문에서는 실행을 고정합니다. 에이전트는 단어가 나타날 때마다 동일한 행동에 도달하고, 평평한 참조 내에서는 찾아야 할 사물의 클래스에 주의를 집중시킵니다. 포인터에서는 호출을 고정합니다. 동일한 단어가 프롬프트, 문서, 코드베이스에 존재할 때, 에이전트는 그 공유된 언어를 자료와 연결하고 더 안정적으로 도달합니다.

선행 단어로 리팩터링할 기회를 찾으세요. 세 곳에 풀어쓴 세 쌍, 하나의 아이디어를 가리키기 위해 한 문장을 사용하는 포인터. 각각은 하나의 토큰으로 축소되기를 기다리는 구절입니다.

• "빠르고, 결정론적이며, 오버헤드가 낮은" → tight(예: tight 루프).
• "당신이 믿는 루프" → red, 모호한 게이트를 이진 관찰 가능 상태로 전환합니다(루프는 버그에서 red가 되거나 그렇지 않습니다).

두 가지 이점이 있습니다. 더 적은 토큰과 에이전트가 사고를 걸 수 있는 더 날카로운 갈고리입니다. 모든 문서가 선행 단어로 대체될 수 있는 반복적인 설명을 담고 있다고 가정하고 찾아내세요.

부정(Negation) 은 이 레버의 실패 모드입니다. 금지를 통해 조종하면 금지된 행동을 컨텍스트로 끌어들여 더 접근 가능하게 만들 뿐입니다. 코끼리를 생각하지 마세요라고 하면 코끼리만 떠오릅니다. 부정은 약한 수정자일 뿐, 강하게 활성화된 개념이 이를 압도합니다. 따라서 금지는 그 행동을 하라는 명령으로 반쯤 읽힙니다. 긍정을 지시하세요. 즉, 금지된 행동은 언급하지 말고 목표 행동을 명시하세요(예: "한 줄 주석을 작성하세요"). 금지는 긍정적으로 표현할 수 없는 단단한 가드레일로서만 자리를 얻습니다. 그런 경우에도 주의가 해야 할 일에 머물도록 긍정적인 목표와 함께 짝을 이루세요.

가지치기

• 각 의미는 단일 진실 공급원(single source of truth) 에 유지하세요. 하나의 권위 있는 장소. 그래야 행동 변경이 한 곳만 수정하면 됩니다. 중복은 유지보수 비용과 토큰을 소비하고, 계층 구조에서 의미의 중요성을 실제 순위보다 부풀립니다. (의도적인 반복인 선행 단어와 우발적인 반대 관계입니다. 선행 단어는 의미가 아닌 토큰을 의도적으로 반복합니다.)
• 환경(Environment) 도 진실 공급원입니다(package.json 스크립트, 설정 파일, 디렉터리 구조, --help 출력 등). 이를 문서가 다시 진술하는 것은 캐시입니다. 즉, 조회의 복사본으로, 조회 비용이 비쌀 때만 부하를 정당화합니다. 에이전트가 찾아서 알 수 없는 것을 캐시하세요. 즉, 문서화되지 않은 관례, 선택背后的 이유, 어떤 설정도 밝히지 않는 함정(potential issue) 등입니다. 파일 하나, 명령어 하나를 찾는 것은 환경에 맡겨 두어, 환경이 오래될 수 없도록 하세요.
• 모든 줄의 관련성을 확인하세요. 여전히 문서가 하는 일과 관련이 있습니까? 관련성을 잃는 경우는 작업과 전혀 관련이 없거나(단순한 설명, 공개되어야 할 분기), 설명하는 행동이나 세상이 변함에 따라 쓸모없어지는 경우입니다. 짧은 문서일수록 관련성을 유지하기 쉽습니다. 가지치기 규율 없이는 기본 운명은 침전물(sediment) 입니다. 추가하는 것은 안전하게 느껴지고 제거하는 것은 위험하게 느껴져서 쌓이는 낡은 층입니다. 결국 살아있는 부분을 찾기 위해 그것들을 뚫고 내려가야 할 때가 옵니다.
• 문장 단위로 무효 명령(no-op)을 찾으세요. 모델이 기본적으로 이미 따르는 명령은 아무 말도 하지 않고 부하만 소비합니다. 테스트(기본값과 비교하여 행동을 변화시키는가?)는 독자(reader)가 아닌 모델(model)에 상대적입니다. 두 사람이 무효 명령에 대해 동의하지 않는다면, 이는 기본값에 대한 의견 차이이며, 논쟁이 아닌 문서를 실행하여 해결해야 합니다. 문장이 실패하면, 단어를 다듬는 대신 문장 전체를 삭제하세요. 이 테스트는 선행 단어의 등급도 매깁니다. 기본값을 이기기에는 너무 약한 단어(에이전트가 이미 대충 철저할 때 "철저히 하라")는 무효 명령이며, 해결책은 더 강력한 단어(예: "끈질기게")를 사용하는 것이지 다른 기술을 사용하는 것이 아닙니다.