agent conventions

Navigation

Progressive loading design

Goal: React, TypeScript, CSS 작업에서 필요한 규칙을 빠짐없이 적용하면서도, 매번 세 skill의 전체 handbook을 context에 넣는 비용을 없앤다.

배경

현재 structured skill은 작은 rules/*.md를 source of truth로 관리하지만, 실제 activation guide는 먼저 generated AGENTS.md 전체를 읽고 관련 rule 원문도 다시 읽도록 안내한다. 고정한 tiktoken==0.11.0, o200k_base 실측에서 React + TypeScript + CSS entrypoint와 compiled guide 1회 로드는 38,102 token이고, 선택한 rule을 다시 읽는 비용까지 중복된다.

문제는 skill을 세 개로 나눈 구조가 아니라 loading contract다. 프로젝트 AGENTS.md에 모든 규칙을 합치면 activation은 단순해지지만, 모든 작업에 모든 규칙이 상시 주입되고 규칙 정본도 프로젝트별로 복제된다. 따라서 세 domain skill은 유지하되, 각 skill을 작은 router + compact rule index + generated selected contract + deterministic full-rule expansion 구조로 바꾼다.

설계 원칙

  1. rules/*.md는 계속 유일한 규칙 정본이다.
  2. SKILL.md는 규칙집이 아니라 scope를 분류하고 필요한 원문을 선택하는 router다.
  3. agent는 규칙 제목만 추측하지 않고 generated index의 적용 조건을 전부 훑는다.
  4. 선택된 규칙은 source에서 자동 생성한 normative contract를 읽고, CRITICAL 또는 exact 판단 근거가 더 필요한 rule은 full source까지 읽는다. 별도 수동 요약 정본은 만들지 않는다.
  5. 선택하지 않은 규칙도 index 수준에서 applicability를 판정했다는 coverage evidence를 남긴다.
  6. scope가 바뀌면 selection을 다시 수행한다.
  7. 완료 전 semantic audit에서 누락, 위반, 증거 부족을 차단한다.
  8. compiled AGENTS.md는 삭제하지 않되 기본 activation 경로에서 제외한다.

범위

이번 변경은 다음을 포함한다.

범위 밖

산출물 구조

세 progressive skill은 아래 구조를 가진다.

skill/react/
  SKILL.md           # 작고 고정된 activation router
  RULES_INDEX.md     # generated compact applicability index
  contracts/         # generated selected-rule normative contract
    *.md
  AGENTS.md          # generated full local handbook, opt-in
  rules/
    _sections.md
    _template.md
    *.md             # source of truth

rules/*.md

progressive rule frontmatter는 applicability와 세 종류의 routing edge를 명시한다.

---
title: Prefer Named Handlers Over Inline Callbacks
impact: HIGH
impactDescription: keeps JSX readable and event flow auditable
appliesWhen: TSX event prop에 분기, 비동기 작업, 상태 변경 또는 두 단계 이상의 동작이 들어간다.
requiresSelected: docs-require-jsdoc-on-key-declarations, events-name-and-curry-handlers
reviewWith: events-keep-handler-flow-inline, events-run-user-actions-in-handlers-not-effects
tags: composition, jsx, handlers
---

appliesWhen은 다음 계약을 따른다.

rule body의 heading/Impact 뒤 규범과 예외는 첫 anchored Incorrect marker 앞에 완결한다. 첫 Incorrect 뒤에는 Incorrect/Correct label, fenced code, 빈 줄만 허용한다. build/validate가 fence 밖 marker와 후반 prose를 검사해 generated contract가 규범을 조용히 누락하지 못하게 한다.

optional routing scalar는 쉼표로 구분한 stable rule id를 사용하고 다른 skill rule은 <skill>/<rule-id>로 적는다.

Unknown contract는 applicability 해소에만 사용하며 Unknown을 Selected/N/A로 먼저 확정한다. N/A source의 requiresSelected는 전이하지 않는다. final Selected contract의 mandatory target과 필수 변경만 scope evidence에 합치고, 예시, 선택적 대안, 미해소 Unknown은 제외한다. 새 surface, companion, Selected가 생기면 contract 로드와 모든 activated index/reviewWith 판정을 activation, partition, scope evidence가 더 이상 바뀌지 않는 고정점까지 반복한다. 같은 target을 requiresSelected와 reviewWith에 중복 선언하지 않는다.

이 routing schema는 progressive React, TypeScript, CSS에 적용한다. 다른 structured skill은 migration 전까지 기존 schema로 계속 build할 수 있어야 한다.

RULES_INDEX.md

build가 _sections.md 순서와 rule 정렬 순서를 이용해 생성한다. token 측정에서 title/impact/tag 중복이 index 비용을 키운 것이 확인됐으므로 각 rule entry에는 selection에 필요한 다음 정보만 둔다.

문서 header에는 skill identity와 canonical routing/source SHA-256 digest만 생성한다. local rule 수와 section heading은 전체 entry scan에서 얻는 정보라 중복 렌더하지 않는다. 각 entry에는 현재 index 안에서만 쓰는 compact ordinal을 붙인다. requiresSelected 목록은 초기 token 비용을 늘리지 않도록 index에서 제외하고 selected/unknown contract에서만 읽는다. digest에는 requiresSelected, requiredOnCompletion, reviewWith, full source body hash, rule-index renderer version, contract renderer version이 모두 들어가므로 규범, 예시, renderer가 바뀌면 기존 receipt도 stale이다.

예시:

- R15 | composition-named-handlers-over-inline | TSX event prop에 분기, 비동기 작업, 상태 변경 또는 두 단계 이상의 동작이 들어간다. | reviewWith: events-keep-handler-flow-inline, events-run-user-actions-in-handlers-not-effects

stable identity는 filename 기반 rule id이고 ordinal은 exact set을 짧게 기록하기 위한 index-local 표현이다. rule 순서나 source body가 달라지면 digest도 달라지므로 서로 다른 index version의 ordinal을 섞을 수 없다. index에는 title/impact/tag, rule 설명, Incorrect/Correct 예시, full body를 넣지 않는다.

contracts/*.md

build가 source rules/*.md에서 자동 생성하고 직접 편집을 금지한다. contract는 requiresSelected와 completion metadata를 포함한다. non-CRITICAL contract는 heading, Impact, 첫 Incorrect 전 normative prose를 보존하고 예시는 full rule 링크로 미룬다. CRITICAL contract는 routing metadata와 짧은 redirect만 생성해 full rule을 반드시 읽게 한다. non-CRITICAL도 exact syntax, 예외 판단, unresolved Unknown, audit PASS evidence 부족이면 full rule로 확장하고 receipt에 Expanded: ordinal + ID: reason을 기록한다.

AGENTS.md

현재와 같이 local full handbook을 생성한다. 다음 경우에만 명시적으로 읽는다.

progressive full handbook은 각 local rule heading 바로 아래에 source frontmatter의 escaped Applies when, Requires selected, Required on completion, Review with를 생성한다. 따라서 전체 원문을 opt-in한 agent도 compact 경로와 같은 fixed-point selection을 수행할 수 있어야 한다.

일반적인 코드 수정과 완료 audit에서는 기본으로 읽지 않는다.

Activation Router Contract

각 SKILL.md는 아래 순서를 짧고 명시적으로 강제한다.

1. Scope snapshot

편집 전에 요청, 대상 파일, diff를 기준으로 domain을 활성화한다.

변경 surface활성화할 skill
.tsx, React component/hook/state/event/JSXReact + TypeScript
.ts, type/schema/helper/API/configTypeScript
.css, stylesheet ownership/selector/tokenCSS
TSX className, CSS import, styled surface를 함께 변경React + TypeScript + CSS

파일 확장자는 최소 신호다. 예를 들어 .tsx에서 class contract를 바꾸면 CSS도 활성화하고, .ts만 수정해도 React hook ownership을 바꾸면 React도 활성화한다.

2. Index scan and rule selection

활성화된 각 skill의 RULES_INDEX.md를 처음부터 끝까지 읽는다. 요청 및 변경 증거가 appliesWhen과 일치하면 해당 rule을 Selected, 명확히 아니면 근거 있는 N/A, 애매하면 Unknown으로 분류한다.

3. Rule Selection Receipt

코드를 바꾸기 전에 짧은 receipt를 유지한다.

Activated: react, typescript, css
Indexes:
- react@sha256:<digest>
- typescript@sha256:<digest>
- css@sha256:<digest>
Selected:
- react: R15,R25,R35,R42 (named handler, handler naming, functional update, React JSDoc)
- typescript: T03,T18,T19,T21,T22 (naming, JSDoc closure, completion gate)
- css: C07,C21 (clsx, completion gate)
Not applicable:
- react: R01-R14,R16-R24,R26-R34,R36-R41
- typescript: T01-T02,T04-T17,T20
- css: C01-C06,C08-C20
Excluded groups:
- react strategy: shared component API를 변경하지 않음
- css selector/values: selector와 token 값을 변경하지 않음
Unknown: none
Expanded: none

N/A rule은 ordinal range로 exact set을 남기고, section 또는 동일 조건의 rule group별 배제 근거를 덧붙인다. index의 모든 ordinal은 selected, not applicable, unknown 중 정확히 하나에 있어야 하며 중복과 누락이 없어야 한다. digest가 현재 generated index와 다르면 receipt를 재사용하지 않고 selection을 다시 수행한다.

receipt는 작업 중 audit packet으로 전달되는 ephemeral artifact이며 consuming product repository에 새 파일을 만들 필요는 없다. behavioral evaluation에서만 재현을 위해 JSON snapshot으로 보존한다.

4. Read selected contracts and deterministic full rules

receipt의 selected/unknown stable ID와 같은 이름인 contracts/<stable-id>.md를 모두 읽는다. CRITICAL contract는 full rule을 반드시 읽는다. non-CRITICAL은 exact syntax, 예외 판단, contract와 코드만으로 해소되지 않는 Unknown, audit PASS evidence 부족일 때만 full rule로 확장한다. Unknown을 먼저 Selected/N/A로 비운 뒤 final Selected의 requiresSelected closure를 전이한다. N/A source의 mandatory target은 전이하지 않는다.

5. Scope drift

새 파일, 새 abstraction, 새 CSS selector, 새 API/type boundary처럼 작업 surface가 넓어지면 index scan과 receipt를 갱신하고 추가 rule을 읽는다. 최초 selection을 끝까지 고정하지 않는다.

Companion Skill Contract

예시:

{
  "companions": [
    {"skill": "typescript", "mode": "required"},
    {"skill": "css", "mode": "conditional", "appliesWhen": "class contract, stylesheet 또는 styling surface를 변경한다."}
  ]
}

React는 required TypeScript와 conditional CSS를 선언한다. convention-audit은 React, TypeScript, CSS를 모두 conditional로 선언하고 실제 changed surface로 활성화한다. 기존 non-progressive skill의 extends는 호환성을 위해 유지한다. build와 validate는 한 skill 안에서 extends와 companions를 동시에 선언하지 못하게 하며, local index에 companion rule을 flatten하지 않고 companion index link와 activation mode만 생성한다.

Convention Audit Contract

convention-audit은 더 이상 React/CSS/TypeScript full AGENTS.md 세 개를 기본으로 읽지 않는다. 다음 순서로 동작한다.

  1. changed files, diff, owner boundaries, runtime/visual evidence로 audit packet을 만든다.
  2. 실제 변경 surface에 해당하는 companion skill을 활성화한다.
  3. 각 activated RULES_INDEX.md 전체를 applicability 수준으로 scan한다.
  4. selected 및 ambiguous stable ID와 같은 이름의 contract를 읽고 CRITICAL/근거가 필요한 full rule만 확장한다.
  5. selected rule별 evidence와 verdict를 기록한다.
  6. coverage count와 excluded-group reason을 검증한다.
  7. FAIL > 0 또는 UNKNOWN > 0이면 구현 수정 또는 evidence 보강 후 다시 audit한다.

auditor는 구현자가 남긴 selection receipt를 그대로 신뢰하지 않는다. diff와 audit packet에서 applicability scan을 독립적으로 다시 수행하고 두 selection을 비교한다. 구현 receipt에서 applicable rule이 빠졌으면 그 rule의 본문 위반 여부와 관계없이 selection coverage FAIL로 판정한다.

두 receipt는 같은 index digest의 exact ordinal partition으로 비교한다. group count만 같거나 배제 설명만 있는 receipt는 audit evidence로 인정하지 않는다.

최종 요약은 다음을 포함한다.

Activated indexes: react 42, typescript 22, css 21
Coverage: selected 9, not applicable 76, unknown 0
Verdicts: PASS 9, FAIL 0, UNKNOWN 0
Excluded groups: <compact reasons>
Reviewer: <independent reviewer or reported fallback>

lint, typecheck, build, browser 확인은 중요한 verification evidence지만 semantic convention verdict를 대신하지 않는다. 독립 reviewer를 사용할 수 있으면 receipt, diff, selected contract, Expanded full rule과 이유, 실행 증거를 넘긴다. 사용할 수 없으면 main-agent reviewer mode를 명시하고 같은 gate를 적용한다.

Project AGENTS.md Policy

consuming project는 규칙 본문을 복사하지 않고 아래와 같은 짧은 activation policy만 둔다. 복사 가능한 정본은 루트 AGENTS.frontend-conventions.md이며, 아래는 핵심 축약본이다.

## Frontend conventions

- React/TSX 변경 전 `convention-react`와 `convention-typescript`를 활성화한다.
- CSS, class contract, stylesheet 또는 styling surface 변경 시 `convention-css`도 활성화한다.
- 각 `SKILL.md`를 router로 사용하고, activated `RULES_INDEX.md`를 전부 scan한 뒤 선택한 `contracts/*.md`와 CRITICAL/근거가 필요한 `rules/*.md`만 읽는다.
- 일반 구현에서 compiled `AGENTS.md` 전체를 기본 로드하지 않는다.
- scope가 넓어지면 rule selection을 갱신한다.
- 완료 전 `convention-audit`을 수행하고 FAIL/UNKNOWN이 0이 될 때까지 수정한다.

프로젝트 고유 naming, 폴더 구조, 검증 명령은 이 policy 아래에 overlay로 둔다. 공통 React/TypeScript/CSS 규칙은 프로젝트마다 복제하지 않는다.

Build 및 Schema 변경

package 구현은 다음 계약을 지원한다.

progressive 여부는 코드에 skill 이름을 흩뿌리지 않고 metadata.json의 명시적 설정으로 선언한다. 예시:

{
  "progressiveDisclosure": true
}

이 설정이 없는 기존 structured skill은 appliesWhen 없이도 validate/build가 계속 통과한다. 설정된 skill은 RULES_INDEX.md가 필수 generated output이며 모든 local rule에 appliesWhen이 필요하다.

isBuildableSkill은 source인 metadata.json과 _sections.md만으로 판정한다. 아직 생성되지 않은 RULES_INDEX.md를 buildability 조건에 넣지 않는다. build는 index가 없는 clean fixture에서도 성공해야 한다. 기존 source validate → build 흐름을 깨뜨리지 않도록 stale 검출은 별도 generated-output check에서 source로 계산한 기대 문자열과 tracked output을 비교한다.

현재 frontmatter reader는 YAML parser가 아니라 한 줄 key: scalar parser다. 이번 schema에서도 배열이나 block scalar를 허용하지 않는다. 모든 non-empty frontmatter line은 알려진 key의 단일 scalar여야 하고, duplicate key, colon 없는 continuation, unknown key를 즉시 거부한다. 따라서 줄바꿈된 appliesWhen이 조용히 잘리는 false green을 막는다.

RED-GREEN 검증 전략

RED: 현재 구조의 실패를 먼저 고정

구현 전 자동화 테스트가 다음 이유로 실패해야 한다.

GREEN: 구조 테스트

Pressure scenarios

최소 다음 mixed scenario를 baseline과 candidate에 각각 두 번 적용한다.

  1. TSX inline callback을 named handler로 추출하고 derived/functional state update를 함께 수정
  2. pure TS helper/type/JSDoc boundary 수정
  3. 기존 CSS owner root 아래로 third-party selector를 제한하고 variable fallback 수정
  4. TSX className과 stylesheet를 함께 수정
  5. React query shaping 변경이지만 CSS/API schema는 변경하지 않음
  6. 구현 중 shared abstraction 또는 new selector가 추가되어 scope가 넓어짐
  7. 적용 여부가 애매한 HIGH rule이 있어 원문 확인이 필요한 경우
  8. lint/build는 통과하지만 semantic rule을 위반한 경우

각 scenario에는 exact expected selected/not-applicable rule id partition과 forbidden full-handbook load를 기록한다. candidate가 impact와 관계없이 expected applicable rule을 하나라도 선택하지 못하면 실패다.

기존 pressure 문서만으로는 positive routing coverage가 React 28/42, TypeScript 18/22, CSS 16/21 rule에 그친다. runtime에 로드되지 않는 routing-evals.json manifest를 각 progressive skill에 추가해 세 skill의 모든 rule id가 최소 한 번은 expectedSelected에 등장하도록 한다. fixture는 id, changed files, expectedSkills, exact expectedSelected, exact expectedNotApplicable, scopeDrift를 명시하고 두 exact set이 해당 fixture의 activated index를 완전히 partition해야 한다. 자동화 테스트는 manifest의 unknown/duplicate id, 존재하지 않는 stable-ID-matched contract, companion closure와 rule coverage 100%를 검사한다. all-rules selection은 exact-set precision과 token gate에서 실패한다.

behavioral pressure 평가는 네 arm으로 비교한다.

  1. no-skill baseline
  2. full-handbook oracle
  3. progressive candidate
  4. expected rule 하나를 receipt에서 제거한 mutation RED

candidate는 oracle보다 추가 convention FAIL/UNKNOWN을 만들면 실패다. mutation arm은 coverage mismatch 또는 UNKNOWN으로 반드시 완료를 차단해야 한다. 각 mixed scenario는 최소 두 번, CRITICAL scenario는 가능하면 세 번 실행한다. oracle fixture는 appliesWhen 작성자와 다른 reviewer가 full rule body를 기준으로 승인해 self-validating evaluation을 피한다.

package test는 schema, build determinism, manifest integrity만 자동 검증할 수 있다. 실제 agent가 index를 읽고 scope drift 뒤 재선택하는 행동은 별도 behavioral run이 필요하다. protocol v3 coordinator는 child dispatch 전에 exact UTF-8 prompt를 렌더하고 raw text, SHA-256, byte length, renderer version, repository HEAD, arm/scenario/trial, generated index digest를 저장한다. child에게 prompt를 되받아 적게 하지 않고 coordinator가 run envelope에 provenance를 주입한다. progressive/full-handbook run은 completion gate, conditional reviewWith outcome, final-Selected requiresSelected addition을 포함한 routing trace를 기록하며, delta가 없는 연속 두 pass와 final receipt가 정확히 같아야 완료할 수 있다. 각 run은 model/runtime/version, reasoning level, scorer/rubric version, declared loaded files, semantic verdict와 token evidence도 content/public/evaluations/ snapshot으로 남긴다. runtime이 file-read telemetry를 제공하지 않으면 declared loaded files임을 명시하며 관측하지 못한 사실을 자동 PASS로 표현하지 않는다.

Token 및 품질 합격선

최초 HEAD pilot 기준선은 React + TypeScript + CSS entrypoint와 full compiled guide를 한 번 로드한 38,102 o200k_base token이었다. mandatory routing과 completion gate를 반영한 현재 fixed context의 one-load 기준선은 46,732 token이다. 선택 rule의 중복 로딩과 독립 audit/reviewer 재로딩은 이 수치에 포함하지 않는다.

최초 index + selected full-rule 구현을 실제 8개 context에 대입한 pilot은 implementation median 13,380, max 19,723, one-load 절감 64.8837%, cumulative 절감 48.698%로 네 token gate를 모두 실패했다. 따라서 routing 조건을 약화하지 않고 index의 중복 title/impact/tag를 제거하고 generated contract + CRITICAL full-rule expansion을 추가했다. mandatory closure까지 포함한 현재 fixed context 재측정은 implementation median 9,377, max 11,832, one-load 절감 median 79.9345%, cumulative 절감 median 65.4441%로 네 gate를 통과했다. 이 측정은 tiktoken==0.11.0, o200k_base, contexts SHA-256 1a052d41f0f96d05b31b95923570fd7f9a56daacfa8e4ba25dcde5aa3aaaeed3에 묶이며, 최종 evidence에는 committed HEAD와 measured-file hash manifest도 함께 기록한다.

후보 구조의 목표는 다음과 같다.

위 10,000/12,000 기준은 구현 단계의 router + index + selected contract + required full-rule context다. 별도로 초기 selection, scope drift 재scan, convention audit, 독립 reviewer 전달 context를 모두 합친 end-to-end 누적 input을 같은 단계의 full-handbook workflow와 비교해 감소율 median 60% 이상이어야 한다.

토큰은 동일한 o200k_base tokenizer와 동일 파일 범위로 다시 측정한다. exact tokenizer 실행 환경을 repository에 고정할 수 없으면 재현 명령과 snapshot 결과를 문서화하고, 자동화 테스트에는 deterministic byte budget을 보조 guardrail로 둔다. full-handbook fallback이 발생하면 receipt와 snapshot에 이유를 적고 progressive token PASS에서 제외한다. token 감소만 통과하고 recall 또는 precision이 떨어지면 전체 변경은 실패로 본다.

호환성 및 Rollout

  1. React, TypeScript, CSS rule에 appliesWhen을 추가하고 metadata flag를 켠다.
  2. RED 테스트를 추가한 뒤 parser/validate/build를 구현한다.
  3. 세 index를 생성하고 completeness를 검증한다.
  4. 세 SKILL.md를 compact router로 바꾼다.
  5. convention-audit router와 pressure tests를 바꾼다.
  6. README, package README, 각 skill README와 template을 갱신한다.
  7. 전체 build/validate/test/typecheck를 실행한다.
  8. baseline/candidate pressure 및 token 측정을 수행한다.

구현은 schema/index/receipt 기반을 먼저 완성하고, TypeScript pilot으로 eval harness를 검증한 뒤 React/CSS와 companion closure, 마지막으로 independent convention audit를 연결한다. 각 phase는 같은 branch 안에서 다음 phase의 전제 조건으로 이어지며, pilot 결과만으로 전체 작업을 완료 처리하지 않는다.

기존 사용자가 AGENTS.md를 직접 링크한 경우 full handbook은 계속 동작한다. 다만 새 README는 일반 작업의 권장 경로를 SKILL.md → RULES_INDEX.md → selected contracts/*.md → CRITICAL/근거 기반 rules/*.md로 명확히 바꾼다.

위험과 대응

index가 지나치게 짧아 규칙을 놓침

appliesWhen을 단순 주제가 아니라 관찰 가능한 code/diff trigger로 작성하고, 애매하면 Unknown에 둔 뒤 contract와 필요 시 full rule 증거로 완료 전에 해소한다. pressure scenario에서 impact와 관계없이 applicable rule recall 100%를 요구한다.

index 자체가 또 다른 거대한 문서가 됨

entry schema와 160자 제한을 enforce하고 예시/설명을 넣지 않는다. token 및 byte budget을 회귀 검증한다.

초기 scope만 보고 후속 변경 규칙을 놓침

router와 audit 모두 scope drift 재선택을 필수 단계로 둔다.

N/A 판정을 너무 쉽게 만들어 coverage가 형식화됨

index digest가 붙은 exact ordinal partition, section/group 단위 exclusion reason, 독립 reviewer selection 비교를 요구한다. 적용 여부가 애매하면 UNKNOWN으로 두고 원문을 읽어 해소한다.

audit가 다시 모든 원문을 읽음

audit의 completeness는 index 전체 scan, digest가 붙은 exact partition, 독립 selection 비교로 확보하고, semantic guidance review는 selected/ambiguous contract와 required full rule에만 제한한다.

metadata migration이 다른 skill을 깨뜨림

progressiveDisclosure가 켜진 skill에만 새 필드를 강제하고, 다른 structured skill의 기존 build 계약을 보존한다.

완료 조건