AI는 지시를 무시한다. 따라서 품질 보증을 프롬프트에 두어서는 안 된다

최근에는 CLAUDE.md나 AGENTS.md 같은 곳에 Repository에서 지켜줬으면 하는 규칙들을 작성하는 경우가 늘었습니다.

저도 사용하고 있습니다.

- 변경 후에는 반드시 테스트를 실행한다
- lint / typecheck를 실행한다
- 기존의 테스트를 망가뜨리지 않는다
...

이런 지시사항을 적어두면, 매번 Prompt로 설명할 필요가 없습니다.
꽤 편리합니다.

다만 사용하다 보니 신경 쓰이는 점도 생겼습니다.

적었다고 해서 반드시 지켜지는 것은 아니다.

테스트를 실행해 달라고 써 두었어도, 실행하지 않고 작업을 끝내는 경우가 있습니다.
변경 범위를 한정했더라도, 필요하다고 판단하면 다른 곳까지 변경하는 경우가 있습니다.
긴 작업 도중에 처음에 준 조건 중 일부가 빠지기도 합니다.

그렇다면 더 강하게 적으면 될까요?

IMPORTANT:
반드시 테스트하세요.
VERY IMPORTANT:
...

아마 이것은 본질적인 해결책이 아니라고 생각합니다.
문제는 Prompt를 작성하는 방식 자체가 아닙니다.
애초에 지켜지지 않으면 곤란한 조건을 Prompt에 넣고 있다는 점입니다.

CLAUDE.md나 AGENTS.md는 매우 편리합니다.
Repository의 구조, Coding Convention, Test 실행 방법, 설계상의 주의점 등을 Agent에게 전달하는 용도로는 상당히 유효합니다.
다만 그것은 어디까지나 Instruction(지시사항)입니다.
여기에 대해서는 Agent에 의한 해석이 있습니다.

OpenAI의 Codex에서도 AGENTS.md는 탐색된 후 Conversation에 Instruction으로 주입됩니다. 계층별 AGENTS.md를 읽어 들인 다음, 더 깊은 Directory의 Instruction이 나중에 전달되는 방식입니다.
즉,

테스트를 실행해 주세요

와

테스트가 성공하지 못하면 Merge할 수 없다

는 다릅니다. 전자는 Agent에 대한 요구사항이고, 후자는 System에 의한 Control(제어)입니다.
이 두 가지는 분리해서 생각하는 것이 좋다고 생각합니다.

이것은 단순히

AI에게 '조심하라'는 지시도 마찬가지로 다루는 것이 좋습니다.

여기서 Agent에게 제공하는 모든 것을 CI(Continuous Integration)로 옮기면 된다는 이야기는 아닙니다.

Instruction에는 Instruction으로서의 역할이 있습니다.

예를 들어,

이것을 하나의 Prompt에 몰아넣으면 안 됩니다.

제가 특히 의식하는 것은,

Agent가 무시해도 곤란하지 않은 것과, 무시되면 곤란한 것을 분리하는 것입니다.

예를 들어 Claude Code에는 Hooks가 있습니다.

PreToolUse를 사용하면 Tool이 실행되기 전에 프로세스에 개입하여 조건에 따라 Tool Call을 거부할 수 있습니다.

Claude Code의 공식 Documentation에서는 Hook과 Skill에 대해 상당히 명확하게 역할을 분리하고 있습니다.

Skill은 Claude가 Instruction을 읽고 해석해서 사용하는 것입니다.
반면 Hook은 Lifecycle Event(생명 주기 이벤트)에서 실행됩니다.

나아가, 매번 적용해야 하는 Guardrail(안전장치)는 Instruction이 아니라 Hook에 두어야 한다는 생각까지 명시되어 있습니다.

예를 들어,

Production DB에 쓰기는 금지

이라고 Prompt에 적는 것과,

Production DB에 Write 작업을 그 자체로 거부하는

것은 다릅니다.

저는 후자(그 자체를 거부하는 방식)가 가능하다면 후자에 가깝게 배치합니다.

다만, Hook도 Test를 대신할 수는 없습니다.

Hook이 보장할 수 있는 것은,

이 Tool을 쓰지 못하게 하는 것
이 Command를 실행하지 못하게 하는 것
이 작업의 전후에 프로세스를 실행하는 것

같은 제어(Control)입니다.

반면에,

Transaction Boundary가 올바른지
Retry 시 이중 처리가 되지 않는지
이 변경 사항이 Business Contract를 충족하는지

는 별개의 문제입니다.

거기에는 Test나 Static Analysis 같은 검증(Verification)이 필요합니다.

여기서도 한 단계 더 분리해야 합니다.

예를 들어 Agent에게,

구현 후에 Integration Test를 실행해 주세요

라고 지시했다고 가정합시다.

