이 프로젝트를 앞으로 Codex 중심의 Agent-First 개발 방식으로 장기간 개발·유지보수할 수 있도록 Harness Engineering 환경을 구축하라.
단순히 AGENTS.md 파일 하나를 만드는 작업이 아니다.
이 저장소 자체를 Codex가 다음 과정을 가능한 한 스스로 수행할 수 있는 자기 설명적(Self-describing), 자기 검증적(Self-validating), 에이전트 친화적(Agent-legible) 개발 시스템으로 만들어라.
탐색 → 이해 → 계획 → 구현 → 실행 → 테스트 → 검증 → 리뷰 → 수정 → 문서화 → 기술부채 관리
이 작업의 목적은 현재 기능 하나를 개발하는 것이 아니라,
앞으로 이 프로젝트에서 Codex가 더 정확하고, 더 독립적이며, 더 일관되게 개발할 수 있도록 개발 환경 자체를 엔지니어링하는 것
이다.
사람이 매번 다음 사항을 설명하지 않아도 되도록 만들어라.
프로젝트 구조
실행 방법
개발 방법
테스트 방법
빌드 방법
배포 방법
아키텍처 규칙
코딩 규칙
DB 구조
환경변수
외부 서비스
보안 규칙
제품 요구사항
완료 기준
장애 분석 방법
기술부채
중요한 과거 의사결정
모든 중요한 지식은 가능하면 Repository 내부의 버전 관리되는 파일에 존재해야 한다.
파일을 생성하기 전에 현재 Repository 전체를 조사하라.
다음을 확인한다.
현재 디렉터리 구조
Git 상태
현재 branch
.gitignore
기존 README
기존 AGENTS.md
기존 docs
기존 CI/CD
기존 Docker 관련 파일
기존 개발 스크립트
자동으로 탐지한다.
예:
PHP
Laravel
Node.js
Next.js
React
Vue
TypeScript
JavaScript
Python
Java
Spring
React Native
Expo
Flutter
MySQL
MariaDB
PostgreSQL
Redis
Apache
Nginx
Docker
GitHub Actions
등.
가능한 범위에서 확인한다.
OS
Runtime 버전
Package Manager
DB
웹서버
개발 서버
Build 명령
Test 명령
Lint 명령
Format 명령
추측하지 말고 실제 파일과 설정을 근거로 판단한다.
이미 존재하는 프로젝트라면 기존 구조를 먼저 존중한다.
다음 원칙을 지킨다.
기존 코드를 불필요하게 재작성하지 않는다.
기존 설정을 임의로 제거하지 않는다.
기존 CI/CD를 이유 없이 교체하지 않는다.
기존 문서를 삭제하지 않는다.
기존 배포 환경을 깨뜨리지 않는다.
기존 DB schema를 임의 변경하지 않는다.
secret을 코드에 기록하지 않는다.
실제 production 데이터에 접근하거나 변경하지 않는다.
필요한 경우 기존 구조 위에 Harness를 점진적으로 추가한다.
Codex가 Repository를 처음 보더라도 빠르게 이해할 수 있어야 한다.
다음 구조를 기본 목표로 사용하되, 프로젝트 특성에 맞게 조정할 수 있다.
/
├── AGENTS.md
├── README.md
├── ARCHITECTURE.md
│
├── docs/
│ ├── README.md
│ │
│ ├── design-docs/
│ │ ├── index.md
│ │ ├── core-beliefs.md
│ │ └── ...
│ │
│ ├── exec-plans/
│ │ ├── active/
│ │ ├── completed/
│ │ └── tech-debt-tracker.md
│ │
│ ├── product-specs/
│ │ ├── index.md
│ │ └── ...
│ │
│ ├── generated/
│ │ └── ...
│ │
│ ├── references/
│ │ └── ...
│ │
│ ├── DEVELOPMENT.md
│ ├── TESTING.md
│ ├── FRONTEND.md
│ ├── DATABASE.md
│ ├── SECURITY.md
│ ├── RELIABILITY.md
│ ├── OBSERVABILITY.md
│ ├── DEPLOYMENT.md
│ ├── QUALITY.md
│ └── TROUBLESHOOTING.md
│
├── scripts/
│ ├── setup.*
│ ├── dev.*
│ ├── test.*
│ ├── lint.*
│ ├── verify.*
│ └── ...
│
└── ...
빈 파일을 무조건 생성하지는 마라.
프로젝트에서 실제로 의미가 있는 문서와 도구만 생성한다.
AGENTS.md에 모든 정보를 집어넣지 마라.
가능하면 짧고 명확하게 유지한다.
목표는 약 100~150줄 이내다.
AGENTS.md에는 반드시 다음 내용이 있어야 한다.
이 Repository에서 Codex가 맡는 역할.
절대 위반하면 안 되는 핵심 규칙.
주요 디렉터리와 역할.
무엇을 알고 싶을 때 어떤 문서를 봐야 하는지.
예:
Architecture → ARCHITECTURE.md
Development → docs/DEVELOPMENT.md
Database → docs/DATABASE.md
Testing → docs/TESTING.md
Security → docs/SECURITY.md
Deployment → docs/DEPLOYMENT.md
Active plans → docs/exec-plans/active/
Technical debt → docs/exec-plans/tech-debt-tracker.md
Codex의 기본 작업 순서.
변경 후 실행해야 할 검증 명령.
코드와 문서가 함께 변경되어야 하는 조건.
Codex가 사람의 판단을 요청해야 하는 상황.
AGENTS.md에는 세부 설명 대신 관련 문서 링크를 사용한다.
현재 Repository를 분석하여 실제 구조를 설명한다.
추측 기반의 이상적인 아키텍처가 아니라 현재 구조 + 앞으로 지켜야 할 방향을 명확히 구분한다.
포함할 내용:
System Overview
주요 Application/Service
Module 구조
Domain 구조
Data Flow
Dependency Direction
External Services
Database
Authentication
File Storage
Background Jobs
API
Frontend/Backend 관계
Infrastructure
Deployment topology
가능하면 ASCII diagram 또는 Mermaid diagram을 사용한다.
예:
UI
↓
Application
↓
Domain
↓
Repository
↓
Database
또는 프로젝트 구조에 적절한 계층을 정의한다.
에이전트가 개발할수록 코드가 무질서해지는 것을 방지해야 한다.
프로젝트에 맞는 Architecture Invariants를 정의한다.
예:
UI에서 DB 직접 접근 금지
Controller에서 SQL 직접 작성 금지
Domain layer가 UI layer를 import하지 않음
외부 API 접근은 지정된 adapter/service를 통해 수행
환경변수 직접 참조 위치 제한
인증 로직 중앙화
공통 validation 방식 사용
공통 error handling 방식 사용
공통 logging 방식 사용
duplicate utility 생성 금지
circular dependency 금지
중요한 규칙은 문서로만 남기지 말고 가능한 경우 다음 중 하나로 기계적으로 검증한다.
ESLint
PHPStan
Psalm
custom lint
dependency test
architecture test
TypeScript compiler
unit test
shell validation
CI check
자동화 가능한 규칙과 사람이 판단해야 하는 규칙을 구분한다.
docs/design-docs/core-beliefs.md
이 프로젝트의 개발 철학을 기록한다.
최소 다음 원칙을 검토한다.
영리하지만 이해하기 어려운 코드보다 명확한 코드를 선호한다.
검증되고 예측 가능한 기술을 선호한다.
시스템 경계를 명확히 한다.
외부 입력은 신뢰하지 않고 boundary에서 검증한다.
중요한 지식은 Repository에 기록한다.
Codex가 검색하고 이해하고 검증하기 쉬운 구조를 선호한다.
누구나 같은 명령으로 개발 환경과 검증을 재현할 수 있어야 한다.
오류 발생 시 원인을 추론할 수 있어야 한다.
가능하면 변경사항을 작고 되돌릴 수 있게 만든다.
반복적으로 발생하는 리뷰 지적은 문서 또는 lint/test로 승격한다.
Codex가 개발 환경을 실행하기 위해 사람이 매번 명령을 알려줘야 하면 안 된다.
가능하면 다음 형태의 표준 명령을 제공한다.
프로젝트 기술에 맞게 실제 실행 가능한 형태로 구현한다.
예:
scripts/setup
scripts/dev
scripts/test
scripts/lint
scripts/verify
또는
npm run setup
npm run dev
npm run test
npm run lint
npm run verify
또는 프로젝트에 적절한 equivalent.
verify는 가능하면 다음을 통합한다.
format check
+
lint
+
type check
+
unit test
+
integration test
+
architecture validation
+
documentation validation
단, 지나치게 오래 걸리는 테스트는 fast/full로 분리할 수 있다.
예:
npm run verify
npm run verify:full
앞으로 모든 기능 개발과 버그 수정은 기본적으로 다음 흐름을 따른다.
1. Understand
2. Locate
3. Plan
4. Implement
5. Run
6. Test
7. Inspect
8. Review
9. Fix
10. Verify
11. Document
12. Summarize
세부적으로는:
요청의 목표와 완료 조건을 이해한다.
관련 코드, 문서, 테스트, schema를 찾는다.
작은 작업이면 내부 계획을 사용한다.
복잡한 작업이면 ExecPlan을 작성한다.
기존 아키텍처와 패턴을 따라 구현한다.
가능하면 실제 애플리케이션을 실행한다.
자동 테스트를 실행한다.
로그, UI, API response, DB 변화 등을 확인한다.
자신이 작성한 diff를 다시 검토한다.
발견한 문제를 수정한다.
전체 검증 명령을 실행한다.
필요한 문서를 업데이트한다.
변경내용과 검증결과를 사용자에게 보고한다.
Codex가 단순히 "코드를 작성했다"를 완료로 판단하지 못하게 한다.
작업 완료 기준은 기본적으로 다음과 같다.
요구사항 충족
코드 구현 완료
기존 기능 regression 없음
관련 테스트 추가 또는 수정
테스트 통과
lint 통과
type check 통과
build 성공
architecture rule 준수
오류 handling 확인
logging 필요 여부 확인
security 영향 확인
documentation 영향 확인
불필요한 debug 코드 없음
임시 파일 없음
secret 포함 없음
diff 자체 검토 완료
UI 작업이라면 추가로:
실제 화면 확인
주요 interaction 확인
loading state
empty state
error state
responsive behavior
접근성 기본사항
을 확인한다.
복잡한 기능은 일회성 채팅 계획으로 끝내지 않는다.
다음 디렉터리를 사용한다.
docs/exec-plans/active/
docs/exec-plans/completed/
복잡한 작업에는 계획 파일을 만든다.
예:
docs/exec-plans/active/user-authentication.md
ExecPlan에는 최소 다음을 포함한다.
# Goal
# Background
# Current State
# Requirements
# Non-Goals
# Architecture Impact
# Implementation Plan
# Files / Modules
# Database Changes
# API Changes
# Security Considerations
# Testing Strategy
# Validation
# Risks
# Progress
# Decisions
# Discoveries
# Final Result
작업 중 중요한 결정이나 예상과 달랐던 점을 계속 기록한다.
완료되면:
active/
→
completed/
로 이동한다.
다음 파일을 만든다.
docs/exec-plans/tech-debt-tracker.md
기술부채를 다음 정도의 필드로 관리한다.
ID
Area
Description
Severity
Reason
Impact
Suggested Fix
Status
Created
Codex가 작업 중 기술부채를 발견했다고 해서 현재 요청과 관계없는 대규모 리팩터링을 즉시 수행하지 않는다.
대신:
현재 작업에 반드시 필요하면 수정
그렇지 않으면 tracker에 기록
향후 별도 정리 작업으로 처리
한다.
문서는 코드의 부속물이 아니라 시스템의 일부다.
다음을 지킨다.
같은 내용을 여러 문서에 복제하지 않는다.
각 문서 영역에 index가 필요하면 생성한다.
고립된 문서를 만들지 않는다.
예:
DB schema 변경
→ DATABASE.md 또는 generated schema 업데이트
배포 방식 변경
→ DEPLOYMENT.md 업데이트
Architecture 변경
→ ARCHITECTURE.md 업데이트
제품 동작 변경
→ product-spec 업데이트
불필요한 "최종 수정일" 남발을 피한다.
제품 기능이 어느 정도 있는 프로젝트라면:
docs/product-specs/
를 사용한다.
각 주요 기능에 대해 다음을 기록할 수 있다.
# Feature
# Purpose
# Users
# User Flow
# Requirements
# Business Rules
# Permissions
# Edge Cases
# Error Cases
# Acceptance Criteria
Codex가 기능을 수정할 때 코드만 보고 제품 의도를 추측하지 않도록 한다.
DB를 사용하는 프로젝트라면 docs/DATABASE.md를 작성한다.
포함:
DB Engine
Version
Connection 방식
Migration 방식
주요 tables
관계
PK/FK
naming convention
transaction policy
timezone policy
charset/collation
production DB 주의사항
가능하다면 schema 문서를 자동 생성하도록 한다.
예:
docs/generated/db-schema.md
그리고 실제 DB 구조와 문서의 drift를 최소화한다.
Production DB는 명시적 허가 없이 변경하지 않는다.
docs/SECURITY.md
최소 다음을 포함한다.
Authentication
Authorization
Session
CSRF
XSS
SQL injection
Input validation
File upload
Secret management
Environment variables
Logging에서 개인정보 처리
API credential
Admin 기능
Production access
다음 원칙을 적용한다.
신뢰 경계에서 데이터를 검증한다.
외부 입력의 구조를 추측하지 않는다.
가능하면 schema validation 또는 typed boundary를 사용한다.
Codex가 오류를 고치기 위해 사람이 로그를 복사해 줄 필요가 없도록 한다.
프로젝트에서 가능한 수준의 observability를 마련한다.
최소:
structured logging
error logging
stack trace
request context
주요 service operation
external API error
민감정보는 로그에 기록하지 않는다.
환경이 허용하면:
metrics
tracing
health endpoint
performance timing
도 고려한다.
docs/OBSERVABILITY.md에는 다음을 적는다.
로그 위치
로그 확인 방법
에러 확인 방법
개발 환경 디버깅 방법
health check
metrics/traces 사용법
웹 또는 앱 UI 프로젝트라면 자동 검증 가능성을 높인다.
환경에 따라 적절한 도구를 선택한다.
예:
Playwright
browser automation
screenshot testing
React Testing Library
Expo testing
accessibility test
가능하면 핵심 사용자 흐름을 자동화한다.
예:
로그인
→ 메인 화면
→ 데이터 생성
→ 수정
→ 저장
→ 조회
Codex가 UI 변경 후 최소한 주요 흐름을 검증할 방법을 제공한다.
docs/TESTING.md
테스트를 무조건 많이 만드는 것이 목적이 아니다.
실패 비용이 높은 영역을 우선한다.
구분:
Unit
Integration
API
Database
UI/E2E
Architecture
Smoke
Regression
각 테스트의 실행 방법을 문서화한다.
특히 버그 수정 시 가능하면 다음 순서를 따른다.
1. 버그 재현
2. 실패하는 테스트 작성 또는 재현 방법 확보
3. 수정
4. 테스트 성공 확인
5. regression 확인
CI가 존재한다면 현재 설정을 분석하고 필요한 부분만 개선한다.
없다면 프로젝트 규모에 맞는 최소 CI를 고려한다.
기본적으로 확인할 항목:
install
lint
type check
test
build
architecture check
documentation check
모든 프로젝트에서 모든 항목이 필요한 것은 아니다.
실제 기술 스택에 맞춰 결정한다.
CI 오류 메시지는 가능하면 Codex가 보고 원인을 이해하기 쉽게 만든다.
문서에 다음과 같은 문장이 반복된다면:
항상 이렇게 해야 한다.
절대 이것을 하면 안 된다.
이 레이어에서는 이것을 import하면 안 된다.
이 naming 규칙을 따라야 한다.
기계적으로 확인 가능한지 검토한다.
가능하다면 lint/test/script로 만든다.
즉:
Human preference
→ documented rule
→ repeated review feedback
→ automated rule
로 발전시키는 것을 목표로 한다.
문서 자체가 오래되어 거짓 정보가 되는 문제를 방지한다.
가능하면 검증 스크립트를 만든다.
예:
깨진 내부 문서 링크 검사
존재하지 않는 경로 참조 검사
중요 문서 존재 여부
ExecPlan structure 검사
generated docs 최신 여부
orphan document 검사
필요하다면:
scripts/check-docs
또는 equivalent를 만든다.
에이전트가 빠르게 코드를 생성하면 drift가 발생한다.
이를 방지하기 위해 docs/QUALITY.md 등에 Golden Principles를 정의한다.
예:
동일 helper 중복 생성 금지
기존 shared utility 우선 검색
deprecated API 제거
dead code 제거
TODO 방치 금지
oversized file 감시
duplicate validation 제거
architecture violation 제거
문서 drift 제거
unused dependency 제거
정기적으로 수행할 수 있는 Maintenance checklist 또는 script를 제공한다.
예:
scripts/maintenance
가능하면 다음을 탐지한다.
dead code
dependency drift
duplicate utility
TODO/FIXME
large files
documentation drift
test gaps
architecture violations
앞으로 사용자 또는 리뷰에서 반복적으로 지적되는 문제가 있다면 다음 순서로 처리한다.
현재 코드만 수정.
문서 규칙 추가.
lint/test/script/architecture constraint로 승격.
목표:
한 번 배운 교훈이 Repository 전체에 누적되도록 한다.
Codex가 모든 것을 마음대로 결정하면 안 된다.
다음 상황에서는 작업을 멈추거나 사용자 판단을 요청해야 한다.
요구사항이 본질적으로 충돌
irreversible production operation
production database destructive migration
credential/secret 필요
비용이 발생하는 외부 서비스 변경
보안 정책 변경
사용자 개인정보 처리 방식 변경
대규모 architecture replacement
public API breaking change
기존 데이터를 삭제해야 하는 경우
법적/규제 판단 필요
단순 구현 세부사항 때문에 불필요하게 질문하지 않는다.
합리적인 범위의 기술적 결정은 Repository 규칙에 따라 스스로 수행한다.
하나의 작업에서 불필요하게 Repository 전체를 리팩터링하지 않는다.
원칙:
Small
Focused
Reviewable
Testable
Reversible
관련 없는 문제를 발견하면 Tech Debt Tracker에 기록한다.
현재 Git 사용 방식을 조사한다.
다음을 문서화한다.
branch 전략
commit 규칙
PR 방식
merge 방식
release 방식
deployment trigger
프로젝트에 이미 규칙이 있다면 존중한다.
없다면 최소한의 합리적 규칙을 제안한다.
Codex가 임의로 remote에 push하거나 merge하지 않는다.
사용자가 명시적으로 허용했거나 Repository 정책이 이를 허용하는 경우에만 수행한다.
.env 등을 검사하되 secret 값을 문서화하지 않는다.
필요하다면:
.env.example
을 관리한다.
.env.example에는 실제 비밀번호/API key/token을 넣지 않는다.
docs/DEVELOPMENT.md에는 필요한 환경변수의 이름과 목적만 설명한다.
새로운 script, abstraction, helper를 만들 때 다음 질문을 한다.
Codex가 이것을 검색할 수 있는가?
Codex가 사용법을 알아낼 수 있는가?
Codex가 성공/실패 여부를 확인할 수 있는가?
오류 메시지가 수정 방향을 알려주는가?
같은 작업을 재현할 수 있는가?
개발 도구의 오류 메시지는 가능한 한 actionable하게 만든다.
나쁜 예:
Architecture violation
좋은 예:
UI layer cannot import Repository directly.
Use Service layer instead.
See: ARCHITECTURE.md#dependency-rules
Harness Engineering을 한다고 해서 필요 없는 시스템을 대량 생성하지 않는다.
다음 기준을 따른다.
구현.
가볍게 준비.
구현하지 않음.
프로젝트 규모와 기술 수준에 비례한 Harness를 만든다.
작업 후 현재 프로젝트를 다음 단계 중 하나로 평가한다.
사람의 설명 없이는 Agent가 작업하기 어려움.
구조와 실행 방법이 문서화됨.
setup/test/build가 재현 가능함.
lint/test/architecture rule로 스스로 검증 가능.
Agent가 탐색→구현→검증을 상당 부분 독립적으로 수행 가능.
문서, observability, architecture enforcement, maintenance loop까지 통합되어 있음.
현재 Level과 다음 Level로 가기 위한 남은 작업을 보고한다.
무조건 Level 5라고 평가하지 않는다.
실제로 확인 가능한 근거를 사용한다.
다음 순서로 실제 작업하라.
Repository와 환경 분석.
Agent가 독립적으로 작업하기 어렵게 만드는 요소 찾기.
AGENTS.md / ARCHITECTURE.md / docs 구조 구축.
setup/dev/test/lint/verify 명령 정리.
architecture rule / lint / validation 구축.
필요한 테스트 구조 정리.
로그와 debugging 접근성 정리.
ExecPlan과 tech debt tracker 구축.
문서 구조 및 link consistency 검증.
Harness 자체를 Codex 관점에서 다시 검토.
작업을 마친 직후 스스로 다음 질문을 하라.
새 Codex session이 이 Repository를 처음 열었다고 가정한다.
AGENTS.md만 읽고 어디를 살펴봐야 하는지 알 수 있는가?
앱을 실행하는 법을 찾을 수 있는가?
테스트하는 법을 알 수 있는가?
Architecture boundary를 알 수 있는가?
DB 구조를 이해할 수 있는가?
현재 진행 중인 작업을 찾을 수 있는가?
과거 중요한 결정을 찾을 수 있는가?
오류 발생 시 로그를 확인할 수 있는가?
변경사항이 올바른지 스스로 검증할 수 있는가?
어떤 작업에서 사람에게 질문해야 하는지 알 수 있는가?
하나라도 명확하지 않으면 Harness를 개선한다.
파일 숫자를 늘리는 것이 목적이 아니다.
각 파일은 반드시 명확한 역할을 가져야 한다.
중복 문서를 생성하지 않는다.
프로젝트에 이미 동일 목적 문서가 있으면:
기존 문서 개선
>
새 문서 생성
을 우선한다.
README.md:
사람을 포함한 일반 개발자용 프로젝트 입구.
AGENTS.md:
Coding Agent가 작업하기 위한 operational map.
ARCHITECTURE.md:
시스템 구조 및 dependency map.
docs/*:
상세한 Source of Truth.
서로 같은 내용을 복붙하지 않는다.
분석 보고서만 작성하고 끝내지 않는다.
안전하게 구현 가능한 Harness 요소는 실제 Repository에 반영한다.
예:
AGENTS.md
architecture 문서
docs 구조
실행 script
test command
lint
verification
docs validation
architecture validation
tech debt tracker
product specs index
CI 개선
단, 현재 프로젝트에 맞지 않는 도구를 억지로 추가하지 않는다.
가능한 환경이라면 문서만 보고 판단하지 않는다.
다음을 실제 수행한다.
install
run
test
lint
build
verify
실패하면 원인을 분석한다.
기존 문제와 이번 Harness 변경 때문에 발생한 문제를 구분한다.
예:
setup script가 실제 실행되는가?
dev 명령이 맞는가?
test 명령이 맞는가?
verify 명령이 실제 동작하는가?
문서의 경로가 실제 존재하는가?
AGENTS.md 링크가 유효한가?
CI와 local 명령이 일치하는가?
문서에 존재하지 않는 명령을 적지 않는다.
작업이 완료되면 이 Repository는 가능한 범위에서 다음 특성을 가져야 한다.
Codex가 구조를 쉽게 찾는다.
중요한 지식이 Repository 내부에 있다.
환경과 검증 과정을 재현할 수 있다.
변경사항의 정확성을 확인할 수 있다.
오류의 원인을 추론할 수 있다.
Architecture drift를 막는 규칙이 있다.
Codex가 자신의 변경을 스스로 검증할 수 있다.
기술부채와 문서 drift를 지속적으로 관리할 수 있다.
사람의 머릿속 지식에 과도하게 의존하지 않는다.
무엇을 선택해야 할지 애매하면 다음 우선순위를 사용한다.
Correctness
↓
Security
↓
Data integrity
↓
Maintainability
↓
Agent readability
↓
Testability
↓
Observability
↓
Simplicity
↓
Performance
↓
Developer convenience
단, 실제 프로젝트 요구사항이 다른 우선순위를 명시한다면 해당 요구사항을 따른다.
다음을 하지 마라.
이유 없는 framework 교체
이유 없는 dependency 추가
거대한 AGENTS.md 작성
문서와 실제 코드가 다른 상태 방치
테스트하지 않은 코드를 완료로 선언
secret commit
production 데이터 임의 수정
임의 DB destructive migration
기존 코드 전체 재포맷
요청과 관계없는 대규모 리팩터링
TODO만 남기고 완료 선언
존재하지 않는 명령을 문서에 기록
실행하지 않은 테스트를 성공했다고 주장
확인하지 않은 내용을 사실처럼 문서화
새로운 abstraction을 만들기 전에 기존 abstraction 검색 생략
동일 utility/helper 중복 생성
사람이 읽기 어렵고 Agent도 추론하기 어려운 과도한 clever code
모든 작업 후 다음 형식으로 보고하라.
현재 기술 스택과 구조.
기존 환경에서 Agent 개발을 어렵게 하던 점.
실제 구축한 사항.
생성한 파일.
수정한 파일.
추가한 Architecture 규칙.
앞으로 사용할 주요 명령.
예:
setup:
...
development:
...
test:
...
lint:
...
verify:
...
실제로 실행한 명령과 결과.
성공/실패를 명확하게 구분한다.
아직 해결하지 않은 문제.
발견된 기술부채.
현재 Level:
Level N
근거:
...
다음 Level에 필요한 것:
...
이 Repository에서 다음으로 하면 좋은 작업.
Harness 구축 이후 앞으로 이 Repository의 모든 개발 작업에서는 기본적으로 다음 행동을 따른다.
READ
→
SEARCH
→
UNDERSTAND
→
PLAN
→
IMPLEMENT
→
RUN
→
TEST
→
REVIEW
→
FIX
→
VERIFY
→
DOCUMENT
코드 작성부터 시작하지 않는다.
먼저 Repository가 이미 알고 있는 것을 찾아본다.
기존:
code
documentation
tests
utilities
patterns
architecture
product specs
exec plans
을 검색한 후 구현한다.
앞으로 Agent가 어떤 문제에서 반복적으로 실패한다면 그것을 단순히 Agent의 실수라고 생각하지 마라.
다음을 조사한다.
필요한 정보가 Repository에 없는가?
문서가 찾기 어려운가?
Architecture가 애매한가?
검증 도구가 없는가?
오류 메시지가 불충분한가?
테스트가 부족한가?
관측 가능성이 부족한가?
작업 방법이 자동화되어 있지 않은가?
문제의 근본 원인이 Harness라면 Harness 자체를 개선한다.
즉:
Agent에게 계속 더 잘하라고 요구하지 말고 Agent가 더 잘할 수밖에 없는 환경을 만들어라.
이 Repository는 사람이 모든 세부 구현을 지시하는 프로젝트가 아니라,
사람이:
목표
제품 요구사항
우선순위
중요한 판단
을 제공하면,
Codex가:
Repository 탐색
→ 관련 지식 검색
→ 계획
→ 구현
→ 테스트
→ 실행
→ 검증
→ 자체 리뷰
→ 오류 수정
→ 문서화
를 최대한 독립적으로 수행할 수 있는 프로젝트가 되어야 한다.
이것이 이번 Harness Engineering 구축 작업의 최종 목표다.
먼저 Repository를 충분히 조사하라.
바로 파일을 대량 생성하지 말고,
현재 상태 파악
→ 기존 Harness 요소 파악
→ 부족한 부분 분석
→ 프로젝트 특성에 맞는 설계
→ 실제 구축
→ 실제 검증
→ Self Review
순서로 진행하라.
기존 코드와 프로젝트 특성을 최우선으로 존중하면서, 이 Repository에서 실질적으로 작동하는 Harness Engineering 시스템을 구축하라.