ai-agents · AI 작업을 통제하고 검증하는 개발 환경
단독 개발의 검토 공백을 보완하기 위해 AI 리뷰와 테스트를 작업 절차에 연결하고, 작업 범위·도구·실행 기록을 관리합니다.
현재 운영
운영 중
제가 맡은 역할
개발 경험을 작업 규칙과 검증 기준으로 정리하고, Claude·Codex의 도구 연결과 실행 환경을 구성·운영.
결과
하네스 개념을 적용해 AI의 작업 범위와 완료 기준을 관리하고, 실제 서비스의 구현·검토·QA 자료 작성에 활용합니다.
기록 → 판단 → 적용 → 검증
- 01Notion경험·기술 조사
문제와 원문, 다음 행동 기록
- 02개발자 판단비교·선별
내 업무에 필요한 변화 결정
- 03ai-agents규칙·도구 개선
Skills · 작업 범위 · AI 리뷰
- 04실제 업무결과 검증
테스트 · Jira · 실행 기록
일부 기록·제안 처리는 자동화하고, 적용 여부와 최종 검토는 직접 판단합니다.
검색 도구를 더했을 때,
결과도 좋아졌을까?
같은 자체 과제로 비교하고, 점수가 높았던 문자열 검색 중심 방식을 선택했습니다.
평가 조건과 해석 범위
Notion 검색 전략과 ai-agents 운영문서의 기록을 요약했습니다. 35B 로컬 모델·소규모 자체 코드 위치 탐색 과제(N=4)에서 비교한 결과입니다. 모든 검색 문제의 정확도나 개발 생산성을 뜻하지 않으며, 벡터 검색 전체의 우열로 일반화하지 않습니다.
비교 대상: rg-first 93%, rg + semantic 79%. 이 기록에 따라 해당 코드·위키 검색 경로를 정리했습니다.
담당 역할과 구현 과정 자세히 읽기
개발·운영 경험을 AI가 따라야 할 기준으로 바꿨습니다.
웹 서비스와 장비 소프트웨어를 개발하며 요구사항 해석, 예외 처리, 배포와 검수를 직접 수행해 왔습니다. ai-agents에서는 이 경험을 수정 범위, 작업 절차, 완료 기준으로 정리합니다. 본인이 판단할 부분과 AI에 맡길 조사·구현·검토를 구분하고 결과를 확인합니다.
AI가 일할 환경을 구성하는 하네스 개념을 적용했습니다.
하네스는 AI에 필요한 문서와 도구를 제공하고, 실행 범위와 검증·기록을 관리하는 주변 실행 체계입니다. 공통 규칙은 AGENTS.md에서 안내하고, 반복 작업은 Skills로 정리했습니다. Claude와 Codex가 같은 업무 기준을 참고하도록 하되 실행 방식의 차이는 별도로 관리합니다.
범위를 정하고, 변경을 검토하고, 실제 결과로 완료를 판단합니다.
작업별 수정 범위와 읽기·쓰기 역할을 구분하고, 변경 작업에는 별도 worktree를 사용하는 절차를 둡니다. 단독 개발의 검토 공백을 보완하도록 AI 리뷰를 도입하고 테스트·린트·빌드 등 실행 결과를 함께 확인합니다. 문서의 작업 지침과 hook·권한·검증 코드가 실제로 강제하는 조건은 구분해서 관리합니다.
실제 사례: 로그인 전환의 롤백 조건까지 검토했습니다.
로그인 전환 작업에서는 신규 배포 후 롤백하고 다시 배포하는 상황을 제가 검토 조건으로 제시했습니다. 저장된 AI 작업 일지에는 레거시 쿠키 유지·세션 중복 발급 방지, 로그아웃 실패 시 쿠키 정리, 관련 테스트와 QA 안내 작성이 남아 있습니다. 연결된 Jira 작업은 종료 상태입니다. AI가 낸 구현 결과를 운영 조건과 검수 항목까지 연결한 사례입니다.
실제 사례: AI가 만든 검증 자료의 오류도 바로잡았습니다.
만화 장르홈 GA4 작업에서는 태깅 규칙·코드·화면을 대조해 담당자 보고 자료를 작성하도록 했습니다. 화면 촬영 결과에 지연 로딩이 반영되지 않은 것을 확인하고, 페이지를 끝까지 스크롤한 뒤 로딩 완료 상태에서 다시 촬영하도록 검증 방법을 수정했습니다. 작업 일지에는 5개 장르 화면의 재확인 기록이 있고, 연결된 Jira 작업은 완료 상태입니다.
작업 기록을 남겨 검토 근거를 추적합니다.
계획과 실행 상태, 결과·검증 근거를 기록하고 Jira 업무와 함께 확인합니다. AI가 완료했다고 응답했는지뿐 아니라 어떤 변경과 검사를 수행했는지 확인하는 데 사용합니다. 실행 횟수를 생산성으로 환산하지 않고, 실제 업무 결과와 연결해 개선할 부분을 찾습니다.
개발 경험과 기술 조사를 다음 작업에 반영합니다.
Notion에서 자료를 읽기·정리·실험·프로젝트 반영으로 구분합니다. 코드 검색은 자체 과제로 비교해 도구 구성을 선택했고, 작업 회고에서는 같은 스킬·유형의 개선 제안을 묶어 검토하고 절차를 수정했습니다. 조사와 후속 과제는 Notion에, 적용된 규칙과 구현은 Git에 남깁니다.
예를 들어, “배포가 끝났다”는 말은 이렇게 확인합니다.
새 코드를 만드는 데 성공했어도 서버에는 이전 버전이 남아 있을 수 있습니다. 그래서 배포 과정에 세 가지 확인을 넣었습니다.
- 서비스가 정상적으로 응답하는가?
- 데이터베이스에 연결할 수 있는가?
- 실행 중인 코드가 방금 배포하려던 버전인가?
이 중 하나라도 맞지 않으면 검사를 통과하지 못합니다. 개발 작업의 끝을 실제 동작으로 확인하려는 기준입니다.
이 방식에 사용한 기술과 공개 표준
- AGENTS.md: AI가 읽을 프로젝트의 개발 규칙을 적는 파일입니다.
- Agent Skills: 반복 작업의 방법과 필요한 자료를 묶어 관리합니다.
- MCP: AI와 외부 도구를 연결하는 프로토콜입니다. 현재 환경에서는 CLI·REST와 용도를 구분해 사용합니다.
모든 도구를 MCP로 만들지는 않았습니다. 또한 작업 규칙을 문서에 적는 것과 실제 실행을 차단하는 권한 기능은 구분해 관리합니다.
최근 하네스 엔지니어링 사례와도 연결됩니다. OpenAI는 에이전트가 읽을 수 있는 문서·도구와 자동 검증을, Anthropic은 구현과 평가를 나누고 결과를 반복 검증하는 실행 체계를 설명합니다. 이 프로젝트에는 업무 규모에 맞는 요소를 적용합니다. 하네스는 단일 인증 표준을 뜻하지 않습니다.
# 배포 확인 코드의 핵심 조건을 단순화한 예시 assert health["ok"] is True assert health["db_ok"] is True assert health["commit"] == expected_commit
사용 기술
Agent harness · AGENTS.md · Skills · Claude · Codex · AI 리뷰 · Git worktree · Gitea CI
기록의 범위와 확인 사항
AI 리뷰는 개발자의 판단과 테스트를 보완합니다. 실행 제한의 강제 수준은 런타임·프로젝트별로 다르며, 결함 감소율이나 시간 절감률은 별도로 측정하지 않았습니다.