Agent가 제대로 실행했습니다. 모든 것이 Green(녹색)이었습니다.
그래도,

Quality = OK

라고는 할 수 없습니다.

이전 기사에서도 썼지만, Green은 Quality 그 자체가 아니라 Signal(신호)입니다.
Test가 보고 있는 Risk(위험 요소)가 어긋나 있다면, 몇 건이 Green이라도 지키고 싶은 것은 지킬 수 없습니다.

그래서 구조적으로는,
[이미지 Placeholder]
이 됩니다.

Agent는 이 중 상당 부분을 도울 수 있습니다.
Risk를 조사합니다.
기존 Test를 찾습니다.
Test를 작성합니다.
Test를 실행합니다.
실패를 분석합니다.
수정합니다.

여기는 마음껏 맡겨도 좋다고 생각합니다.

하지만,
어떤 Risk를, 무엇을 근거로 멈출 것인가
라는 구조까지 Agent에게 주는 Instruction에만 가두게 되면, 품질 보증 그 자체가 Agent의 판단에 의존하게 됩니다.

그것은 분리하고 싶습니다.

이런 이야기를 하면,
AI를 신뢰하지 않는 건가
라는 방향으로 흐르기 쉽지만, 저는 그렇게 생각하지 않습니다.

오히려 상당히 사용합니다. 조사도 구현도 Test도 Review도 AI에 의해 빠르게 할 수 있는 부분이 많습니다.
제가 신경 쓰는 것은 신뢰가 아니라 책임(責務)입니다.

인간이든 AI든,
절대로 지켜야 하는 조건을 누군가의 주의력이나 판단만에게 맡기지 않는 것.
이것은 예전부터 변하지 않았습니다.

Coding Agent가 아직 단순한 코드 보완 기능이었을 때는,

AI가 작성한다
↓
인간이 확인한다

정도만으로도 성립할 수 있었습니다. 지금은 다릅니다.
Agent 자신이 Repository를 조사하고, 구현하고, Test를 쓰고, 실행하고, 수정하고, 경우에 따라 여러 Agent에게 일을 분해합니다.

Anthropic 역시 장시간 구동하는 Coding Agent에 대해 Prompt뿐만 아니라 Harness 전체를 어떻게 설계할지 지속적으로 연구하고 있습니다.

2026년 3월에 공개된 Harness Design 아티클에서는 Prompt Engineering과 Harness Design을 통해 개선을 진행한 후, 나아가 Agent의 성능을 끌어내기 위해 주변 구조 자체를 재검토하고 있습니다.

이는 품질 보증(QA)에서도 마찬가지라고 생각합니다.

Agent에게 무엇을 쓰게 할지뿐만 아니라,

Agent 외부에 무엇을 둘 것인지.

Coding Agent가 강해질수록, 이쪽 설계가 더 중요해진다고 생각합니다.

최근에는 CLAUDE.md나 AGENTS.md 같은 파일을 정리할 기회가 늘었습니다.

그때 저는,

이 규칙은,
Agent가 알고 있어야 하는 것인가?
아니면,
...

을 나누어 생각하고 싶습니다.

알고 있어야 한다면, Instruction으로 충분합니다.
특정 조작을 금지하고 싶다면, Hook이나 Permission이 더 적절할 수 있습니다.
코드의 성질을 보장하고 싶다면, Static Analysis나 Test가 필요할 수 있습니다.
변경을 통해선 안 된다면, CI의 Quality Gate까지 필요해집니다.
프로덕션 환경에서만 알 수 있다면, Observability가 필요합니다.

모든 것을 Prompt에 쓸 필요는 없습니다.
AI는 지시를 무시하는 경우가 있습니다.
사람도 잊습니다.
그러니 그 점을 탓해도 소용이 없습니다.

여러 번,

절대적으로 지켜주세요.

라고 쓰는 것보다,
지키지 않으면 다음 단계로 진행할 수 없는 메커니즘으로 만들 수는 없을까 생각합니다.

사람에게 해왔던 것을 AI에게도 그대로 적용하는 것일 뿐입니다.
AI Coding Agent가 강해질수록, Prompt Engineering뿐만 아니라 그 외부에 있는 Software Engineering의 설계가 중요하게 작용합니다.
저는 그렇게 생각하고 있습니다.

• OpenAI — Codex Prompting Guide Codex Prompting Guide
• GitHub Docs — Creating and using custom agents for GitHub Copilot CLI GitHub Copilot CLI Custom Agents
• GitHub Docs — GitHub Copilot CLI command reference Copilot CLI command reference
• Claude Code Docs — Extend Claude Code Claude Code features overview
• Claude Code Docs — Permissions Claude Code permissions
• Anthropic Engineering — Harness design for long-running application development Harness design for long-running application development