작업 시작과 반복 QA 메뉴얼

작업은 목표 → 순차 작업 → 작업별 QA → 수정·재검증 → 전체 최종 QA로 진행합니다. 처음에는 필요한 작업을 최대30개까지 정리합니다.30개를 채우는 것이 목표가 아닙니다. 이후에는 남은 작업 중1~5개를 골라 반복하며, 전체 미완료 목록은 보존합니다.

작업 메뉴얼 목록 · 새 메뉴얼 작성 · 공통 JSON 템플릿 · 보고서 작성 기준

1. 시작 전에 정할 내용

1. 요청 범위, 관련 프로젝트와 기존 QA·토론을 읽습니다. 현재 소스·설정·실행 결과로 출발 상태를 확인합니다.
2. 예상 소요 시간을 범위로 제시하고 시작 시각을 기록합니다. 확인하지 않은 내용은 미확인으로 표시합니다.
3. 목표와 전체 완료 기준을 정합니다. 구현·설치·실행·배포 중 필요한 범위를 구분합니다.
4. 하나의 메뉴얼에 순차 작업을130개 등록합니다. 작은 작업은13개로 충분합니다.
5. 각 작업에 실행 절차, 기대 결과, 반복할 QA 절차, 선행 작업, 담당·차단 사유를 기록합니다. 실행하지 않은 작업은 대기입니다.

2. 순차 실행 규칙

작업 상태는 대기 → 진행 → QA 대기 → 완료이며, 진행할 수 없는 항목은 차단입니다. 메뉴얼 상태는 준비·작업 중·QA 중·차단·완료입니다. 이는 버그 보고서의 접수·검토·진행·해결·종료와 별개입니다.

3. 소수 작업으로 반복하기

첫 계획 이후에는 최신 메뉴얼에서 남은 작업으로 소수 후속 회차 만들기를 누릅니다. 다음 회차 번호가 생성되고 첫 미완료 작업 최대5개가 선택됩니다. 전체 작업·이전 완료·실패 기록은 유지합니다. 필요하면 선택을 조정하되 선행 순서는 지킵니다.

• 이번 회차의 대상은1~5개입니다. 나머지 작업을 삭제해 완료율을 높이지 않습니다.
• 실패한 QA를 지우거나 기존 판정을 통과로 고치지 않습니다. 수정 후 실행한 QA를 새 ID로 추가합니다.
• 절차·기대값·QA·순서·의존성을 변경하면 작업 revision을 올리고 scopeChange에 이유를 적습니다. 기존 통과는 변경된 작업과 그 영향을 받는 작업을 보증하지 않습니다.
• 차단되면 이유, 필요한 자료·접근 권한, 즉시 가능한 대체 작업을 기록합니다. 실제 제한 없이 임의로 중단하지 않습니다.
• 부분 구현은 전체 완료가 아닙니다. 이번 회차를 마쳤어도 원래 목록의 미완료 작업은 다음 회차로 이어갑니다.

4. 전체 최종 QA와 종료

모든 작업이 완료되면 QA 종류를 전체 최종 QA로 선택하고 모든 작업의 현재 버전을 검사합니다. 전부 통과하고 결과·근거가 있어야 메뉴얼을 완료로 등록할 수 있습니다. 한 항목이라도 실패·미실행·차단이면 완료하지 않고 수정·재검증합니다.

실제 프로젝트 화면을 캡처·압축하여 결과 보고서에 첨부합니다. 문서 작업처럼 실행 화면이 없는 경우 사유를 기록합니다. 빌드·링크·필터·모바일·테마 등 변경 범위에 맞는 QA를 수행하고, 공개 게시가 포함되면 푸시와 배포·외부 URL 확인을 구분합니다.

이 메뉴얼은 증거의 필수 항목과 순서를 검사합니다. 작성자가 올린 실행 근거의 진위를 자동으로 증명하거나, 등록만으로 다른 프로젝트를 실행하는 기능은 아닙니다. AI는 실제 도구로 실행·검증을 계속하고 그 결과를 갱신해야 합니다.

5. 사람이 쓰는 방법

작성 폼에서 작업 메뉴얼을 고릅니다. 목표·완료 기준과 작업별 절차를 입력합니다. QA는 실제 실행 후 QA 결과 기록에서 대상 작업·판정·시각·실제 관찰·근거를 입력합니다. 이전 버전의 QA는 읽기 전용이며 새 기록으로 이어집니다. 검사·미리보기 후 GitHub에서 제출하면 공통 검사와 배포를 거칩니다. 임시저장은 현재 브라우저의 초안입니다.

