Rules나 Skills를 유지보수하는 것이 힘들기 때문에, 「구현 예시」를 많이 준비하기보다 「원칙」을 우선하여 Rules나 Skills로 옮겨 운용해 보았습니다.

느낌이 좋았기에 Agentic Coding의 한 사례로 소개합니다.

특히 0 → 1 단계의, 아직 패턴화되지 않은 문서 작성이나 코딩 작업에 효과적입니다.

품질이나 비용 등 어떤 이유로든 문서나 코드에 신경을 써야 한다면 더욱 추천합니다.

구성 예시

「원칙」의 Rules/Skills: 가장 추상도가 높고 관점이 높은 진정한 공통 지침

• 문서의 취급

• 코드(프로그램)의 취급 (책임 분리(Separation of Concerns) 원칙, 경계 설계)

• 테스트의 취급

「원칙」을 적용하는 Rules/Skills: 문서의 종류·언어·프레임워크·아키텍처별

• DesignDoc에서는 어떻게 할 것인가

• CONTRIBUTING.md에서는 어떻게 할 것인가

• README.md에서는 어떻게 할 것인가

• 커밋 메시지(Commit Message)에서는 어떻게 할 것인가

• Go에서는 어떻게 할 것인가

• React에서는 어떻게 할 것인가

구체적인 설명이나 지시를 하는 Rules/Skills + AGENTS.md (CLAUDE.md): 프로젝트·작업·워크플로우별

• 패턴별 구현 방법
• 리뷰 방법
• 테스트 방법
• 커밋 메시지 포맷
• 프로젝트 개요, 목적, 설계
• 기타 워크플로우

「원칙」의 Rules/Skills

0 → 1 단계의 문서 작성이나 코딩에서, "DesignDoc을 만들어줘"라거나 "Clean Architecture로 만들어줘"라고 만들고자 하는 대상의 정보를 20~30줄 정도 작성한 뒤 지시하면, 결과물이 그저 그렇거나 그 이하인 경우가 많다고 느낍니다.

※ 기준이 까다로운 개인적인 감각입니다.

구체적인 예시나 스타일 가이드(Style Guide)를 참조하게 해도 누락되는 부분이 있으며, "추가 정보나 판단이 필요한 경우에는 질문해줘"라고 지시를 넣으면 차라리 내 손으로 전체적인 틀을 만드는 게 더 빨라지는 경우도 있습니다.

즉, AI Agent의 출력에 대한 기대치에 비해 컨텍스트 관리(Context Management)가 불충분한 것입니다.

문서를 만들게 할 때의 어려움

다음 프롬프트 구성에서는 무엇이 부족할까요?

• 정보를 20~30줄 정도 작성
• DesignDoc을 만들어줘
• 추가 정보나 판단이 필요한 경우에는 질문해줘

관점을 조금 바꿔서 볼 필요가 있지만, 아래와 같은 명확한 지시가 없습니다.

• DesignDoc의 역할은?

(일반적인 것이 아니라 이 프로젝트에서는 어떤가) - 이 프로젝트에서 문서는 어떻게 취급되는가?

(README, DesignDoc, ADR의 구분은?)

• 누가 읽는가? (엔지니어? 비엔지니어? 팀 내부?)
• 어디까지 작성하는가?
• 어떤 구성으로 작성하는가?

명확한 지시가 없는 이러한 사항들은, 질문 공세에 시간을 잡아먹거나,

멋대로 판단·추측되어 AI Agent나 모델의 습성·특징에 휘둘린 결과물이 됩니다.

문서에 관한 「원칙」을 스킬(Skill)로 만들기

다음의 styleguide-markdown-document/SKILL.md

와 참조하고 있는 document.md

가 「원칙」에 해당합니다.

그 외에는 「원칙」을 적용하기 위한 가이드 같은 것들이 적혀 있습니다.

styleguide-markdown-document/SKILL.md

