ArdenZC/codex-work-skills

수업 계획 생성기 Skill 2.2.1

본 Skill의 유일한 완전한 행동 규범입니다. 다른 agent 진입점은 먼저 이 파일과 공통 프롬프트.md를 읽어야 하며, 다른 필드 세트나 생성 규칙을 복사하지 않습니다. 현재 Windows와 macOS를 지원합니다. 모델은 자료를 이해하고 완전한 Content 2.2 JSON을 생성하는 역할을 담당합니다. Python은 결정론적 검증, 포맷팅 및 템플릿 매핑만 수행하며, 모델의 본문 창작을 대체할 수 없습니다. 2.2.1은 Lesson / WorkOrder 전달 계약의 수정 버전이며, Word 템플릿, 본문 품질 알고리즘 또는 WorkOrder 평가 계약을 수정하지 않습니다.

작업 진입점 및 Intake Runtime 2.1.1

작업 시작 시 현재 세션, 사용자 업로드 파일 및 사용 가능한 강의 자료를 읽습니다: 능력 지도, 단원별 작업 분해, 교과 과정 기준, 교재 목차, 기존 수업 계획 및 사용자가 지정한 Word 템플릿. 공식 계획을 세우기 전에 반드시 INTAKE_PENDING 상태로 진입해야 하며, 현재 이해를 바탕으로 한 번에 집중된 완전한 중국어 강의 기본 정보 확인을 구성해야 합니다. 정보가 이미 세션이나 첨부 파일에서 추론되었더라도 반드시 표시하고 사용자에게 확인을 요청해야 합니다. 확인이 완료되면 INTAKE_CONFIRMED 상태로 진입하여 자료 검색, 강의 수준 개요(outline), Content 2.2, QA 및 DOCX를 직접 시작합니다.

사용자 인터페이스는 중국어 레이블만 사용하며, 내부 필드 이름을 질문 내용으로 사용하지 않습니다. 한 번 확인에 반드시 포함되어야 하는 강의 기본 구성은 다음과 같습니다: 강의 이름, 전공, 수강 대상, 총 수업 시간. 확인 요약에는 다음의 비차단 정보도 반드시 포함되어야 합니다: 이론 수업 시간, 실습 수업 시간, 이론 및 실습 조직 방식, 단일 수업 시간 기본값 2학점, 사용 교재, 보조 참고 자료, 실습 작업 지시서 동시 생성 여부.

네 가지 핵심 필드에 정보 누락이 있는 경우 동일한 확인 요약에 "보충 필요"를 표시합니다. 총 수업 시간은 사용자가 명확하게 제공한 사실만 허용합니다. 전공이나 수강 대상이 단지 Agent의 추론인 경우 반드시 "현재 이해 / 부정확하면 수정"으로 표시해야 합니다. 이론/실습 분할, 조직 방식 또는 실습 작업 지시서 선호도가 명확하게 제공되지 않은 경우 반드시 "확인 필요"를 표시해야 하며, 50/50, 통합형 또는 "아니오"로 자동 완성할 수 없습니다. default_hours=2는 2학점 기준으로 대략 몇 개의 수업이 있는지 설명하는 데만 사용할 수 있으며, 이를 기반으로 이론/실습 비율을 추론할 수 없습니다. 내부 필드 매핑 및 상태 규칙은 docs/intake-contract-v2.1.1.json을 참조하십시오. 사용자 인터페이스에는 "보조 참고 자료"만 표시되며, 내부 상태는 여전히 auxiliary_references를 사용하므로 이 영문 키를 사용자 질문으로 사용해서는 안 됩니다.

첫 응답은 다음과 유사해야 합니다:

먼저 강의 기본 정보를 확인하겠습니다:
- 강의 이름: 《고급 자료구조》
- 전공: 현재 이해 / 부정확하면 수정
- 수강 대상: 현재 이해 / 부정확하면 수정
- 총 수업 시간: 40학점
- 이론 수업 시간: 확인 필요
- 실습 수업 시간: 확인 필요
- 이론 및 실습 조직 방식: 확인 필요 (선택 사항: 전체 이론 / 전체 실습 / 분할 조직 / 통합 조직)
- 단일 수업 시간: 기본 2학점
- 사용 교재: 지정되지 않음 (지정 교재가 있으면 알려주세요. 없어도 계속 진행 가능합니다)
- 보조 참고 자료: 지정되지 않음
- 실습 작업 지시서 동시 생성: 확인 필요
위 정보가 정확합니까? 조정이 필요하면 한 번에 알려주세요.

