agent conventions

AI agent와 개발하면서 반복해서 설명하던 코드 판단 기준을 규칙과 예제로 정리했습니다. React, TypeScript, CSS, Testing과 Figma의 규칙에서 agent용 skill과 사람이 읽는 문서를 함께 생성하는 도구와 작성 체계를 만들었습니다.

핵심 기여

과제	구현한 것	남긴 구조
변경에 필요한 규칙을 찾는 과정	skill, 전체 index와 선택한 규칙의 contract 분리	적용 조건과 중요도에 따른 읽기 경로
규칙과 문서의 내용 차이	한 원본에서 agent용 산출물과 사이트 생성	stable ID로 연결되는 규칙, 예제와 참조
규칙을 검토할 기준	메타데이터와 참조, 올바른 예제의 검사	생성물 검사와 시나리오별 분할 검증

개요

항목	내용
기간	Git 기록 2026.03 ~ 현재
역할	주요 규칙과 예제, 생성 도구 작성. 다른 작성자의 기여가 있는 공개 저장소입니다
기술	TypeScript, Node.js, Markdown, Biome, Stylelint, React, Vitest, Playwright, for-humanity
링크	GitHub 저장소, 문서 사이트

문제와 해결

작업 범위에서 필요한 규칙까지 이어지는 읽기 경로 만들기

문제. 긴 규칙 문서를 매번 전부 읽히면 현재 변경과 관계있는 기준을 찾기 어렵습니다. 일부 규칙만 읽으면 함께 봐야 할 계약을 놓칠 수도 있습니다.

판단. 작업 범위를 판정하는 skill, 모든 적용 조건을 훑는 index와 선택한 규칙의 contract를 구분했습니다. 중요도에 따라 원문까지 읽어야 하는 범위를 명시했습니다.

flowchart LR
    Task["변경 범위"] --> Skill["SKILL: 범위 판정"]
    Skill --> Index["RULES_INDEX: 전체 적용 조건"]
    Index --> Contract["해당 규칙의 contract"]
    Contract --> High["CRITICAL과 HIGH: 원문 전체"]
    Contract --> Medium["MEDIUM: 규범과 첫 예시 쌍"]

구현. appliesWhen으로 적용 조건을 기록하고 requiresSelected와 reviewWith로 관련 규칙을 연결했습니다. CRITICAL과 HIGH contract는 원문 전체를 요구하고 MEDIUM contract는 규범과 첫 Incorrect, Correct 예시를 포함하도록 생성했습니다.

구현 코드: 중요도에 따른 contract 생성

if (rule.impact === "CRITICAL") {
  return fullRuleNotice(
    ", and re-check the result against its Correct examples before completion"
  );
}
if (rule.impact === "HIGH") {
  return fullRuleNotice("");
}

routing.ts의 분기 일부입니다. MEDIUM에서는 별도로 추출한 규범과 첫 예시 쌍을 사용합니다.

결과. 규칙의 범위와 읽기 순서를 문서 자체의 계약으로 남겼습니다. 실제 agent의 준수율이나 token 절감률은 이 구조의 존재와 구분해 측정해야 할 항목으로 남겼습니다.

규칙 하나를 고치면 skill과 읽기용 문서에 함께 반영하기

문제. agent용 설명과 문서 사이트를 따로 관리하면 같은 규칙의 예제와 참조가 달라질 수 있습니다.

판단. 규칙과 예제를 원본으로 두고 index, contract와 사이트 문서를 생성했습니다. 번호가 바뀌어도 규칙의 연결은 stable ID로 유지하도록 구성했습니다.

flowchart TB
    Source["규칙 원본과 예제 파일"] --> Index["RULES_INDEX"]
    Source --> Contracts["stable ID별 contract"]
    Source --> Site["읽기용 문서 사이트"]
    Source --> Check["참조와 예제 검사"]

구현. 생성할 contract와 기존 파일 목록을 대조해 삭제된 규칙의 옛 산출물도 정리했습니다. 생성 대상을 쓰기 전에 중복 경로와 일반 파일 여부를 검사하는 코드도 두었습니다.

결과. 한 규칙의 설명과 예제가 두 가지 읽기 방식으로 이어졌습니다. 현재 문서 사이트도 같은 원본을 for-humanity로 빌드합니다.

문장으로 쓴 기준을 검사할 수 있는 대상으로 바꾸기

문제. 규칙 문장이 그럴듯해도 예제가 실행되지 않거나 참조한 규칙이 없으면 적용 기준으로 쓰기 어렵습니다.

판단. 규칙의 내용 검토와 함께 예제, 메타데이터와 생성물을 검사 대상으로 두었습니다.

구현. 올바른 예제의 lint와 타입 검사, 참조와 선언 관계 검사, 생성물 일치 검사를 구성했습니다. 시나리오에 기록한 기대 skill과 선택 규칙의 집합, 필수 규칙과 마무리 규칙의 포함 여부도 검사하도록 만들었습니다.

결과. 규칙을 바꿀 때 설명과 예제, 참조 관계를 함께 확인할 수 있는 구조를 남겼습니다. 검증 명령은 저장소의 작성 가이드에서 확인할 수 있습니다.

결과와 확인 범위

반복하던 코드 판단을 적용 조건과 예제, 검사 코드로 옮긴 개인 프로젝트입니다. 주요 규칙과 생성 도구를 작성했으며 팀 전체의 채택률이나 개발 시간 개선율은 측정한 성과로 추가하지 않았습니다.