AI 코딩 에이전트에게 신뢰할 수 있는 도메인 지식을 주는 방법

일반적인 coding agent는 그럴듯한 답을 쓰면서도 stack의 중요한 세부 사항을 놓칠 수 있다. 최근 바뀐 API, 넘어가면 안 되는 repository boundary, production 안정성을 지키는 convention이 그 예다. 해결책이 항상 더 긴 prompt인 것은 아니다. 작고 재사용 가능한 domain guidance와 검증 가능한 definition of done을 제공하라.

1. project rule과 domain procedure를 분리하라

두 계층으로 시작한다. 첫 번째는 짧은 repository contract다. project의 성격, 구조, build/test command, 수정 금지 file, done의 조건을 적는다. JetBrains의 agent behavior 문서는 AGENTS.md와 CLAUDE.md 같은 instruction file이 repository와 함께 이동하고 여러 도구에서 공유될 수 있다고 설명한다.

이 계층은 안정적이고 운영 가능해야 한다. domain logic의 위치, check 실행법, 수정하면 안 되는 범위를 알려줘야 한다. 한 workflow에만 필요한 규칙은 별도 skill에 둔다.

두 번째 계층은 domain knowledge다. Android navigation migration, database schema change, release checklist처럼 반복 작업을 위한 focused recipe다. skill에는 명확한 trigger, 짧은 단계, explicit validation이 필요하다.

2. knowledge gap을 중심으로 skill을 작성하라

좋은 skill은 model이 반복해서 틀리거나 같은 내용을 매번 다시 찾을 때 만든다. Android Skills 철학은 변화하는 API와 custom architecture에서 검증 가능한 gap을 찾으라고 한다. 테스트되지 않은 대형 모음 대신 신뢰할 수 있는 source에서 skill을 받으라는 경고도 있다.

작은 예시는 다음과 같다.

---
name: navigation-upgrade
description: Use when changing the app's Navigation 3 setup or upgrading its related APIs.
---

Before editing:
1. Inspect the current dependency versions and existing navigation tests.
2. Read the project's navigation conventions.
3. Confirm the target API in the approved platform documentation.

While editing:
- Make the smallest vertical change that satisfies the requested behavior.
- Do not replace the navigation architecture without approval.
- Preserve existing deep-link and back-stack behavior unless the task says otherwise.

Done means:
- The focused tests pass.
- The relevant build or lint command passes.
- The response names changed files, checks run, and unresolved risks.

예시는 의도적으로 좁다. 매번 전체 framework manual을 붙이지 않고, 언제 적용하고 무엇을 확인하며 어떤 경계를 지키고 완료를 어떻게 증명할지 알려준다. 실제 repository의 command와 convention으로 바꿔라.

3. agent가 행동하기 전에 inspect하게 하라

Coding agent는 request와 environment context를 결합하고 추론한 뒤 edit, test, build를 수행한다. AWS Prescriptive Guidance가 설명하는 pattern이다. 지침에 단계를 드러내라.

실용적인 요청은 네 부분이다.

1. Context: feature, 관련 directory, constraint.
2. Plan: edit 전에 file과 check 목록.
3. Change: acceptance criteria를 만족하는 최소 구현.
4. Evidence: test, lint, build 또는 manual check.

이렇게 하면 agent가 한 문장만 보고 시작했다가 architecture를 늦게 발견하고 큰 rewrite로 보상하는 일을 줄일 수 있다. inspection은 판단에 필요한 context를 얻는 방법이다.

4. 짧은 feedback loop를 제공하라

Domain guidance는 project 방식을 설명하지만 executable check가 변경의 성공 여부를 보여준다. VS Code의 최신 TDD guide는 failing test의 red, 최소 구현의 green, test를 유지하는 refactor를 분리한다.

세 개의 복잡한 agent는 필요 없다. 작은 task에서는 먼저 failing 또는 characterization test를 요구한 뒤 구현하고 focused test와 일반 quality gate를 실행하라. check가 실패하면 requirement나 environment에 대한 정보이지, 자신감 있는 요약으로 숨길 일이 아니다.

5. guidance를 검토하고 폐기하라

skill을 versioned engineering infrastructure로 취급한다. framework 변경, agent의 반복 오류, noisy check가 있을 때 review한다. Android Skills guidance는 model이 개선되면 기존 지침이 불필요해지고 새 API가 새 gap을 만든다고 설명한다.

간단한 유지보수 loop:

• skill을 실행하는 example task를 남긴다.
• 예상 file과 validation command를 기록한다.
• skill 또는 model 변경 후 실행한다.
• 더 이상 필요 없는 instruction을 삭제한다.
• 보안 민감 작업은 optional하고 review 가능하게 한다.

목표는 agent가 더 전문가처럼 들리게 하는 것이 아니라 올바른 behavior를 재현 가능하게 만드는 것이다. 짧은 repository contract, 정확한 domain procedure, 실행 가능한 done-definition이 context에서 change와 evidence로 가는 길을 만든다.