교재는 권장 사항이지 필수 사항이 아닙니다: 제공된 파일이나 서명은 직접 표시하며, 제공되지 않아도 생성을 차단할 수 없습니다. practice_work_orders가 제공되지 않은 경우 확인 필요 상태를 유지합니다. 사용자가 명확하게 선택한 후에만 WorkOrder Skill 연결 여부를 결정합니다. 명확하게 false를 선택한 경우 실습 학점은 여전히 강의 총 수업 시간에 포함되지만, Practice Task Contract, handoff, WorkOrder 또는 실습 측 추가 파일을 생성하지 않습니다. 명확하게 true를 선택한 후, Lesson Agent는 Lesson QA/DOCX 및 Practice Task Contract handoff를 완료한 후 사용 가능한 WorkOrder Skill을 감지하고 호출하며, WorkOrder Agent가 완전한 Content V1을 창작하고 QA를 실행하고 작업 지시서를 생성한 후 최종적으로 통합 전달합니다. 사용할 수 없는 경우 Lesson과 handoff만 전달하고 실습 작업 지시서 생성기를 현재 사용할 수 없습니다. 실습 작업 데이터 파일이 저장되었습니다. 작업 지시서 생성기를 사용할 수 있게 되면 계속 생성할 수 있습니다.라고 명확히 표시하며, 작업 지시서 DOCX를 위조하지 않습니다.

Intake가 확인되기 전에는 프로젝트 수나 이름, 이론/실습 수업 구조, 실습 작업 수, 수업별 교수 내용을 결정하거나 DOCX를 생성할 수 없습니다. 단, 사용자가 이미 명확하게 해당 사실을 제공한 경우는 예외입니다. 한 번 확인된 후에는 outline, 프로젝트 이름, 수업별 작업, 평가, 템플릿, 출력 디렉토리 또는 "DOCX 생성을 시작할까요?"에 대해 다시 질문할 수 없습니다. 기본 템플릿과 기본 출력 규칙을 직접 사용합니다. 사용자가 요구 사항을 능동적으로 변경하거나, 확인 정보에 합리적으로 해결할 수 없는 직접적인 충돌이 발생하거나, 안전/파일 덮어쓰기 등 사용자 결정이 실제로 필요한 사항이 있는 경우에만 다시 중지할 수 있습니다.

사용자가 "전체 이론"을 명확하게 선택하면 theory_hours=total_hours, practice_hours=0, delivery_mode=theory_only으로 정규화하고 실습 작업 지시서를 false로 설정합니다. "전체 실습"을 명확하게 선택하면 theory_hours=0, practice_hours=total_hours, delivery_mode=practice_only으로 정규화합니다. 기타 분할은 theory_hours + practice_hours = total_hours을 충족해야 합니다. 같지 않은 경우 먼저 충돌을 보고하고 outline을 시작할 수 없습니다.

자료 검색은 사용자가 제공한 교재/강의 자료와 사용자가 지정한 교재를 우선 사용합니다. 네트워크 연결이 가능한 경우 출판사나 학교 공식 페이지, 표준/가이드, 공식 기술 문서 및 확인 가능한 공개 문헌을 추가로 검색합니다. 서명만 제공된 경우 실제로 확인된 저자, 출판사, ISBN, 판 또는 연도만 작성할 수 있습니다. 네트워크를 사용할 수 없는 경우 정상적으로 계속 진행하며, 네트워크 연결 불가로 생성을 중단하지 않습니다.

• 사용자가 합리적인 추론을 허용한 경우, 프로젝트화 교수법에 따라 프로젝트, 작업, 교수 내용, 평가 및 사전 생성된 성찰을 보충합니다.
• 최종 DOCX에는 "자료 부족, 추론, AI, QA, similarity, confidence" 등의 내부 설명이 나타나지 않아야 합니다.

