Tracefolio 게시물 작성 가이드

작업 시작 전에 작업 시작·반복 QA 메뉴얼을 읽고 작업 메뉴얼을 등록·갱신합니다. 최초 필요한 작업은 최대30개, 이후에는1~5개씩 반복하며 전체 미완료 목록과 QA 이력을 보존합니다. 메뉴얼 JSON 템플릿을 사용합니다.

작성 기준 v2 — 사람과 AI가 같은 폼·JSON·검사로 작성합니다. 프로젝트별 결과 보고서와 버그 보고서를 같은 기준으로 관리합니다. 글마다 별도 HTML·CSS를 만들지 않습니다.

보고서 작성 폼 · 5단계와 공통 JSON 설명 · 결과 JSON 템플릿 · 버그 JSON 템플릿 · JSON 스키마

1. 분류와 단계

GitHub의 버그 이슈를 다시 열면 검토 단계로 돌아갑니다. 해결·종료에는 수정 내용과 검증 근거가 필요합니다. 과거 글도 원문 근거를 검토해 단계를 부여합니다. 수정·검증 근거가 있으면 해결, 미판정·중단·검증 대기는 검토, 수정 중인 범위가 남으면 진행으로 분류하며 완료 문구만으로 종료하지 않습니다. 원문·해시와 판단 근거는 별도 단계 검토 이력으로 보존합니다.

2. 사람이 작성하는 방법

사이트의 보고서 작성 폼에서 프로젝트·분류와 실제 내용을 입력합니다. 검사·미리보기는 공통 데이터와 Markdown을 보여줍니다. 공개 내용을 확인한 뒤 GitHub에서 최종 제출합니다. GitHub 로그인이 필요하고 등록 이후 자동 검사·배포를 거쳐 사이트에 표시됩니다. 브라우저 임시저장은 그 기기에만 남는 초안이며 사이트 등록이 아닙니다.

3. AI가 작성하는 방법

결과·버그 JSON 템플릿을 실제 값으로 채워 같은 검사 함수를 호출하는 CLI를 사용합니다. 원본 JSON을 보존하지 않고 Markdown을 직접 만들어 필수 항목을 우회하지 않습니다.

