지난주 야간 장애 대응 중에 인증 세션 토큰 만료 버그를 잡으려 코딩 에이전트에 에러 로그를 던졌습니다. 화면에 뜬 첫 줄은 “좋은 질문입니다! 이 문제는 인증 미들웨어와 쿠키 처리 로직이 복잡하게 얽혀 발생할 수 있습니다…“로 시작하더군요. 새벽 2시에 서비스가 멈춰서 피가 마르는데, 정작 수정해야 할 파일 경로와 코드 라인을 보려면 마우스 휠을 세 번이나 굴려야 했습니다.

도움을 주려는 의도는 알겠지만, 터미널 앞에서 빠른 판단을 내려야 하는 개발자에게 이런 장황한 서두와 예의 바른 미사여구는 순수한 노이즈일 뿐이었습니다.

이런 문제의식을 느끼던 중 깃허브 트렌드에서 발견한 오픈소스가 바로 ayghri/i-have-adhd였습니다. 레포지토리 이름에는 ADHD가 들어가 있지만, 실제로 뜯어보니 에이전트의 불필요한 사족을 쳐내고 결론부터 터미널에 꽂아 넣고 싶어 하는 모든 개발자를 위한 극단적 실용주의 프롬프트 규칙이었습니다.

flowchart TD subgraph Default ["일반적인 에이전트 응답"] A1["사용자 프롬프트 입력"] --> B1["서두 및 인사말: 좋은 질문입니다..."] B1 --> C1["배경 이론 및 상황 설명 (3~5단락)"] C1 --> D1["수정 코드 및 명령어 (스크롤 하단 은닉)"] D1 --> E1["사족 및 맺음말: 도움이 되셨길 바랍니다!"] end subgraph ADHD ["i-have-adhd 적용 후 응답"] A2["사용자 프롬프트 입력"] --> B2["첫 줄: 즉시 실행할 명령어 및 파일 경로"] B2 --> C2["간결한 넘버링 액션 (최대 3~5단계)"] C2 --> D2["다음 단계 단일 액션 안내 (종료)"] end

에이전트는 왜 핵심 답변을 자꾸 숨길까

대부분의 대규모 언어 모델(LLM)은 기본적으로 친절한 튜터처럼 행동하도록 RLHF(인간 피드백 기반 강화학습)를 거칩니다. 그래서 질문을 받으면 상황을 재정의하고, 공감을 표하며, 친절한 조언을 덧붙인 뒤 마지막에 “도움이 되었으면 좋겠습니다"로 끝맺는 정형화된 패턴을 따릅니다.

문제는 개발자가 코딩 에이전트(Claude Code, Cursor, Codex 등)를 쓸 때 원하는 것은 친절한 대화가 아니라 실행 가능한 코드라는 점입니다.

군대나 응급 구조 현장에서는 BLUF(Bottom Line Up Front, 결론 최우선 제시) 원칙을 사용합니다. i-have-adhd는 이 BLUF 철학을 에이전트 시스템 프롬프트에 강제로 주입합니다. 사용자의 작업 기억(Working Memory)은 한정되어 있고, 터미널을 보는 뇌의 피로도를 최소화해야 생산성이 유지된다는 전제에서 출발합니다.

실무 프로덕션 환경에서 주의할 점: 에이전트의 답변을 지나치게 단축하도록 강제하면, 복잡한 분산 트랜잭션이나 데이터베이스 마이그레이션처럼 배경 컨텍스트가 중요한 작업에서 맥락을 놓치고 위험한 명령어를 무비판적으로 실행할 위험이 커집니다.

실무에서 체감된 핵심 10대 규칙

SKILL.md에 명시된 10가지 규칙 중, 실제 업무에서 가장 체감이 컸던 3가지 규칙을 정리했습니다.

1. 첫 줄은 무조건 다음 실행 행동으로 시작 (Lead with action)

질문에 대한 답이 명령어, 파일 경로, 코드 스니펫이라면 설명보다 그것이 먼저 화면에 나와야 합니다.

기존 나쁜 예시:

인증 흐름을 살펴보면 몇 가지 고려할 점이 있습니다. auth.ts의 verifyToken 함수를 보면 구버전 라이브러리를 쓰고 있는데요, 최신 버전으로 패키지를 올리고 함수를 고치는 것이 좋겠습니다.

개선된 예시:

npm install jsonwebtoken@latest 실행 후 src/auth.ts:42 수정.

  1. src/auth.ts 열기
  2. verifyToken 함수(42~58줄)를 아래 코드로 교체
  3. npm test -- auth.spec.ts 실행