작업 자료가 없더라도 반드시 먼저 강의 수준의 outline을 구성한 후, 수업별 내용을 생성해야 합니다. outline에는 최소한 lesson_id, unit, task, lesson_type, hours, theory_hours, practice_hours, prior_learning, capability_stage, deliverable, next_bridge 및 practice_task_ids가 포함되어야 합니다. 긴 강의는 내부적으로 4~6개 수업을 한 묶음으로 생성할 수 있지만, 최종적으로는 완전한 강의 컨텍스트를 사용하여 통합 QA를 수행해야 합니다.

Content Contract V2.2

기본적으로 assets/templates/lesson-plan/v1.1.2/template.docx를 사용합니다.

공식 생성 입력의 기본값은 content_contract_version: "2.2"이며, Word 템플릿 버전과 독립적입니다. 런타임 시 "2.1" 및 "2.0" 읽기를 호환합니다. 기본 Word 템플릿은 lesson-plan v1.1.2이며, v1.0 legacy-coordinate, v1.1.0/v1.1.1 semantic-bookmark 및 이전 호환성 템플릿 경로를 계속 지원합니다. 이전 sparse JSON은 더 이상 생성되지 않습니다.

강의 수준 필수 필드:

content_contract_version, course_name, major, audience,
default_hours, total_hours, delivery_plan, course_materials,
reference_pool, artifact_plan, outline, lessons

각 2.2 이론 수업은 직접 다음을 제공해야 합니다:

lesson_id, unit, task, lesson_type, hours, theory_hours, practice_hours,
progression, reference_ids, practice_task_ids,
student_analysis, teaching_content, goals,
key_point, difficult_point, teaching_methods, resources,
implementation, evaluation, reflection

2.0 입력은 여전히 수업 내의 references 객체를 읽습니다. 2.1 호환 입력은 기존 수업 의미를 유지합니다. 2.2는 강의 수준 reference_pool의 reference_ids를 통해서만 출처를 선택하며, 각 이론 Lesson에는 최소 1개의 reference가 있어야 합니다. 2.2의 Lesson DOCX는 이론만 포함합니다: sum(lesson.hours) == theory_hours, 모든 Lesson은 lesson_type=theory, practice_hours=0입니다. 실습은 Lesson DOCX에 포함되지 않습니다. artifact_plan.practice_work_orders=true인 경우에만 실습이 Practice Task Contract / WorkOrder handoff에 포함됩니다. false인 경우 contract나 작업 ID를 포함할 수 없으며, practice_task_ids는 스키마에서 요구하는 빈 배열만 유지합니다. practice_task_ids는 이론 수업과 연결된 실습 작업을 나타내며, 실습 Lesson DOCX를 생성해야 함을 의미하지 않습니다. delivery_plan은 theory_only, practice_only, split_lessons, integrated_lessons, hybrid를 지원하며, theory_hours + practice_hours == total_hours를 충족해야 합니다. integrated는 아티팩트 수준의 이론-실습 통합 조직을 설명할 뿐, 실습 시간을 Lesson DOCX에 포함시키거나 1+1로 고정하지 않습니다.

default_hours는 Agent가 각 수업 시간을 생성할 때 사용하는 기본 단일 수업 학점입니다. 특정 수업에서 명시적으로 제공한 hours가 이를 덮어쓸 수 있습니다. default_hours는 모든 lessons.hours와 같을 필요는 없습니다. default_hours, total_hours 및 각 수업의 hours는 모두 양의 정수 학점이어야 합니다: 값은 1, 2, 4, 12 등의 정수, 문자열은 "1", "2", "2.0"이 가능합니다. 빈 문자열, 분수, 0, 음수, NaN 또는 Infinity는 허용되지 않습니다. unit은 프로젝트화된 이름(예: "프로젝트 1...")을 사용합니다. progression은 prior_lesson_id, 구체적인 prior_learning, capability_stage, deliverable, next_bridge를 포함합니다. capability_stage는 인지, 이해, 모방, 독립, 종합, 최적화, 전이만 사용할 수 있으며, 기계적인 선형 증가를 요구하지 않습니다. 첫 번째 수업의 prior_lesson_id는 반드시 null이어야 하며, 후속 수업은 이미 나타난 이전 수업만 참조할 수 있습니다. 4개 이상의 수업에서 모든 능력 단계가 동일해서는 안 됩니다.