토론 글의 이 논의로 작업 시작으로 들어오면 같은 프로젝트와 토론이 연결됩니다. 다른 프로젝트의 토론을 섞지 않습니다.

6. AI가 쓰는 방법

template-manual.json을 실제 작업으로 채웁니다. 원본 JSON 없이 Markdown을 직접 작성하지 않습니다. 작업·QA를 실행한 뒤 최신 JSON을 복사하여 갱신하고, 기존 Markdown·HTML을 덮어쓰지 않습니다.

node 리포트/create-report.mjs --input manual.json --dry-run
node 리포트/create-report.mjs --input manual.json
node 리포트/update-manual.mjs --from projects/프로젝트/posts/최신파일.md --input updated-manual.json --dry-run
node 리포트/update-manual.mjs --from projects/프로젝트/posts/최신파일.md --input updated-manual.json
node 리포트/build.mjs
node 리포트/verify.mjs
node --test 리포트/tests/*.test.mjs

같은 회차의 갱신은 round를 유지합니다. 다음 회차는 round를1 올리고 phase를 followup으로, focusTasks를 미완료 작업1~5개의 ID로 설정합니다. tasks에는 원래 전체 목록을 유지합니다. update-manual은 이전 메뉴얼 연결과 새 버전 파일을 만듭니다. GitHub 접수에서도 같은 JSON 계약을 사용합니다.

qaRuns는 id·kind(step/regression/final)·실제 at·summary·results를 기록합니다. 각 결과는 taskId·revision·verdict·actual·evidence·dependencies를 포함합니다. dependencies에는 QA 당시 확인한 선행 작업 ID와 revision을 기록합니다. final QA는 후속 회차의5개 제한과 관계없이 전체 작업을 검사합니다.

7. 앞으로 적용할 기준

전역 AGENTS.md에도 이 절차를 기록합니다. Codex의 지침은 작업 시작 시 로드되므로 이미 실행 중인 다른 대화가 즉시 새 지침을 읽었다고 간주하지 않습니다. 기존 작업은 해당 메뉴얼을 직접 읽고 이어갑니다. 근거: OpenAI의 AGENTS.md 공식 안내.

최종 보고에는 HTML 링크, 실제 화면과 확인 내용, 남은 사항, 제안 시간, 실제 소요·완료 시각·시간대, XERJ 사용 여부를 기록합니다.

8. 작업에서 배운 교훈을 다음 작업에 반영하기

매 작업이 끝나기 전에 재발 가능한 문제·실수, 검증된 해결 방법, 사용자 정정·지속적 선호를 검토합니다. 공통으로 재사용할 교훈은 전역 AGENTS.md의 기존 항목과 비교해 추가하거나 통합합니다. 새 교훈이 없으면 규칙을 억지로 만들지 않습니다.

1. 무엇이 문제였고 어떤 근거로 확인했는지 기록합니다. 미확인 원인을 확정 규칙으로 만들지 않습니다.
2. 다른 프로젝트에도 적용할 행동 규칙만 전역에 둡니다. 특정 제품·버전의 사실과 상세 로그는 프로젝트 지침·보고서에 남깁니다.
3. 기존 지침 전체와 의미를 비교합니다. 같은 뜻은 하나로 합치고, 서로 다른 조건·예외·사용자 승인 요구는 유지합니다.
4. 전역은 현재 유효한 규칙을 간결하게 유지하고 사건별 근거와 이전 규칙은 보고서·Git 이력에 보존합니다.
5. 설치본과 저장소를 동기화하고 해시·diff를 확인한 뒤 승인된 범위에서 커밋·푸시합니다. 이미 실행 중인 다른 대화가 자동으로 갱신됐다고 가정하지 않습니다.

결과 보고에는 교훈 검토: 추가 / 통합 / 변경 없음, 근거·적용 범위·유지한 조건을 적습니다. 지침·문서만 수정해 실제 프로그램 실행 화면이 없는 작업은 그 사유를 기록하고 장식 이미지를 만들지 않습니다.

작업별 실제 화면 대조

각 작업의 선택 항목 visualEvidence에 원본(reference)과 실제 실행(current) 이미지를 붙일 수 있습니다. 같은 프로젝트의 ../assets/ 안에 실제 이미지를 보관하고 image, caption, 선택 사항인 공식 source HTTPS 주소를 기록합니다. 탭 전체·부분 메뉴·구형 버전 등 원본 범위와 실제 실행 버전을 설명에 명시합니다. 없는 화면은 만들어 넣지 않습니다. 화면 촬영은 기능 실행 전체의 통과를 대신하지 않습니다. blocked는 실제 외부 제한으로 실행할 수 없을 때만 사용하며 미구현은 실패, 미실행은 not_run으로 구분합니다.

최종 보고는 푸시·공개 배포 후 웹 링크로 제출

1. 원본 JSON·Markdown에서 HTML 보고서를 만들고 필요한 실제 화면·첨부를 중앙 리포트 폴더에 저장합니다.
2. 이번 보고서와 관련 첨부만 대조해 커밋·푸시합니다. 로컬 생성이나 푸시만으로 전달을 완료하지 않습니다.
3. GitHub Actions·Pages의 해당 버전 배포 성공을 확인합니다. 실패하면 로그를 확인하고 수정·재배포합니다.
4. 개별 보고서의 공개 HTTPS URL에서 실제 본문과 필요한 첨부가 인증 없이 열리는지 확인합니다. 오래된 버전이나 메인 목록만 열린 것으로 대체하지 않습니다.
5. 최종 채팅에는 핵심 상태와 확인된 개별 보고서의 공개 링크를 반드시 제공합니다. 로컬 경로·file://·localhost는 최종 보고서 전달 수단으로 사용하지 않습니다.

푸시·배포·외부 접근이 막혔으면 구현 완료 여부와 보고서 공개 미완료를 구분합니다. 검증하지 않은 웹 링크를 만들어 완료라고 안내하지 않고, 실제 오류와 남은 공개 단계를 기록하며 해결을 계속합니다.

이미지 작업은 Affinity 필수

로고·아이콘·배너·썸네일·일러스트·합성·보정·자르기·리사이즈·내보내기는 실제 Affinity에서 작업합니다. CLI·MCP·SDK는 실제 앱에 연결해 처리할 때만 Affinity 사용으로 인정합니다. 직접 SVG·Canvas·Python 등으로 그림을 만들거나 다른 도구로 임의 대체하지 않습니다. 사용자가 다른 도구를 명시적으로 허용한 경우만 예외입니다.

연결·기능 문제가 있으면 오류를 확인하고 전용 CLI·MCP·SDK 복구를 먼저 검토합니다. 실제 제한으로 대체가 필요하면 구체적인 방식에 대한 사용자 승인을 받습니다. 열려 있는 문서를 임의로 수정하거나 다른 작업 중인 사용자의 화면 포커스를 빼앗지 않습니다.

목적·레퍼런스·실제 출력 크기·해상도·색상·글꼴을 정하고 편집 가능한 Affinity 원본과 결과물을 해당 프로젝트에 보관합니다. 구성·정렬·가독성·윤곽·색상·여백을 실제 크기로 검토하고 품질이 부족하면 Affinity에서 수정·재출력합니다. Affinity로 처리했다는 사실만으로 품질 통과로 표시하지 않습니다.

게임·프로그램·에디터의 증거 화면은 해당 프로그램에서 실제로 캡처합니다. 캡처 편집·최적화도 Affinity로 수행하며 사실을 왜곡하거나 가짜 화면으로 대체하지 않습니다. 지침·문서만 바꾸는 작업은 불필요한 이미지를 만들지 않습니다.

간결한 보고와 변경 전·후 비교

보고서는 무엇이 달라졌고, 확인됐으며, 무엇이 남았는지 먼저 보여줍니다. 핵심 결과는 1~3문장, 변경점은 필요한 항목만 짧게 적습니다. 검증은 실행한 검사와 결과·제한을 남기고 긴 로그와 상세 절차는 근거·메뉴얼 링크로 분리합니다. 필수 시간·검색·교훈 기록은 유지하되 같은 설명을 반복하지 않습니다.

한 글은 한 주제나 연관된 변경 묶음으로 작성합니다. 독립적인 기능·수정이 섞이거나 설명이 길면 글을 나눠 서로 링크합니다. 한 페이지에 맞추려고 글자·이미지를 줄이거나 빽빽하게 배치하지 않습니다. 기존 글도 수정할 때 같은 기준을 적용하며 과거 근거와 이력은 보존합니다.

화면에 드러나는 수정은 변경 전 1장 이상 + 변경 후 1장 이상을 반드시 첨부합니다. 작업 전에 기준 화면부터 확보하고 가능한 한 같은 상태·배율로 촬영합니다. 각 사진 아래에 변경 위치와 전후 차이를 한 문장으로 설명합니다. 가능하면 실제 Affinity에서 테두리·화살표·번호로 위치를 표시하고 편집 원본을 보관합니다. 표시가 내용·오류를 가리거나 상태를 왜곡해서는 안 됩니다.

전 화면이 없으면 재현 가능한 이전 버전에서 촬영합니다. 불가능한 경우 전 화면 미확보 사유를 명시하고 전후 비교 검증 완료로 쓰지 않습니다. 화면 변화가 없는 코드·지침·문서 작업은 불필요한 이미지를 만들지 않고 diff·실행 검증 등으로 증명합니다. 캡처 압축·하이라이트 등 편집도 Affinity 필수 규칙을 따릅니다.

전후 비교는 가능하면 짧은 GIF를 우선 보여줍니다. 실제 전·후 화면 또는 수정 동작을 사용하고 전·후 표시와 충분한 확인 시간을 둡니다. 정지 전후 사진도 함께 제공합니다. 빠른 점멸을 피하고 가독성을 유지하며 길이·해상도·프레임 수를 줄여 용량을 최적화합니다. GIF 편집·최적화·내보내기는 실제 Affinity 기능을 확인한 뒤 처리합니다. 지원하지 않으면 제한을 명시하고 정지 비교를 제공하며 다른 도구로 임의 대체하지 않습니다.

Affinity 저장 권한 오류는 프로젝트 범위에서 복구

저장·내보내기 권한 오류는 같은 명령만 반복하지 않습니다. 실제 오류와 대상 프로젝트의 해석된 경로·실행 계정·소유자·ACL·Affinity 파일 접근 허용 범위를 확인하고, 확인된 원인에 맞춰 직접 복구합니다. Windows ACL 문제라면 기존 ACL을 보존한 뒤 해당 사용자 SID의 수정·쓰기와 상속을 복구합니다. 원인이 확인된 프로젝트 하위 경로만 다루며 드라이브 전체·다른 프로젝트·Everyone 전체 제어·보안 기능 해제로 넓히지 않습니다. Affinity 허용 폴더 문제라면 해당 프로젝트만 허용합니다.

복구 뒤 임시 파일 생성·수정·삭제, 실제 Affinity 편집 원본 저장·재열기와 출력 파일을 확인할 때까지 진행합니다. 관리자 권한 등 실제 제한이 있으면 정확한 오류와 필요한 최소 조치를 기록하며, 단순 쓰기 테스트만으로 Affinity 저장까지 성공했다고 쓰지 않습니다.

수정 범위별 전후 화면과 핵심 요약

결과 보고 전에 수정 항목마다 실제 전·후 스크린샷을 촬영하고 첨부합니다. 여러 화면·기능·탭·상태를 수정했다면 각각 확인할 수 있도록 필요한 만큼 전후 쌍을 늘립니다. 대표 화면 한 쌍으로 나머지 변경의 증거를 대신하거나 촬영 수를 임의로 제한하지 않습니다.

작업 전 기준 화면부터 확보하고 동일한 조건의 수정 후 화면과 짝지어, 항목명·전/후·변경 위치·달라진 점을 짧게 적습니다. 보고 직전 수정 목록과 이미지 쌍을 대조해 빠진 항목을 확인합니다. 가능한 하이라이트와 편집·압축은 기존 Affinity 기준을 따르며, 실제 실행 화면이 없는 문서 작업 등 기존 예외와 미확보 사유 기록 의무는 유지합니다.

본문 첫 1~3문장에 핵심 결과와 사용자에게 달라진 점을 요약하고, 변경점·검증·남은 사항을 짧은 항목으로 씁니다. 긴 로그·세부 과정은 근거 링크로 분리하고 내용이 많으면 주제별 보고서로 나눕니다. 사진은 판독할 크기로 배치하고 각 전후 쌍의 설명을 가까이 둡니다.

보고서에 작업 대화 기록 함께 남기기

앞으로 각 결과 보고서에는 사용자 요청·추가 지시·정정·승인, AI의 주요 답변과 결정 이유·미해결 질문을 실제 발언 순서대로 기록합니다. 발언자 / 핵심 내용 / 반영 결과를 짧게 적고, 판단에 필요한 핵심 문구는 원문 인용으로 남깁니다. 요약을 인용문처럼 꾸미거나 대화·승인·시각을 추측해 채우지 않습니다. 실제 발언 시각이 확인되지 않으면 미기록으로 표시합니다.

공통 H2 순서는 유지합니다. JSON의 changes 등 해당 본문 안에 H3 ### 대화 기록을 넣어 요약하고, 길면 projects/<project>/assets/conversations/의 별도 기록 파일이나 같은 프로젝트의 글로 분리해 링크합니다. 본문은 결과·변경·검증·남은 사항을 먼저 보여줍니다.

인증정보·개인정보·작업과 무관한 개인 대화·비공개 내용은 게시 전에 제외하거나 마스킹합니다. 보고용으로 정리한 작업 대화 기록을 남기며 원본 세션 로그 전체를 그대로 올리지 않습니다. 대화에 접근하지 못했다면 확인한 범위와 누락을 명시합니다.