학습자를 위한 빌드
당신은 코드를 작성하는 방법을 알고 있습니다. 여기서 보이지 않는 것은 교실입니다: 30명의 어린이들이 한 학교 주소에서 오전 9시 5분에 이것을 열고, 공유 Chromebook, 정답이 'View Source' 하나면 되는 퀴즈, 숙제를 대신 해주는 튜터, 학급이 쓸 수 있는 키(key). 이것을 순서대로 지키고, 평범한 말로 설명하세요: 당신이 돕고 있는 사람은 코드를 읽어본 적이 없을 수도 있습니다.
여기 나오는 명령어는
viable-harness입니다. npm에 배포되기 전까지는npx github:VIABLE-Learning-Lab/viable을 대신 사용하세요.
1. 만들기 전에 물어보세요
요청 사항만으로는 알 수 없는 것을 한 번의 메시지로 물어보고, 답변을 프로젝트 루트의 LEARNERS.md에 기록하세요.
- 학습자는 누구인가요? 13세 미만, 13~17세, 또는 성인: 이에 따라 허용되는 것이 달라집니다.
- 이후에 학습자가 무엇을 할 수 있어야 하나요? 한 문장으로. 도구의 목적을 결정합니다.
- 어디서, 몇 명이 사용하나요? 수업 시간에 학교 컴퓨터로, 아니면 집에서? 동시에 몇 명? 컴퓨터를 공유하나요?
- 어떤 환경에서 작업해야 하나요? Chromebook은 서버나 아래 명령어를 실행할 수 없습니다. 누가 호스팅할 건가요?
- 학습자 사용 중 AI가 필요한가요? 대부분은 아닙니다: AI 없이도 퀴즈를 만들 수 있습니다.
- 무엇을 저장하고, 누가 보나요? 이름이 필요한가요, 아니면 코드만으로 충분한가요?
- 다음 학기에 누가 관리하나요? 다른 사람들이 이것에 의존하게 될까요?
만약 학습자에게 AI가 응답하길 원한다면, 같은 메시지에 다음 질문도 함께 물어보세요. 각각 답이 달라질 수 있기 때문입니다:
- 누구의 계정으로 비용을 지불하며, 해당 제공업체가 이 학습자들을 허용하나요? 18세 미만의 경우, 교사의 개인 키는 종종 이것에 사용될 수 없다고 지금 말하세요. references/learner-data.md에 세 제공업체의 요구 사항이 나와 있습니다. 메시지를 보내기 전에 읽어보세요.
- 학습자가 충격적인 말을 했을 때 누가, 얼마나 빨리 통보받나요?
- 하루에 얼마나 사용할 수 있으며, 그 한도에 도달하면 학습자에게 무엇을 보여줘야 하나요?
- 대화는 얼마나 오래 보관되나요?
이 내용을 프로젝트의 AGENTS.md 또는 CLAUDE.md에 추가하여 이후 세션에서도 유지되도록 하세요:
학습자가 이것을 사용합니다. LEARNERS.md를 먼저 읽으세요. 모델 키, 채점되는 정답, 또는 학습자의 이름을 페이지나 프롬프트에 절대 넣지 마세요. 공유하기 전에 `viable-harness review`를 실행하세요.
2. 필요한 최소한의 기능만 구축하세요
각 단계는 누군가가 실행하고, 비용을 지불하고, 책임져야 할 무언가를 추가합니다. 작업을 수행하는 가장 낮은 단계에서 멈추고, 그 이유를 설명하세요.
| 단계 | 설명 | 요구 사항 |
|---|---|---|
| 0. 페이지 | 계정 없음, 서버에 저장되는 것 없음, 학습자 사용 중 AI 없음 | 거의 없음. 대부분의 퀴즈, 게임, 시뮬레이션이 여기에 해당 |
| 1. 기억하는 페이지 | 이름 없이 학급 코드로 작업 저장 | 규칙이 있는 데이터베이스와 저장된 데이터 삭제 |
| 2. 학습자 곁의 AI | 학습자에게 응답하는 모델 | 키를 보관하는 서버, 학급별 예산, AI 규칙, 테스트, 학습자가 충격적인 말을 했을 때 처리 절차, 그리고 성인이 읽을 수 있어야 하므로 데이터베이스와 교사용 페이지. 이것이 작은 페이지를 애플리케이션으로 만드는 지점입니다: 우리가 시도했을 때 테스트 포함 약 천 줄 |
| 3. 이름과 기록 | 명단, 개인별 작업, 성적 | 데이터 규칙, 보관 기간, 그리고 일반적으로 학교의 동의 |
| 4. 연구 | 동의, 조건, 내보내기 | 검토 위원회 및 어떤 버전이 무엇을 했는지에 대한 기록 |
누가 요청하든 멈추고 그렇게 말하세요. 그리고 구축할 가치가 있는 가장 가까운 것을 제안하세요:
- IEP, 504 플랜, 행동 계획 또는 진도 보고서를 작성하는 AI. 여러 출처의 오랜 기간 정보가 필요합니다 (Common Sense).
- 성인이 읽을 수 없는 어린이와의 공개 채팅.
- 스스로 성적, 배치 또는 처벌을 결정하는 모든 것.
실제 학습자가 사용한다면, 그것은 더 이상 프로토타입이 아닙니다. "내가 직접 만들었다"고 해서 학교의 검토에서 면제되지 않습니다 (CoSN). 일찍 알리세요.
3. 2단계부터는 누가 무엇을 운영할지 결정하세요
스킬은 작성하는 코드의 형태를 결정합니다. 교실에서는 여전히 누군가가 키를 관리하고, 예산을 감시하며, 책임을 져야 합니다. 각각의 비용과 함께 다음 옵션을 제시하고, 선택하게 하세요.
| 원하는 것 | 사용 | 그들이 할 일 |
|---|---|---|
| AI 튜터가 있는 학급, 자체 페이지 없음 | VIABLE 학습 플랫폼: 가르치는 내용을 말하세요 | 구축할 것이 없으므로, 무엇이든 구축하기 전에 그렇게 말하세요 |
| 자체 페이지, 키/한도/트래픽은 다른 사람이 관리 | 모델 엔드포인트로 VIABLE API: 학급당 하나의 키, 각각 자체 분당 요청 수, 일일 토큰 및 월 비용, 사용량 확인 가능 | 키를 보관하는 작은 서버 |
| 자체 페이지 및 자체 모델 계정 | 자체 서버, references/classroom.md의 패턴 사용 | 모든 것 |
| 모든 것을 자체 서버에서 | VIABLE 엔진 | 서버 실행 |
| 동의와 조건이 있는 연구 | VIABLE 개발자 플랫폼 | 호스팅할 것 없음 |
학습자가 18세 미만인 경우, 다른 제공업체와 마찬가지로 VIABLE 옵션에 의존하기 전에 VIABLE Lab에 문의하여 무엇이 적용되는지 확인하도록 하세요. 이 스킬은 그 질문에 답할 수 없으며, 당신도 할 수 없습니다.
4. 추측하지 말고 필요한 것을 찾으세요
- 표준 및 스킬:
viable-harness catalog "<몇 단어>"는 라이선스와 함께 개방형 표준, 데이터셋 및 도구를 찾습니다. 의존하기 전에 라이선스를 확인하세요. - 학습자가 틀리는 것:
viable-harness misconceptions "<몇 단어>"(수학용). 이를 바탕으로 오답과 힌트를 만드세요. - 연구가 권장하는 것:
viable-harness guidance "<몇 단어>"는 수업의 특정 순간에 무엇을 해야 하는지 알려주며, 각 항목은 연구 출처를 명시합니다. 출처를 함께 보관하고, 출처에서 얻지 않은 연구를 인용하지 마세요: 허위 인용은 흔합니다.
Harness의 MCP 서버가 연결된 경우, find_public_goods 도구, find_misconceptions 도구 및 find_guidance 도구가 동일한 기능을 수행합니다.
5. 구축하는 동안 다음을 지키세요
2~4단계의 코드를 작성하기 전에 references/classroom.md와 references/learner-data.md를 읽으세요. 학습자에게 응답하는 AI의 경우 references/ai-beside-learners.md도 읽으세요.
- 키와 AI에게 전달되는 내용은 서버에 보관됩니다. 페이지는 당신의 서버를 호출합니다.
- 학습자별 또는 학급별로 집계하고, 주소별로 집계하지 마세요. 학교는 보통 하나의 주소입니다. 학급 코드와 이름 없이는 학습자를 구분할 수 없습니다: 학급별로 집계하고, 브라우저당 대략적인 한도를 설정하세요.
- 각 학급에 예산을 할당하고 서버에서 집계하며, 예산이 소진되면 간단한 메시지를 표시하고 AI 없이도 작동하는 페이지를 유지하세요.
- 프롬프트에 학습자 이름을 넣지 말고, 학습자가 여는 페이지에 분석 또는 광고 스크립트를 넣지 마세요. 어린이가 입력하는 내용에도 개인 정보가 포함될 수 있으므로 제공업체의 규칙이 채팅 자체를 포괄합니다.
- 채점되는 답변은 서버에 보관됩니다. 브라우저가 답변이 맞았다고 말하는 것을 신뢰하지 마세요.
- 공유 컴퓨터: 한 학습자가 작성한 내용이 다음 학습자 페이지에 나타나지 않아야 합니다. "당신이 샘인가요?"는 실수를 잡아내지만, 누구나 '예'를 누를 수 있습니다.
- 교사가 통제권을 유지합니다: 교사가 열고, 중단할 수 있으며, 누가 막혀 있는지 볼 수 있습니다. 이름이 없으면 "누구"는 숫자입니다.
- 모든 사람이 읽고 사용할 수 있어야 합니다: 학습자의 읽기 수준, 키보드 사용 및 스크린 리더, WCAG 2.1 AA, 작은 화면 및 느린 네트워크.
6. 누군가 사용하기 전에 확인하세요
viable-harness review
모델 없이, 컴퓨터를 벗어나지 않고 프로젝트 텍스트에서 교실에서 문제가 될 만한 것을 읽습니다. 반드시 수정해야 한다고 말하는 것은 수정하고, 나머지는 당신이 돕고 있는 사람과 함께 읽으세요. 검토하고 만족한 줄은 viable-review: ok와 같은 주석에 이유를 적을 수 있습니다(예: 잘못된 코드에 대한 높은 한도). 예산이 작동하는지, 수업 시간에 어떤 일이 일어나는지, 접근성 등을 확인할 수는 없습니다: 깨끗한 결과가 합격을 의미하지는 않습니다.
도구에 학습자에게 응답하는 AI가 있는 경우, tutor-tests.json을 프로젝트에 복사하고 질문과 답변을 도구 자체의 주제로 변경하세요. 답변을 요구하고, 반박하고, 충격적인 말을 하고, 정답과 오답을 제시하며, 프롬프트를 알아내려고 시도합니다. 등장인물과 장소는 가상입니다. AI에게 전달되는 내용에 대해 실행하세요:
OPENAI_API_KEY=<해당 엔드포인트의 키> viable-harness test tutor-tests.json --endpoint https://api.openai.com/v1 --endpoint-model <모델명> --system "$(cat prompt.txt)" --judge-model <다른 모델>
--endpoint는 OpenAI 호환 주소로, /v1로 끝납니다. 28번의 모델 호출을 하며, 작은 모델에서는 최대 몇 센트입니다. 교사가 AI가 도움을 주는 정도를 변경할 수 있다면 각 설정에서 실행하세요: viable-harness draft-tests는 설정에 대한 테스트 케이스를 작성합니다.
그런 다음 교실 환경을 시뮬레이션하세요. 키가 없으면 모델 대용을 사용하세요:
- 한 주소에서 동시에 두 개의 브라우저, 두 번째 사람이 첫 번째 사람의 어떤 것도 보지 못하는지 확인.
- 문장 중간에 페이지를 닫고 다시 돌아오기. 예산에 도달하기. 모델 끄기.
- 학습자 역할로 충격적인 말을 한 다음, 교사가 다른 일을 하는 동안 교사가 보는 화면을 확인.
- 그들이 사용할 가장 작은 화면, 그리고 가능하다면 학교 자체 네트워크에서 테스트 (필터가 새 주소를 차단함).
7. 정직하게 인계하세요
평범한 말로 다음을 설명하세요: 무엇을 하는지; 무엇을, 어디에, 얼마나 오래 저장하는지; 누가 볼 수 있는지; 비용은 얼마이며 한도에 도달하면 어떻게 되는지; 무엇을 확인했는지; 그리고 아무도 확인하지 않은 것은 무엇인지. 안전하다거나 FERPA, COPPA 또는 어떤 법률을 준수한다고 절대 말하지 마세요. 당신은 그것을 알 수 없으며, 오직 사람만이 이에 대해 책임을 질 수 있습니다. references/learner-data.md에서 학교가 물어볼 질문 목록을 제공하세요.