student_analysis의 base/problems/strategies, 세 가지 유형의 goals는 각각 최소 2개 항목, teaching_content는 최소 3개 항목, key_point 및 difficult_point는 각각 content와 strategy가 있어야 합니다. methods는 최소 2개 항목, resources는 최소 2개 항목이어야 합니다. 2.2 이론 Lesson의 reference_ids는 비어 있을 수 없습니다. 빈 reference는 직접 실패합니다. 순수 실습 강의는 Lesson DOCX가 없을 수 있습니다. 실습 작업 지시서 생성을 명확하게 선택한 경우에만 Practice Task handoff를 통해 실습 학점을 표현해야 하며, 명확하게 생성하지 않는 경우 handoff를 생성하지 않으며 이론 수업을 허구로 만들어서는 안 됩니다.

각 수업의 implementation은 다음 9개의 ID, 고정된 순서로 완전히 제공되어야 하며, 각 단계의 label, minutes, modality, content, teacher_actions, student_actions, objective는 모두 JSON에서 가져와야 합니다:

before_class_preparation
task_introduction
operation_demonstration
task_implementation
task_extension
project_practice
peer_review
lesson_summary
after_class_improvement

수업 전 준비 및 수업 후 개선은 수업 외 단계에 속합니다. 중간 7개 단계의 분 수는 엄격하게 hours * 45와 같아야 합니다. 각 수업 외 단계는 0분이 허용되지만 max(60, hours * 45)를 초과할 수 없으며, 두 수업 외 단계의 합계는 2 * hours * 45를 초과할 수 없습니다. 오류 보고는 lesson ID, stage, actual 및 limit를 지적해야 합니다. operation_demonstration은 의미적 행위 위치이며, 간호, 회계, 기계 등의 강의에서 방법 시범, 사례 분석 또는 기술 시범으로 표시될 수 있습니다.

평가는 명시적으로 85–96 범위의 evaluation.score를 제공해야 하며, 0.5점 단위로 증분하고, 표준 13개 criterion ID에 대한 수업별 remarks를 제공해야 합니다. 각 remark는 실질적인 내용이 있어야 합니다. 모든 Content V2 템플릿 버전은 통일적으로 48개의 유의미한 문자를 초과할 수 없는 계약 상한을 적용하며, manifest는 더 엄격하게 제한할 수 있습니다. 상한을 초과하면 자르지 않고 실패해야 합니다. 점수가 지정되지 않은 경우 자연스럽게 88–94에 집중되는 것을 권장하지만, 모두 90이거나, 임의의 짧은 주기로 순환하거나, 엄격하게 증가하거나 감소해서는 안 됩니다. score_breakdown()은 명시적인 총점을 결정론적으로 기존 테이블 행에 분배하는 역할만 합니다. Python은 비고를 창작하지 않으며, 세 가지 고정된 remarks 순환이나 기계적인 점수 fallback을 사용하지 않습니다. 성찰은 명시적으로 summary, innovation, improvement를 제공해야 하며, 수업 전 사전 생성이 허용되지만 본 수업의 작업, 핵심/난점, 조직, 예상 성과, 문제 및 다음 수업 연결과 관련된 차별성을 생성해야 합니다.

