웹 프로젝트용 에이전트 하네스 키트
프로젝트를 읽어 하네스 환경을 구축합니다.
레거시 SI 스택(전자정부·iBatis·Nexacro·OZ·Tibero 등)은 harness-for-K-legacy를 쓰세요.
-
프로젝트를 읽어 루트·폴더
AGENTS.md를 맞춰 씁니다
빌드 파일·설정·소스로 스택을 잡고, 계층별 규칙을 폴더마다 둡니다. -
위험한 동작은 훅이 막습니다
비밀 파일 읽기, 훅·등록 파일 수정, 위험 셸을 실행 전에 차단합니다. -
쓸수록 규칙이 남고, 쓰레기는 치웁니다
대화 교정은 memory-tidy로 공유 규칙에 올리고, 임시·세션 파일은 garbage-collector로 미리보기 후 지웁니다.
- 프로젝트 맞춤 설치 — 스택을 감지하고 쓸 기능만 고른 뒤, 원칙을 프로젝트 사실로 채움
- 루트·폴더 AGENTS.md — 폴더 지도와 계층별 규칙을 구조에 맞게 생성
- 위험 동작 차단 — 비밀·보호 경로·위험 셸을 실행 전에 막고, 보호 해제만 승인 키워드
- 검증·검토 — 변경 정적 검사(verify), 계획·diff 별도 검토(reviewbot)
- 교정 승격 — 대화·메모리 교정을 공유 지시 파일로 올림 (memory-tidy)
- 임시 파일 정리 —
.agents/tmp·세션 기록을 미리보기 후 삭제 (garbage-collector) - 이슈·로그·매퍼·DB — issue-flow, log-debug, mapper, db-mcp (상세는 아래 표)
- 원칙 → 프로젝트 채움 — 모듈은 작성 항목. 설치 때 빌드·설정·폴더에서 채움. 못 찾은 값은
미확인으로 남기고 물음 - 폴더별 지시 — 계층마다 다른 규칙을 해당 폴더
AGENTS.md로 나눔 - 기존 규칙 이전 —
CLAUDE.md·.cursor/rules등을 옮기고 빠진 규칙 점검 - 정본 하나 —
.agents/만 키우고 도구별은 링크·생성. 값은harness.toml, 비밀은 저장소 밖 - 오래 쓰기 — memory-tidy·garbage-collector
언어·프레임워크·DB에 묶인 규칙은 없습니다. 스택은 시작할 때 프로젝트에서 감지하고, 맞는 기능만 켭니다.
예시 프로젝트(Spring Boot + MyBatis 3 + Vue 3)에 설치한 결과입니다. 폴더 AGENTS.md는 켠 기능과 실제 폴더 구조에 따라 정해집니다.
my-web-project/
├─ AGENTS.md ← 스택·폴더 지도·형상관리
├─ src/main/resources/mappers/AGENTS.md ← MyBatis 3, 기존 매퍼 먼저 읽기
├─ frontend/AGENTS.md ← Vue 3 · TypeScript · Vite
└─ .agents/
├─ harness.toml ← 경로·서버·이름 (규칙 본문에는 값 없음)
├─ docs/ ← 프로젝트에서 읽어 쓴 참조 문서
├─ skills/ agents/ hooks/ mcp-servers/
└─ tmp/ ← 일회성 파일 (garbage-collector가 정리)
프론트 폴더 AGENTS.md 발췌. 아래 값은 설치 때 frontend/package.json·소스를 읽어 채운 모습입니다.
# 프론트엔드 (frontend)
- Vue 3 + TypeScript + Vite. UI는 Element Plus, 상태는 Pinia, 라우팅은 vue-router
← frontend/package.json
- API는 `frontend/src/api/`의 axios 클라이언트. Vite 개발 서버는 `/api`를 Spring으로 프록시
← vite.config.ts · src/api/
- 화면은 `views/`, 재사용 UI는 `components/`, 공유 유틸은 `utils/`
← frontend/src 폴더 구조
- 운영 배포는 `npm run build:deploy`로 Spring 정적 리소스에 포함
← package.json scripts.build:deploy- 저장소를 받습니다:
git clone https://github.com/JiniBean/harness-kit.git - 하네스를 설치할 프로젝트에서 에이전트에게 말합니다:
<받은 폴더>/start.md 를 읽고 따라 이 프로젝트에 하네스를 설치해줘 - 끝나면 「하네스 점검해줘」로 확인합니다
필요한 것: Python 3.11+(표준 라이브러리만), Windows는 개발자 모드. 자세한 절차는 start.md.
시작 전에
- 확인받기 전에는 프로젝트 파일을 쓰지 않습니다
- 코드에서 찾은 값은 묻지 않고 「이렇게 정했습니다」로 보여 줍니다. 모르면 「모름」이라고 해도 됩니다
- 계정·비밀번호 값은 묻지도 받지도 않습니다. 빈 파일만 만들어 둡니다
modules/<이름>/이 기능 하나의 설치 단위입니다.
어디에 둘지 고릅니다. 여러 프로젝트에서 같이 쓰면 전역, 그 저장소만이면 프로젝트.
| 이름 | 하는 일 | 구성 |
|---|---|---|
| agent-rules | 에이전트 응답·작업 태도 규칙 | 규칙 |
| response | 응답 형식 지적을 받으면 다시 설명하고 지적을 쌓아 둠 | 스킬 |
| ponytail | 필요한 만큼만 코드를 쓰게 함 | 스킬 5종 |
| memory-tidy | 대화에서 고쳐 준 것을 모아 규칙 파일로 올림 | 스킬 |
| garbage-collector | 에이전트 임시 파일·세션 기록을 미리보기 후 삭제 | 스킬 |
| transcript-grep | 지난 대화 기록 검색 | 도구 |
| jetbrains | IntelliJ로 코드 검색, IDE 쪽 수정·터미널 호출 차단 | 훅, 규칙 |
이 저장소에만 붙습니다.
| 이름 | 하는 일 | 구성 |
|---|---|---|
| guards | 비밀 파일 읽기·훅 수정·위험 셸을 실행 전에 차단. 보호 파일은 승인 키워드로 한 번만 풀림 | 훅 |
| verify | 바꾼 파일만 정적 검사. FAIL이 있으면 완료 선언 금지 | 스킬, 도구 restore_eol |
| reviewbot | 계획·diff를 별도 맥락에서 검토 | 에이전트 |
| db-mcp | DB 환경·쓰기 승인 정책·훅·싱글톤. JDBC는 엔진 어댑터 모듈이 담당 | 규칙, 훅, MCP 등록·싱글톤 |
| mapper | 기존 매퍼 구조를 따라 SQL 작성, 바꾼 SQL은 개발 DB에서 확인 | 규칙, 에이전트 sqlbot |
| log-debug | WAS 로그로 오류·변경 추적 (운영 로그 / 로컬 로그) | 스킬, 에이전트 logbot, 훅, MCP(FTP), 도구 |
| issue-flow | 이슈 착수→분석→계획→검증을 한 흐름으로 | 스킬, 도구 |
| comment-gen | 바꾼 코드에 변경 이력 주석 | 스킬 |
| 구성 | Claude Code | Cursor | Codex |
|---|---|---|---|
| 전역 지시 | ~/.claude/CLAUDE.md import |
User Rules 붙여넣기 | ~/.codex/AGENTS.md 링크 |
| 스킬 | 링크 | 직접 읽음 | 직접 읽음 |
| 에이전트 | 링크 | 링크 | TOML 생성 |
| 프로젝트 훅 | 생성 | 생성 | 생성 (/hooks에서 신뢰 승인 필요) |
| 전역 훅 | 병합 생성 | 병합 생성 | 생성 안 함 |
| MCP | 링크 | 링크 | config.toml 생성 |
전자정부 프레임워크, iBatis, Nexacro, OZ Report, Tibero 프로젝트는 harness-for-K-legacy를 쓰세요. 이 저장소의 내용을 모두 포함한 단독 저장소입니다.
MIT. modules/ponytail/skills/ponytail*은 DietrichGebert/ponytail(MIT)을 고친 것입니다.