V4TIME/V4SKILL

체계적 에이전트 — 규율 있는 코딩 관행

사용 시기

모든 코딩 작업, 수정, 디버깅 세션 또는 구현 작업. 이 스킬은 코드 변경에 접근하는 방법에 대한 기본 운영 체제로, 선택적 추가 기능이 아닙니다.

모든 코드 관련 작업에 자동으로 호출됩니다. 사용자가 코드를 변경, 추가, 수정 또는 빌드하도록 요청하면 이 스킬을 따르십시오.

핵심 규칙

1. 프로젝트에 대해 절대 가정하지 마세요

파일을 건드리기 전에 실제로 무엇이 있는지 반드시 알아야 합니다. 파일을 읽으세요. 현재 상태를 확인하세요. "있어야 할" 것에 대한 기억에 의존하지 마세요 — 읽으세요.

구체적인 조치:

• 변경하려는 파일을 read_file로 읽고, 주변 컨텍스트도 포함하세요
• 관련 코드, 임포트, 함수 호출자 및 참조를 search_files로 검색하세요
• 서버가 실행 중이고 엔드포인트가 응답하는지 테스트 변경 사항을 확인하기 전에 확인하세요
• 설정 파일에 실제로 생각하는 내용이 포함되어 있는지 확인하세요

2. 변경하기 전에 관련 파일을 검사하세요

맹목적으로 패치를 적용하지 마세요. 편집하려는 모든 파일에 대해:

1. 전체 파일(또는 충분한 컨텍스트가 있는 관련 섹션)을 읽으세요
2. 현재 구조, 임포트, 종속성 및 패턴을 이해하세요
3. 무엇을 변경해야 하는지와 그 이유를 식별하세요
4. 그런 다음에만 패치 또는 편집을 작성하세요

패치 시: old_string에 고유하게 일치하도록 충분한 주변 컨텍스트를 포함하세요. 여러 위치와 일치하는 패치는 잘못된 위치에 적용됩니다.

큰 파일을 읽을 때: 오프셋/제한을 사용하여 점진적으로 읽으세요. 하나의 함수만 필요한 경우 1600줄 파일을 한 호출에 로드하려고 하지 마세요 — 하지만 변경 중인 함수는 전체(서명 및 모든 호출 사이트 포함)를 반드시 읽으세요.

3. 실행 전에 간결한 계획을 세우세요

사소하지 않은 모든 코딩 작업 전에 다음에 답하는 간단한 계획(3-7개의 글머리 기호)을 작성하세요:

• 어떤 파일을 변경해야 하는가
• 각 변경 사항이 무엇을 하는가 (변경당 한 줄)
• 변경 사항이 어떤 순서로 이루어져야 하는가
• 어떤 검증 단계가 성공을 확인할 것인가

예시:

계획:
1. app.py 762-770줄 읽기 — _get_hermes_response 서명 확인
2. image_url: str = None 매개변수를 서명에 추가
3. 함수 내 모든 5개의 _call_api 호출에 image_url=image_url 추가
4. chat()에서 _get_hermes_response로 image_url 전달
5. 서버 재시작, curl 이미지 페이로드로 테스트

계획을 말할 때까지 코딩을 시작하지 마세요. 계획이 잘못되면 코드도 잘못됩니다.

4. 도구를 사용하여 추측 대신 주장을 검증하세요

코드베이스에 대한 모든 주장은 기억이 아닌 도구 출력에 의해 뒷받침되어야 합니다.

주장	검증 방법
"파일 X에 함수 Y가 있다"	grep -n 또는 read_file로 파일 읽기
"서버가 실행 중이다"	curl로 헬스 엔드포인트 확인
"변경 사항이 작동한다"	실제 테스트를 실행하고, 가정하지 마세요
"API 키가 구성되어 있다"	storage/apis.json 읽기
"CSS가 로드되었다"	curl로 정적 파일을 확인하고 HTTP 상태 확인
"패치가 올바르게 적용되었다"	새 텍스트를 grep하거나 해당 영역 read_file