2.2의 course_materials.textbook은 별도로 교재를 나타내며, 객체 또는 null이 될 수 있습니다. 기본적으로 Word의 references 셀에 자동으로 기록되지 않습니다. Agent는 수업별 생성 전에 먼저 course_reference_pool / reference_catalog planning 개념을 형성하며, 저장 필드는 여전히 reference_pool이며 새로운 JSON 계약 필드가 아닙니다. 각 항목은 reference_id, reference_type, 식별 가능한 구체적인 제목, source_kind, source_region (domestic/foreign/unknown) 및 해당 evidence가 있어야 합니다. 수업별로는 reference_ids만 작성합니다. allow_textbook_as_reference는 기본값이 false이며, 명시적으로 true인 경우에만 교재가 references에 포함될 수 있습니다. references는 읽거나, 참조하거나, 인용하거나 강의의 근거로 사용할 수 있는 문헌/문서 출처만 나타냅니다. 여기에는 단행본, 강의/교수 표준, 국가/산업/직업 표준, 가이드/규범, 논문, 공개 문헌, 공식 기술 문서, 공식 제품 매뉴얼 및 사용자가 제공한 공식 교육 문서가 포함됩니다. resources는 교수 구현 시 사용하는 도구, 장비, 환경 및 재료를 나타냅니다. 예를 들어 MySQL Workbench, 데이터베이스 서버, PPT, 프로젝터, 간호 모델, 가상 머신, 실습 과제 시트 및 사례 데이터 세트 등이 있습니다. 이러한 것은 references에 숫자를 채우기 위해 작성할 수 없습니다. 각 수업은 일반적으로 1~3개의 reference를 선택하며, 강의 수준의 합법적인 reference는 재사용할 수 있습니다.

source_kind는 여전히 provided, generic, verified_public을 유지합니다. provided는 사용자 실제 자료 evidence가 필요하고, verified_public은 URL 또는 확인 가능한 공식 출처가 필요하며, generic은 구체적인 문서 의미만 사용할 수 있고 상세한 서지 정보를 위조할 수 없습니다. "통합 모델링 언어 관련 공개 문서", "관련 네트워크 리소스", "관련 공개 문헌" 등의 일반화된 자리 표시 텍스트를 금지하며, 저자, ISBN, 출판사, 판, 연도 또는 표준 번호를 추측하는 것도 금지합니다. 국내 출처를 우선시합니다: 사용자 제공 자료, 국내 간행물/단행본, 국내 대학 자료, 국가/산업/직업 표준 및 국내 권위 있는 문서를 외국 고전보다 우선시합니다. 국내 비율이 70% 미만인 것은 quality warning일 뿐 hard fail은 아니며, 국제 표준/고전이 확실하거나 국내 출처가 부족한 경우 외국 출처를 보충할 수 있습니다. reference의 수업 간 완전 중복은 허용되며, reference_reusable에 속하며, exact/item/sentence/field/structural/frequency/whole-course 중복 반대 hard-fail에서 명시적으로 제외됩니다. 동일 수업 내 중복 ID 또는 중복 내용은 여전히 hard-fail입니다. References의 중복은 교안 본문 중복 문제에 속하지 않습니다. 강의 중복률을 낮추기 위해 다른 교재, 저자, ISBN, 출판사, 표준 번호 또는 공개 문헌을 조작하는 것을 금지합니다. 동일 교재를 18회 반복하는 것이 18권의 교재를 조작하는 것보다 낫습니다. evidence는 입력 및 QA에만 사용되며, DOCX에는 공식 인용 텍스트만 작성하고 evidence 메타데이터는 작성하지 않습니다.

Practice Task Contract V1

artifact_plan.practice_work_orders=true인 경우에만 2.2 입력은 practice_task_contract를 제공해야 하며, 버전은 1.0, granularity: "per_task"입니다. 실습 학점은 양의 짝수여야 합니다. 작업 필드는 task_id, project_id, title, lesson_ids, practice_hours, scenario, objectives, required_inputs, tools_or_materials, steps, deliverables, acceptance_criteria, safety_or_compliance입니다. 각 Practice Task는 고정 2학점이며, 작업 수는 엄격하게 practice_hours / 2와 같습니다. 각 작업은 하나의 WorkOrder에 해당하며, project_id는 그룹화에만 사용되며 세분성을 다시 계획할 수 없습니다. lesson_ids는 이론적 준비/사전 지식을 제공하는 이론 Lesson ID이며, 여러 수업에 걸쳐 있을 수 있습니다. 순수 실습 강의에 이론 Lesson이 없는 경우 빈 배열입니다. practice_work_orders=false인 경우 contract 또는 handoff가 허용되지 않으며, 모든 practice_task_ids는 빈 배열로 유지되어야 합니다. true인 경우 Lesson은 표준 handoff를 생성하고 QA하는 역할만 담당하며, 감지된 WorkOrder Skill이 Agent orchestration을 통해 handoff를 소비합니다. Lesson Python generator는 WorkOrder Python을 subprocess 호출하거나 handoff를 작업 지시서 본문으로 자동 매핑할 수 없습니다. WorkOrder Skill을 사용할 수 없는 경우 practice-task-contract.json handoff만 출력하고, 사용 불가능 상태를 명확히 표시하며 실습 작업 지시서 DOCX를 위조하지 않습니다.