실무 프로덕션 환경에서 주의할 점: 패키지 업데이트 명령어를 첫 줄에서 바로 제시받을 경우, 메이저 버전 변경(Breaking Changes)으로 인한 사내 타 모듈과의 의존성 충돌 여부를 사전에 파악하기 어려우므로 반드시 lock 파일 변경 내역을 교차 검증해야 합니다.

2. 곁가지(Tangents) 원천 차단

에이전트가 흔히 저지르는 실수 중 하나가 바로 요청하지 않은 문제를 지적하며 삼천포로 빠지는 것입니다. 코드 버그를 물어봤는데 “참고로 의존성 버전이 오래되었고 README에 오타가 있네요"라며 주의를 분산시킵니다.

i-have-adhd는 현재 당면한 단 하나의 문제만 해결하도록 못 박습니다. 다른 이슈가 발견되더라도 현재 작업을 완전히 끝낸 뒤 별도의 독립 질문으로만 분리해 제시하게 만듭니다.

실무 프로덕션 환경에서 주의할 점: 보안 취약점(CVE)이나 심각한 메모리 누수와 같은 잠재적 크리티컬 버그까지 곁가지로 취급되어 보고가 누락될 수 있으므로, 보안 점검 세션은 별도로 분리해 실행하는 운영 규칙을 세워야 합니다.

3. 미사여구 및 서두/요약문 삭제 (No preamble, no closers)

“좋은 질문입니다”, “확인해 보겠습니다”, “도움이 되셨길 바랍니다”, “추가 질문이 있으시면 언제든 말씀해주세요” 같은 문장을 전면 차단합니다.

단순히 몇 글자 줄어드는 것을 넘어 터미널 버퍼의 스크롤 낭비를 줄이고, 에이전트와 주고받는 턴(Turn) 사이의 인지 전환 비용을 대폭 낮춰줍니다.

실무 프로덕션 환경에서 주의할 점: CI/CD 실패 로그나 서버 덤프를 분석할 때 에러 원인의 인과관계 설명까지 요약되어 원인 규명이 모호해질 수 있으므로, 장애 리포트 작성 시에는 상세 모드로 전환해야 합니다.

사내 프로젝트 적용 및 테스트

설치는 간단합니다. Claude Code나 지원 에이전트 CLI 환경에서 다음 명령어로 스킬이나 플러그인을 불러올 수 있습니다.

# 에이전트 프롬프트에 직접 입력하여 설치
Install the i-have-adhd skill from https://github.com/ayghri/i-have-adhd

자체 환경에 맞춰 커스텀하려면 저장소를 포크한 뒤 skills/i-have-adhd/SKILL.md 파일을 수정해 개인화할 수 있습니다.

실제로 사내 결제 모듈 리팩토링 과정에서 /i-have-adhd 모드를 켜고 작업을 진행해 보았습니다. 에이전트가 긴 설명 없이 바로 수정할 파일의 상대 경로와 줄 번호를 찍어주니, diff를 확인하고 커밋을 찍는 속도가 확실히 빨라졌습니다.

규칙을 깨야 하는 예외 상황

원작자 역시 무조건적인 극단적 간결함을 고집하지는 않습니다. 시스템 프롬프트 내부에는 다음과 같은 예외 조항(When to break the rules)이 명시되어 있습니다.

  1. 사용자가 원리 설명이나 코드 워크스루를 명시적으로 요구했을 때 (explain, walk me through)
  2. rm -rf, 강제 푸시(git push -f), 테이블 드롭, 스키마 마이그레이션 등 파괴적(Destructive) 명령어 실행 전 확인이 필요할 때
  3. 3회 이상 디버깅이 반복 실패하는 디버그 스파이럴 상황일 때 (코드를 계속 찍어내는 대신 근본 가정 재점검 질문을 던짐)

실무 프로덕션 환경에서 주의할 점: 에이전트가 파괴적 명령어 확인 절차를 건너뛰지 않도록, 사내 배포 스크립트나 인프라 관리 도구(Terraform, K8s) 연동 시에는 시스템 프롬프트 수준의 가드레일이 상위 우선순위를 갖도록 설정해야 합니다.

정리하며

AI 코딩 어시스턴트가 쏟아내는 긴 텍스트에 피로감을 느끼고 있었다면, 이 프로젝트의 SKILL.md 전문을 한 번 읽어보시길 권합니다. 꼭 플러그인 형태로 쓰지 않더라도, 본인이 사용하는 에이전트 시스템 규칙(CLAUDE.md, .cursorrules, AGENTS.md)에 2~3가지 핵심 룰만 발췌해 넣는 것만으로도 작업 효율이 체감될 만큼 달라집니다.