node 리포트/create-report.mjs --input report.json --dry-run
node 리포트/create-report.mjs --input report.json
node 리포트/build.mjs
node 리포트/verify.mjs
node 리포트/verify-migration.mjs
node 리포트/verify-editorial.mjs
node --test 리포트/tests/*.test.mjs

GitHub 접수를 사용할 때는 같은 JSON을 tracefolio:v2 표시와 json 코드 블록으로 등록합니다. 사이트 폼도 같은 내용을 만듭니다. 구체적인 표시와 이벤트 처리는 공통 등록 설명을 참고하세요.

4. 반드시 기록할 내용

5. 생성되는 게시물 형식

프로젝트·보고서 분류·단계·우선순위
제목 / 요약 / 상태 / 날짜·버전
작업 결과
변경 내용 (버그: 재현 조건·순서·기대·실제·원인 포함)
검증
남은 사항
작업 시간
등록·상태 변경 이력

하나의 JSON 계약에서 format: tracefolio-v2 Markdown을 생성합니다. 빌드는 보존된 JSON을 재검사하고 Markdown이 같은 데이터에서 생성됐는지 확인합니다. 본문 H1 제목을 중복 작성하지 않습니다. 프로젝트별 최근 글을 참고하되 과거 v1·legacy 예외를 새 글 작성에 사용하지 않습니다.

6. 파일과 버전

projects/<project>/posts/       생성된 Markdown
projects/<project>/reports/     생성된 HTML
projects/<project>/assets/      JSON·로고·첨부
projects/<project>/originals/   원문 백업

GitHub로 접수한 글은 TF-이슈번호로 표시됩니다. 수정 시 새 버전과 단계 이력을 보존하고 목록에는 최신 버전만 표시합니다. 오래된 기록·이전 버전·원문은 지우지 않습니다. 제품 버전과 문서 버전은 구별합니다.

7. 읽기와 공개 기준

• 한 문단에 하나의 결과나 근거를 쓰고 존댓말을 사용합니다.
• 표는 비교·매핑·검사 결과에 사용하고 긴 코드는 코드 블록에 넣습니다.
• 이미지에는 실제로 확인할 수 있는 내용을 설명하는 alt 문구를 씁니다.
• 첫 화면에 전체 로그·파일 목록·해시를 나열하지 않고 필요한 근거와 링크를 둡니다.
• raw HTML, script, iframe, 실행 URL을 사용하지 않습니다.
• 인증정보·개인 로그·세션 기록·비공개 데이터를 공개 등록하지 않습니다.
• 원문 시점의 테스트를 이번 작업의 검증으로 보고하지 않습니다.
• 푸시와 배포 성공을 구분하고 공개 URL까지 확인한 뒤 완료라고 안내합니다.

과거 v1·legacy 글은 읽기 호환을 유지합니다. 이 글들의 숫자와 판단은 원문 시점의 기록이며 현재 상태를 새로 증명하지 않습니다.

프로젝트 소항목

사이드바의 턴룸 아래 공통·통합 작업(turnroom), Pixora(pixora), Design Data Table(designdatatable)을 소항목으로 관리합니다. 상위 항목은 세 제품의 글을 합쳐 보여주며, 소항목은 해당 제품만 보여줍니다. 묶음 정의는 project-groups.json에서 관리합니다.

사람은 작성 폼의 턴룸 그룹에서 소항목을 고릅니다. AI는 기존 JSON project에 해당 소항목 ID를 기록합니다. 상위 묶음 ID인 products 또는 collection:products를 보고서 project로 쓰지 않습니다. 프로젝트별 폴더·원본·이전 링크는 유지합니다. 소항목에서 결과·버그 분류와 버그 5단계를 함께 필터링할 수 있습니다.

결과 이미지 필수 첨부와 압축

• 프로젝트 작업 결과를 보고할 때는 해당 프로젝트의 실제 실행 화면을 직접 캡처해 채팅과 HTML 보고서 양쪽에 첨부한다. 게임은 실제 게임 화면, 프로그램은 실제 프로그램 화면, 에디터·플러그인은 해당 에디터에서 작업 결과가 보이는 화면을 사용한다. 수정한 기능·상태·오류가 실제로 드러나는 장면을 고르고 무엇을 확인한 화면인지 설명한다. 이미지 첨부 의무를 채우기 위한 요약 카드·안내 도식·장식 이미지·가짜 화면·AI 생성 이미지를 만들어 대체하지 않는다. 지침·문서 수정 등 실제 실행 화면이 없는 작업은 이미지를 억지로 만들지 않고 그 사유와 확인한 변경 내용을 텍스트로 기록한다. 실제 화면 캡처가 필요한데 제한된 경우에는 캡처 미실행과 이유를 명시하고 화면 검증까지 완료했다고 보고하지 않는다.
• 보고용 이미지는 업로드 전에 불필요한 여백·중복 화면·메타데이터를 제거하고 필요한 해상도로 줄여 가독성을 유지하는 범위에서 최대한 압축한다. 래스터 이미지는 WebP를 우선 검토하고, 작은 글자·선·투명도가 손상되면 무손실 WebP·최적화 PNG 또는 SVG를 사용한다. 이미지당 200KB 이하를 우선 목표로 하되 글자 판독과 검증 근거 보존을 우선한다. 압축 전후 바이트·크기·실제 표시 품질을 확인하며, 원본은 필요 시 로컬에 보존하고 압축본만 첨부·게시한다.

이미지는 projects/<project>/assets/에 저장하고 JSON의 outcome·changes·verification 본문에서 ![확인한 내용](../assets/압축파일.webp)로 첨부합니다. 사람의 작성 폼과 AI JSON 모두 같은 Markdown 이미지 문법을 사용합니다. 로컬 파일 경로를 공개 이미지 주소로 쓰지 않습니다. 채팅에도 실제 압축 이미지와 HTML 보고서 링크를 함께 제공합니다.

QA 토론 · 개선 제안 · 새 기능 요청

보고서 상세의 토론 시작은 프로젝트와 원본 보고서를 자동 연결합니다. QA 토론 메뉴에서는 프로젝트·종류·논의 상태·검색으로 글을 찾고 원본 QA와 함께 다시 읽을 수 있습니다. 작성은 사이트 폼 또는 토론 JSON 템플릿과 같은 create-report.mjs --input 절차를 사용합니다. GitHub에서 최종 등록해야 공개 사이트에 반영되며 로그인 전의 미리보기·초안 저장은 등록이 아닙니다.

• kind: discussion, type: 토론. 결과·버그 수에는 섞지 않고 QA 토론 목록에 표시합니다.
• topic: qa(QA 토론), gap(부족한 점), proposal(개선 제안), feature(새 기능 요청).
• discussionState: open(논의 중), considering(검토 중), accepted(채택), deferred(보류), implemented(반영 완료).
• relatedReport: 같은 프로젝트의 실제 HTML 경로입니다. 예: projects/프로젝트ID/reports/파일.html. qa 종류에는 필수이며 다른 제안은 독립 글로도 작성할 수 있습니다.
• replyTo: 후속 글을 쓸 때 원본 토론의 HTML 경로를 기록합니다. 같은 프로젝트·같은 QA의 토론만 연결하며 순환 참조를 허용하지 않습니다.
• outcome에는 관찰 사실과 논의할 질문, verification에는 QA 근거·실제 화면, changes에는 제안·대안·기대 효과, decision에는 결정 이유·담당자·후속 작업, remaining에는 열린 질문을 기록합니다. 제안과 검증된 사실을 구분합니다.
• 채택·보류·반영 완료에는 decision이 필수이며, 반영 완료에는 verification도 필수입니다. 승인받지 않은 제안을 채택·구현 완료로 표시하지 않습니다.

토론의 H2는 토론 내용 → QA 근거와 맥락 → 제안 및 대안 → 결정과 후속 작업 → 작업 시간입니다. JSON 원본·Markdown·생성 HTML은 기존과 같이 프로젝트별 assets/submissions, posts, reports에 보존합니다. GitHub로 등록한 글의 수정 이력은 버전별로 보존하고 목록에는 같은 이슈의 최신 글만 표시합니다. 후속 글 쓰기는 별도 글을 남겨 결론·보류 이유·새 제안의 맥락을 이어갑니다. GitHub 댓글은 토론 글의 외부 링크에서 볼 수 있으며 사이트에 자동 복제하지 않습니다.

작업 메뉴얼 형식

kind: manual은 결과·버그·토론과 별도 목록으로 관리합니다. 목표와 완료 기준 → 순차 작업 메뉴얼 → QA 반복 기록 → 남은 작업과 다음 반복 → 작업 시간 순서의 공통 H2를 사용합니다. 완료는 모든 작업의 결과·현재 버전 QA 통과와 전체 최종 QA가 필요합니다. 작업 메뉴얼의 상태는 버그 처리5단계와 구분합니다.

교훈 검토와 지침 반영

작업 종료 전 확인한 문제·재발 방지·사용자 정정을 검토하고 결과 보고에 교훈 검토: 추가 / 통합 / 변경 없음과 근거·적용 범위를 적습니다. 검증된 공통 행동 규칙은 전역 AGENTS.md에 반영하고 같은 의미의 항목은 통합합니다. 프로젝트·버전에 국한된 상세는 해당 프로젝트에 남기며 사용자 조건·예외·승인·검증 의무를 삭제하지 않습니다. 작업 메뉴얼의 교훈 반영 절차를 따릅니다.

최종 결과 보고는 반드시 중앙 저장소에 커밋·푸시하고 공개 배포된 개별 HTML·첨부의 외부 접근을 확인한 뒤 HTTPS 웹 링크로 제출합니다. 로컬 파일·file://·localhost 링크만으로 최종 보고를 끝내지 않습니다. 푸시·배포 실패는 보고서 공개 미완료로 구분합니다. 공개 보고 절차를 따릅니다.

이미지 제작·편집·보정·자르기·리사이즈·내보내기는 실제 Affinity 사용이 필수입니다. 직접 그림 코드나 다른 도구로 임의 대체하지 않습니다. 편집 가능한 원본과 실제 출력 품질 검토를 남기고, 실행 증거 화면의 내용은 왜곡하지 않습니다. Affinity 필수 작업 절차를 따릅니다.

단일 보고서의 TC별 원본 대조

여러 탭이나 기능을 하나의 결과 보고서에서 검증할 때는 결과 JSON의 선택 항목 testCases에 최대60개를 기록합니다. 보고서를 분할할 필요가 없습니다. 각 항목은 고유 id, group, title, 실행 steps, expected, actual, status를 포함합니다. 상태는 pass(통과), fail(실패), partial(부분 확인), not_run(미실행)입니다.

reference에 원본의 출처·버전·비교 범위를 적고, referenceImage·beforeImage·afterImage는 ../assets/ 아래 실제 이미지 경로로 지정합니다. 원본 또는 수정 후 화면이 없으면 missingEvidence에 사유를 명시합니다. fix와 retest에는 실제 수정·재검증을 기록합니다. 이미지를 만들거나 미실행을 통과로 채우지 않습니다. 모든 TC가 통과하기 전에는 전체 결과를 complete로 등록할 수 없습니다. 이 확장도 공통 H2 순서와 보존 JSON 검사를 그대로 사용합니다.

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

보고서는 무엇이 달라졌고, 확인됐으며, 무엇이 남았는지 먼저 보여줍니다. 핵심 결과는 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/의 별도 기록 파일이나 같은 프로젝트의 글로 분리해 링크합니다. 본문은 결과·변경·검증·남은 사항을 먼저 보여줍니다.

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