현재 2.2 전체 규칙은 docs/content-contract-v2.md를 참조하십시오. examples/tasks-v21.example.json은 2.1 호환 예제로 유지되며, examples/tasks.example.json은 2.0 호환 예제로 유지됩니다. 필드 설명은 docs/content-contract-v2.md 및 docs/practice-task-contract-v1.md를 참조하고, 기계 제약 사항은 schemas/lesson-plan-input.schema.json과 저장소 표준 schemas/shared/practice-task-contract.schema.json을 참조하십시오. schemas/practice-task-contract.schema.json은 호환성을 위한 진입점일 뿐입니다.

Python과 Agent의 경계

Agent는 강의 수준 계획 및 모든 수업별 교수 본문을 담당합니다. 생성기는 스키마 검증, 번호 매기기, 줄 바꿈, 분 포맷팅, 필드 매핑 및 템플릿 쓰기만 수행합니다. V2 공식 경로에서는 이전의 generated_lesson_fields, implementation_cell_values, reflection_cell_values를 호출하거나 flows[:3]을 사용하거나 누락된 필드에 따라 본문을 창작할 수 없습니다. 내용이 manifest의 max_chars 또는 max_paragraphs를 초과하는 경우 lesson, field, actual chars, limit를 지적하고 실패해야 하며, 자르거나 자동으로 삭제할 수 없습니다.

생성 및 QA 순서

자료 읽기 → 한 번의 강의 기본 정보 확인
  -> 강의 outline
  -> Content V2.2 JSON
  -> Input Contract QA
  -> Content Quality QA
  -> Template QA
  -> candidate DOCX 생성
  -> Output Structure + Content-to-DOCX Fidelity QA
  -> 선택 사항 LibreOffice render smoke
  -> 최종 출력 및 외부 QA 보고서에 원자적 커밋
  -> practice_work_orders=true인 경우 WorkOrder Skill Agent 감지 및 호출, Lesson + WorkOrder 통합 전달
  -> Agent 대표 페이지 시각적 검사

scripts/generate_lesson_plans.py를 사용하여 생성합니다. 모든 DOCX는 먼저 최종 디렉토리와 동일한 상위 디렉토리의 candidate에 기록됩니다. Content QA, 템플릿 QA, 출력 구조/북마크/형식 보호, 내용 충실도 QA 및 요청된 render smoke가 모두 통과된 후에야 최종 디렉토리로 교체됩니다. 명시적인 --qa-report의 경우 외부 보고서는 동일한 상위 디렉토리에서 먼저 staging되고 출력 디렉토리와 함께 커밋됩니다. 교체 실패 시 이전 출력과 이전 보고서를 모두 복구합니다. 비어 있지 않은 최종 디렉토리에는 --backup-existing이 필요합니다. 교체 실패 시 이전 디렉토리를 복구해야 합니다. 커밋 성공 후 stdout은 최종 디렉토리에 실제로 존재하는 DOCX 경로만 보고합니다. 강의 기본 정보 확인 후에는 DOCX 생성을 위한 추가 확인을 수행하지 않습니다. Agent의 대표 페이지 시각적 검사는 커밋 후 검수에 속합니다. 오버플로, 잘림, 비정상적인 페이지 나누기 또는 빈 페이지가 발견되면 V2 내용을 다시 작성하고 --backup-existing을 사용하여 트랜잭션 생성을 다시 수행해야 합니다. qa-report.json은 보고서만 작성하고 DOCX에는 기록하지 않습니다.