"작동해야 한다"고 말하는 응답을 실제로 작동하는지 확인하지 않고 작성하지 마세요.

5. 모든 중요한 수정 후에는 결과를 테스트하거나 검사하세요

모든 코드 변경 후:

1. 구문 검사: python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" — 재시작 전에 반드시 통과해야 함
2. 서버 재시작 변경 사항이 app.py에 있는 경우
3. 변경된 동작 테스트:
   • API 변경의 경우: 대표적인 페이로드로 엔드포인트를 curl
   • 프론트엔드 변경의 경우: 정적 파일이 제공되는지 확인(HTTP 200)
   • 설정 변경의 경우: 설정 파일을 읽어 확인
4. 실제 출력 확인 — 예상한 것이 아니라 도구가 반환한 것

변경 사항은 테스트 결과를 확인할 때까지 완료되지 않습니다. "작동한다고 생각한다"는 검증이 아닙니다.

6. 무언가 실패하면 다른 접근 방식을 시도하기 전에 실제 오류를 진단하세요

테스트가 실패하거나 패치가 적용되지 않을 때:

1. 실제 오류 메시지를 읽으세요 — 그대로 복사하세요. 요약하지 마세요.
2. 근본 원인을 식별하세요 — 구체적으로 무엇이 실패했고 왜 그런지
3. 수정에 대한 가설을 세우세요
4. 도구로 가설을 테스트하세요 — 다른 패치를 시도하지 마세요
5. 수정이 작동하지 않으면 오류를 다시 읽으세요 — 변경되었거나 잘못 읽었을 수 있습니다

피해야 할 안티 패턴:

• 작동 여부를 확인하지 않고 연속으로 세 가지 다른 패치 적용
• 오류 텍스트를 읽지 않고 오류 유형에 따라 수정 추측
• 오류가 한 특정 위치에 있을 때 관련 없는 코드 변경
• 서버 시작을 방해하는 구문 오류를 수정하지 않고 서버 재시작

7. 결과가 검증될 때까지 작업이 완료되었다고 말하지 마세요

작업은 다음 조건이 충족될 때만 완료됩니다:

• 코드 변경이 작성되고 구문 검사 완료 ✓
• 서버가 새 코드로 실행 중 ✓
• 변경된 동작이 예상 결과를 생성함(도구 출력으로 검증됨) ✓
• 이를 증명하는 특정 테스트/명령/출력을 가리킬 수 있음 ✓

패치가 성공적으로 적용되었다고 해서 "완료"를 선언하지 마세요. 패치가 잘못된 위치에 적용되거나, 구문 오류를 도입하거나, 실제로 문제를 해결하지 못할 수 있습니다. 패치 적용은 검증의 1단계이지 끝이 아닙니다.

절차

모든 코드 변경:

1. 읽기 — 변경할 파일을 검사하세요. 현재 상태를 알아야 합니다.
2. 계획 — 3-7개의 글머리 기호 작성: 어떤 변경, 어떤 순서, 어떻게 검증할지
3. 변경 — 편집을 수행하세요. 여러 파일 작업의 경우 한 번에 하나의 원자적 변경.
4. 구문 검사 — py_compile 또는 동등한 도구. 진행하기 전에 오류 수정.
5. 재시작 — 실행 중인 서버가 새 코드를 필요로 하는 경우.
6. 테스트 — curl, 실행 또는 검사. 실제 동작이 의도와 일치하는지 확인.
7. 보고 — 무엇이 변경되었는지, 테스트 결과는 무엇인지, 검증 여부를 명시.

디버깅:

1. 재현 — 실제 오류 출력을 얻으세요. 그대로 복사하세요.
2. 위치 파악 — 코드에서 오류가 발생한 위치를 찾으세요. grep, read_file, 스택 추적.
3. 이해 — 실패한 코드를 전체적으로 읽으세요. 무엇을 하는지 추측하지 말고 읽으세요.
4. 가설 세우기 — 이 특정 오류를 해결할 구체적인 변경 사항은 무엇인가?
5. 수정 — 근본 원인을 해결하는 최소 변경을 수행하세요.
6. 검증 — 실패한 테스트를 다시 실행하세요. 오류가 사라졌고 다른 것도 깨지지 않았는지 확인.
7. 여전히 실패하면 — 1단계로 돌아가세요. 오류가 변경되었을 수 있습니다. 다시 읽으세요.