---
name: styleguide-markdown-document
description: Write, review, and refactor Markdown documentation (README, PRD, DesignDoc, ADR, CONTRIBUTING) using the project's styleguide. Use when working on .md docs to enforce document boundaries, required sections, and link hygiene. Consult the referenced styleguide files under docs/styleguide/documents/*. Outputs are in English by default; also applicable to Japanese documents.
...

이 「원칙」과 「원칙을 적용하는 가이드」를 사용하여 작성한 DesignDoc 및 프롬프트

프롬프트

월 단위로 google calendar의 일정을 sync 하는 기능의 DesignDoc을 작성해 주세요.
결정해야 할 사항이나 모르는 점은 질문해 주세요.
입력:
...

Login with Google

gcal-sync login

Sync events to personal (or specified) calendar

gcal-sync <src calendar id> [--dest <dest calendar id>] [--name <sync event name>] [--all] [[--month YYYYMM]] [--next-month]

Options 및 사양
--dest, -d: 이벤트의 동기화 대상
--name: 복사할 이벤트의 이름 (완전 일치) (지정하지 않을 경우 경고를 출력하고 y/n를 프롬프트로 입력받음)
...

결과물 (소요 시간 20분 정도)

※ 상기 프롬프트 외에도 5회 정도 수정 및 추가 지시를 했습니다.

코딩을 시킬 때의 어려움

DesignDoc이나 Plan에 디렉토리 구성과 함께 "Clean Architecture를 채택한다." 또는 "DDD에 준거한다."라고 명시했을 경우에도 마찬가지로 부족한 정보가 있습니다.

• 무엇을 중시할 것인가?
• 무엇을 무시할 것인가?
• 어떻게 구현할 것인가?
• DDD는 어디까지 적용할 것인가?
• 레이어(Layer) 구성은?
• 테스트는 어디에 비중을 둘 것인가?
• 캐시(Cache)는 어디에 둘 것인가?
• 어떻게 책임을 분리할 것인가?

프로덕트나 운용 방침에 따라 채택한 아키텍처(Architecture)나 디자인 패턴(Design Pattern) 위에서 더욱 판단이 필요할 것입니다.

이 부분을 임의로 판단하거나 추측해 버리면 곤란합니다.

코딩에 관한 「원칙」을 스킬(Skill)로 만들기

이하의 styleguide-sourcecodes/SKILL.md 및 참조시키고 있는 모든 파일이 「원칙」에 해당합니다.

주로 「책임의 분리 (Separation of Concerns)」, 「경계 설계 (Boundary Design)」에 대해 정리되어 있습니다.

styleguide-sourcecodes/SKILL.md

---
name: styleguide-sourcecodes
description: Apply the repository's source-code design principles (separation of concerns, sliced iterations, root ownership) when designing, reviewing, or refactoring code. Use for any language to keep responsibilities thin, testable, and referencable.
...

「원칙」을 Rules/Skills로 운용했을 때의 효과

판단 재료 및 지침을 확실하게 원칙으로 정리할 수 있다면, 그 기준을 사용하여 부족한 정보를 보완할 수 있으므로 다음과 같은 흐름으로 진행할 수 있습니다.

원칙 + 컨텍스트 (Context) → 판단 → 구현

특히 DesignDoc 작성 시에는 완성까지의 대화(벽치기) 횟수가 1020회 정도에서 510회 정도로 줄어드는 경우가 많아졌습니다.

또한, 기분 좋은 오차로서 Claude Sonnet 4.6이나 GPT-5.4 mini 등 비교적 경량 모델에서도 불만을 느끼는 상황이 줄어들었습니다.

「원칙」의 언어화

물론, 이 「원칙」을 정리하기 위해서는 상응하는 시간이 필요합니다.

저의 경우에도 styleguide나 Skills를 만드는 단계에서는 AI나 팀 멤버와 상당한 대화(벽치기)를 거쳤습니다.

프롬프트 예시

〇〇에 대한 설계 원칙을 문서화해 주세요.
### 목표
다음의 인식을 팀 멤버 및 AI Agent와 맞추어, 계승 및 응용이 가능하도록 함
...

Discussion