독립적인 scripts/content_quality.py는 로컬에서 결정론적으로 실행되어야 하며, 온라인 API, 임베딩 또는 모델 서비스를 호출하지 않습니다. 기존 본문 중복, 엔터티 마스킹 후 구조적 유사성, 중복 긴 문장, 오래된 상투어, 완전성, 수업 내 일관성, 진행 일관성, 점수 패턴, 13개 평가 비고 밀도 및 비IT 오염을 검사합니다. 이번 라운드에서는 2.2 reference 필수 입력, source-region 통계 및 이론/실습 handoff 검사만 추가되며, 기존 반복, 진행, 평가 또는 구현 일관성 알고리즘은 변경되지 않습니다. non_it_contamination 및 해당 범위 메타데이터는 "입력에는 없지만 템플릿이나 생성기가 출력에 주입"한 IT 기본 단어만 감지하며, 일반 강의 분류기가 아닙니다. 진단은 제한된 조각과 안정적인 SHA-256만 유지하며, 사용자 본문 전체를 출력하지 않습니다. 모든 detector는 공통 재사용 정책을 공유합니다: narrative_strict, terminology_reusable, resource_reusable, reference_reusable, fixed_rubric_reusable 및 ignore. 교수 방법, 필수 리소스, 합법적인 reference 및 출석/준수/습관 고정 루브릭은 중복 증거를 기록할 수 있지만 hard fail하지 않습니다. reference는 수업 간 완전 중복이 허용되며, exact/item/sentence/field/structural/frequency/whole-course 중복 반대 hard-fail에서 완전히 제외됩니다. 동일 수업 내 정확한 중복과 명백한 순수 도구/장비 reference는 hard-fail해야 합니다. 단기 강의 용어 면제는 내러티브 필드에 포함될 수 없습니다. 강의 중복률을 낮추기 위해 참고 문헌을 허구로 만들어서는 안 됩니다.

progression의 artifact 상속 및 전방 전환은 모두 어휘/일관성 증거와 substantive_anchor 증거를 동시에 통과해야 합니다. "설계, 조작, 분석, 검사, 프로세스, 구현" 등의 일반적인 동작은 독립적으로 anchor가 될 수 없습니다. 인접하지 않은 prior_lesson_id는 여전히 허용됩니다. 물리적 순서 체인이 review인 경우 보고서는 requires_agent_review=true로 설정하고 from/to/reason/score/declared_prior를 나열해야 합니다. Agent 최종 검수는 물리적 시퀀스 검토를 자동으로 무시할 수 없습니다. 실제 수업 순서를 설명할 수 없는 경우 progression을 다시 작성해야 합니다.

결정론적 QA가 통과되고 원자적 커밋이 완료된 후, Agent는 수업별 내부 재검토를 수행해야 합니다: 이 수업이 이전 수업에 비해 무엇을 새로 추가했는지, 이전 수업의 어떤 지식이나 결과를 사용했는지, 무엇을 산출했는지, 다음 수업에서 이 결과를 어떻게 사용할지. 이 재검토는 DOCX에 기록되지 않습니다. --render를 요청하면 Python 보고서는 render.scope=smoke만 나타내며, 페이지 수 방법은 경량 pdf_page_object_regex입니다. 이는 시각적 QA 또는 페이지 매김 확인과 동일하지 않으며, 오버플로, 잘림, 비정상적인 페이지 나누기 또는 표 변형이 없음을 증명할 수 없습니다. Agent는 첫 번째 수업, 본문이 가장 밀집된 수업, 마지막 수업을 검사하고, 강의가 12학점에 도달하면 1~2개의 중간 수업을 추가로 검사하여 클리핑, 오버플로, 겹침, 빈 페이지, 비정상적인 행 높이 및 테두리를 확인해야 합니다. 실제 검사 후 scripts/record_visual_inspection.py를 사용하여 독립적인 visual-inspection.json에 명시적으로 기록합니다. 이 파일은 대표 페이지, 검사, 메모, 관련 qa-report, 출력 지문 및 타임스탬프를 기록하며, Python은 자동으로 시각적 통과를 주장하지 않습니다. 시각적 검사에 실패하면 V2 JSON을 수정하고 --backup-existing을 사용하여 트랜잭션 생성을 다시 수행하고 다시 검사해야 합니다.

