류준열의 기술 블로그 | 하네스 만들기 3탄

하네스 만들기 3탄

하네스는 실패에서부터 시작한다.

전에 같이 일하던 동료가 전해준 자료들을 참고해서 하네스를 만들고 있다. (작업을 돌려놓고 블로그를 쓰고 있다)

옵시디언에 모든걸 기록해두고 RAG처럼 사용하니까 좋다. 일단 옵시디언에 기록해두면 필요할때마다 AI한테 찾아보라고 하면 되어서 이런 방법을 사용하고 있다.

오늘은 프론트엔드 서브에이전트를 만들었다. 고민이 생길때마다 AI한테도 물어보고 블로그 글들도 봤는데, 하네스 엔지니어링 wikidocs 가 많이 도움이 되었다.

내가 하고 싶은건, 내가 작성한 가이드 문서들이 하네스가 되도록 하는 것이었다.

처음에는 skills로 구현했다.

task-docs 매핑 테이블을 두고, 작업에 맞는 문서를 찾아 읽히는 방식이었다. 그런데 이 방식은 결국 “이 문서를 읽어라”라고 말만 하는 수준에서 더 발전하지 못했다.

PostToolUse hook으로 경고 메시지를 띄우는 것도 시도했다. 하지만 이것도 종종 무시됐다. 결국 필요한 건 “읽으라고 말하는 구조”가 아니라, "읽지 않으면 다음 단계로 넘어갈 수 없는 구조"였다.

노이즈를 제거하고 목표에만 집중 할 수 있도록 독립 컨텍스트를 가진 서브에이전트로 시도해보았다.

프론트엔드 서브에이전트

fe.md

메인 에이전트
  → 서브에이전트 fe 호출
    → Phase 1: AGENTS.md 목차 → 관련 docs/ 문서 실제 Read
    → Phase 2: 규칙 준수하며 코드 작업
    → Phase 3: 자기 검증 + 체크리스트 반환

바로 작업을 시작하지 않고, 문서를 읽은 후 코드를 수정하도록 헀다.

Phase 1: 문서 읽기

이 단계는 건너뛸 수 없다.

Skill의 task-docs 매핑 테이블에서 작업과 관련있는 문서 선별 (모든 문서를 읽지 않음)
AGENTS.md에서 목차 파악 2-1. AGENTS.md에는 과거의 실수, 프로젝트 결정사항, 개발 가이드 링크가 리스트업 되어있다.
과거의 실수 기록 확인
1번에서 선별한 문서를 frontend/docs에서 찾아서 읽는다

Phase 1을 완료하지 않으면 Phase 2를 시작하지 않는다.

Phase 2: 작업 수행

역할을 좁힌 서브에이전트가 문서 읽기와 작업을 진행한다.

Phase 1에서 읽은 규칙을 준수하며 코드를 작성/수정한다.
TypeScript strict 모드를 준수한다.

Phase 3: 자기 검증 + 결과 반환

읽은 문서의 규칙으로 자기 검증 후 반환

이렇게 플로우를 구현하니 필요한 문서만 읽는걸 확인할 수 있었다.

실수를 다시 문서로 보완

실제 작업을 하니 무지성 메모이제이션을 한다거나, react hook form에서 쓸데없이 onChange, watch를 사용하는 아쉬운 부분이 있었다.

이러한 내용을 AI와 정리하며 옵시디언에 기록하고, 다시 읽혀서 문서화 시키고 frontend/docs에 보완하는 방식으로 진행했다.

그 외 back pressure

작업하면서 크게 느낀건 LLM은 비결정적이라는 것이다.

md를 따를때도 있고 무시할때도 있다.

그래서 컨벤션, 품질 기준 같은건 lint, tsc, sh등으로 강제하는것이 좋다.

지금은 이런식으로 걸어두었다.

frontend/ 소스 파일 수정 후 tsc 자동 실행
.claude/settings.json PostToolUse 훅에 등록

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/block-secrets.sh"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/frontend-eslint.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/frontend-typecheck.sh"
          },
          {
            "type": "command",
            "command": "bash .claude/hooks/prettier.sh"
          }
        ]
      },
      {
        "matcher": "Skill",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/skill-doc-reminder.sh"
          }
        ]
      }
    ]
  },
  "enabledPlugins": {
    "session-wrap@team-attention-plugins": true,
    "frontend-design@claude-plugins-official": true
  }
}

PreToolUse와 PostToolUse로 문서 작업 전,후 실행해야 하는 작업들을 안내했다.

서브에이전트의 작업이 전,후 hook이 개입하여 작업 전에 .env나 api key 접근을 막고, 작업 후에는 최소한의 품질 기준을 강제한다.

문서를 읽는 흐름과 작업 결과를 되받아치는 장치가 중요하다.

마무리

스킬로 구현하니까 문서를 안읽고, 서브에이전트로 해도 문서를 덜 읽고, ... 이런 저런 개선을 해봤지만 아직 부족하다.

'하네스는 실패관찰에서 시작한다'는 글이 맞다.

하네스가 몇달뒤 추상화되어 만들기 쉬워진다해도 이 경험들은 또 다른 문제를 해결하는데 도움이 될 것이다.

개발자 류준열