여러 단계로 구성된 작업:

• 한 번에 한 단계씩 수행하세요. 다음 단계로 넘어가기 전에 각 단계를 검증하세요.
• 3단계가 2단계의 정확성에 의존하는 경우, 먼저 2단계를 검증하세요.
• 검증되지 않은 변경 사항을 일괄 처리하지 마세요 — 2단계가 잘못되면 3단계의 "수정"도 잘못됩니다.

함정

• 조치 없이 같은 줄을 반복해서 읽기. 함수를 3번 읽었는데 편집하지 않았다면 막힌 것입니다. 변경을 수행하거나 방해하는 요소를 명시하세요.
• 파일 내용 추측하기. 항상 파일을 읽으세요. 여러 패치 후에는 "거기에 있던" 것에 대한 기억이 신뢰할 수 없습니다.
• 구문 검사 건너뛰기. 패치가 깔끔하게 적용되어도 구문을 깨뜨릴 수 있습니다. 항상 확인하세요.
• 재시작 없이 테스트하기. app.py가 변경되면 실행 중인 서버는 이전 코드를 가지고 있습니다. 테스트 전에 재시작하세요.
• 패치 성공으로 완료 선언하기. "패치 적용됨" ≠ "작업 완료." 동작을 검증하세요.
• 오류 메시지를 읽지 않기. 오류 텍스트는 무엇이 실패했는지 알려줍니다. 읽으세요. 오류 유형만으로 추론하지 마세요.
• 과도한 패치. 특정 문제를 해결하는 최소 변경을 적용하세요. 한 줄이 잘못되었다고 전체 함수를 다시 작성하지 마세요.

검증 체크리스트

코딩 작업 완료를 보고하기 전에 각 항목을 확인하세요:

• 파일을 변경 전에 읽음(현재 상태 파악)
• 계획 작성(어떤 변경, 어떤 순서)
• 구문 검사 통과(py_compile 또는 동등한 도구)
• app.py가 변경되면 서버 재시작
• 테스트 실행(curl, 실행 또는 검사) — 실제 출력 확인
• 출력이 예상 동작과 일치
• 새로운 오류 도입되지 않음

이 스킬이 다른 스킬과 상호작용하는 방식

• 이것은 기준선 스킬입니다 — 다른 스킬이 활성화되어 있어도 모든 코딩 작업에 적용됩니다.
• test-driven-development가 활성화되면 TDD가 테스트 방법이 됩니다. 이 스킬은 전체적인 규율을 관리합니다.
• systematic-debugging이 활성화되면 디버깅에 자체 상세 절차가 있습니다. 이 스킬의 규칙 6은 여전히 적용됩니다.
• spike가 활성화된 경우(일회용 실험), "변경 전 검사" 및 "변경 후 확인" 규칙은 여전히 적용됩니다. 스파이크는 지저분할 수 있지만 부주의해서는 안 됩니다.
• human-first-ui 또는 webmxerz가 디자인 작업을 위해 활성화된 경우, 이 스킬은 디자인을 구현하는 코드 변경을 관리합니다. 디자인 스킬은 무엇을 구축할지 알려주고, 이 스킬은 어떻게 안전하게 구축할지 관리합니다.
• 스킬은 skill_view(name)을 통해 요청 시 로드됩니다 — 지속적으로 활성화된 백그라운드 프로세스가 아닙니다. 스킬은 로드된 세션 턴 동안에만 활성화됩니다. 디자인 지원 스킬(webmxerz, human-first-ui)은 특정 UI 작업에 대해 참조됩니다. 이 스킬은 디자인을 구현하는 코드 작업의 기준선으로 유지됩니다.