기본 출력 QA는 원본 V2 JSON을 읽고 순수 포맷터를 통해 예상 값을 계산한 후 semantic bookmark 또는 v1.0 좌표와 비교합니다. 교수 내용 생성 함수를 다시 호출하지 않습니다. 템플릿 레이아웃, 70개의 semantic bookmark, 북마크 ID/이름, 지문, v1.0/v1.1 호환성 및 표준 바이너리가 모두 보호됩니다. 로컬에 LibreOffice가 있는 경우 --render를 사용하여 render smoke를 수행합니다. 렌더러가 없는 경우 구조적 QA는 계속 통과되며, 보고서는 render.status=not_executed로 표시됩니다. 실제 페이지 매김, 오버플로 및 시각적 레이아웃 결론은 Agent의 대표 페이지 검사에서만 비롯됩니다.

어댑터 설치 의미는 고정됩니다: 기본값은 instruction-only adapter install（仅规则/指令安装）이며, 프로젝트 규칙과 최소 instructions만 설치하고 전체 런타임을 복사하지 않으며 대상 프로젝트가 generator를 독립적으로 실행할 수 있다고 약속하지 않습니다. --copy-engine을 추가하는 경우에만 full runnable project-local Lesson engine（完整可运行引擎）입니다. 대상 프로젝트가 .lesson-plan-docx-generator/scripts/generate_lesson_plans.py를 직접 호출해야 하는 경우 --copy-engine을 사용해야 합니다. visual-inspection.json은 Agent visual inspection attestation for the current generated DOCX/QA state이며, 현재 생성된 DOCX/QA 상태에 대한 Agent의 대표 페이지 검사를 나타내며, 검사된 PDF/이미지의 암호화 증명이 아닙니다.

경로 사전 점검은 mkdir, 생성, 이동, 백업, 삭제 전에 실행되며, Skill 루트, 입력 JSON, 스키마, 선택/사용자 정의 템플릿, manifest, 표준/호환성 패키지, 스크립트 및 테스트를 보호하고 상위, 하위, 확인된 심볼릭 링크 및 Windows 어휘/8.3 별칭 중복을 거부합니다. 출력을 보호된 디렉토리나 사용자 정의 템플릿 패키지에 기록하지 마십시오.

명령어

Windows:

python scripts/generate_lesson_plans.py `
  --tasks-json tasks.json `
  --output-dir output `
  --render

macOS:

python3 scripts/generate_lesson_plans.py \
  --tasks-json tasks.json \
  --output-dir output \
  --render

개별 출력 검증:

scripts/validate_template.py --json
scripts/validate_output.py --input-json tasks.json --output-dir output --render
scripts/validate_visual_inspection.py --output-dir output --qa-report output/qa-report.json --evidence output/visual-inspection.json

수동 설치 및 종속성 검사 (설치 프로그램이 Python 환경을 자동으로 수정하지 않음):

python scripts/install.py --skills-dir <skills-dir>
python <skills-dir>\lesson-plan-docx-generator\scripts\check_dependencies.py

check_dependencies.py는 docx, yaml, jsonschema를 읽기 전용으로 검사합니다. 누락 시 pip install -r requirements.txt를 안내합니다. Agent 생성 프로세스에서는 --skip-template-validation 또는 --skip-output-validation 사용을 금지합니다. 이 두 호환 매개변수는 명시적으로 LESSON_ALLOW_UNSAFE_VALIDATION_SKIP=1이 설정된 경우에만 제어된 테스트에 사용할 수 있으며, 보고서에 명확히 skipped로 표시해야 합니다. 입력 계약, 콘텐츠 품질 및 경로 보호는 건너뛸 수 없습니다. 임시 JSON, PDF, 이미지 및 candidate 디렉토리는 작업 종료 후 정리되며, 생성된 DOCX는 커밋되지 않습니다.

템플릿 파일

assets/templates/lesson-plan/v1.1.2/template.docx
assets/templates/lesson-plan/v1.1.2/manifest.yaml
assets/templates/lesson-plan/v1.1.1/template.docx
assets/templates/lesson-plan/v1.1.1/manifest.yaml
assets/templates/lesson-plan/v1.0.0/template.docx
assets/templates/lesson-plan/v1.0.0/manifest.yaml
schemas/lesson-plan-input.schema.json
scripts/content_contract.py
scripts/content_quality.py
scripts/generate_lesson_plans.py
scr... (잘림)