AI 도구를 위한 안내

For AI agents: this repository is a toolkit (procedures, templates, skills, and a project scaffold) for running research with several LLM agents while keeping their numbers and judgments checkable. It is not a research project itself. Read this file first, then follow section 1. Answer the user in the user's language. All documents are written in Korean.

이 파일은 사용자가 이 저장소의 주소만 건넸을 때 Claude, ChatGPT(Codex) 같은 AI 도구가 무엇을 하고 무엇을 할 수 있는지 정한다. 사람이 읽는 소개는 README.md에 있다.

0. 이 저장소는 무엇인가

LLM 에이전트에게 연구 작업을 나눠 맡길 때 결과를 믿고 쓸 수 있게 하는 절차와 도구 모음이다. 세 가지를 절차와 파일로 지키게 한다.

1. 결과를 본 뒤에 판정 기준을 슬쩍 바꾸지 않는다. 기준은 결과 전에 한두 줄 적어 두면 충분하다. 해시 봉인(사전 등록)은 선택이고 드물게 쓴다(다시 받을 수 없는 자료, 큰 비용). 원고에는 쓰지 않는다.
2. 결과를 만든 쪽이 그 결과를 채점하지 않는다(독립 검산, 독립 심사).
3. 찾지 못한 것과 존재하지 않는 것을 구별한다(문헌 정찰의 검색어 기록, 확인 수준 표시).

들어 있는 것은 다음과 같다.

이 저장소 자체는 연구 프로젝트가 아니다. 여기서 세션 절차(00-교류/, 현황, 인계 노트)를 돌리지 않는다. scaffold/template/ 안의 AGENTS.md는 앞으로 만들 프로젝트의 규칙이고, 이 저장소의 규칙이 아니다.

1. 주소를 받으면

1. 이 파일, README.md, skills/README.md를 읽는다. 다른 파일은 필요할 때 읽는다.
2. 사용자가 무엇을 원하는지 2절 표에서 찾는다. 대화에 답이 없으면 다음 셋 가운데 필요한 것만 한 번에 묻는다.
   • 지금 연구가 어느 단계인가(주제 찾기, 착수 판단, 실험, 원고, 심사 대응, 여러 편 관리)
   • 어떤 도구를 쓰는가(Claude Code, claude.ai, Codex, 그 밖)
   • 이미 작업 중인 프로젝트 폴더가 있는가
3. 사용자가 무엇인지만 물으면 길게 설명하지 않는다. 아래 꼴로 짧게 답하고 무엇을 원하는지 묻는다.

이 저장소는 AI 에이전트로 연구할 때 결과를 검증할 수 있게 하는 절차와 스킬 모음입니다.
- 착수: 문제 정의 다듬기, 선행 연구 정찰, 해볼 만한지 관문 판정
- 실행: 실험 전 기준 메모(봉인은 선택), 일을 나눠 에이전트에게 맡기고 다른 에이전트가 검산
- 원고: 초록과 서론 구조, 모의 심사 반복, 읽기 쉽게 다듬기, 분량 줄이기, 실제 심사 대응
- 자리를 비운 동안: 떠나기 전에 승인한 지시서대로 에이전트가 일하고, 돌아오면 확인을 마친 검토서부터 봄
- 프로젝트 틀: 위 절차를 처음부터 갖춘 폴더를 만들어 줌
처음이면 착수 스킬 셋으로 시작하면 됩니다. 채워진 견본은 examples/demo-study에 있습니다.
지금 어떤 연구를 어느 단계에서 하고 계신가요?

4. 할 일을 고르면 무엇을 바꿀지(설치할 폴더, 만들 파일)를 먼저 말하고 사용자 확인을 받은 뒤 실행한다. 이 저장소의 파일을 읽기만 하는 일은 묻지 않고 해도 된다.
5. 이 체계로 하는 모든 일은 research-session 8절의 틀로 보인다. 시작하기 전에 시작 안내, 상태가 바뀔 때 진행판, 끝날 때 마침 보고를 보이고, 사용자가 보는 곳에 5분 넘게 아무 표시도 없게 두지 않는다. 양식은 templates/진행판.md.

2. 요청별로 할 일

스킬은 서로를 가리킨다. 흐름은 problem-grill, literature-scout, feasibility-gate로 착수를 판정하고, research-batch로 실행하고(봉인 preregister-seal은 선택), paper-framing에서 paper-quality-loop로 원고를 다듬고, submission-package로 투고를 준비하는 순서다. 모든 스킬의 공통 규칙은 research-session의 0절에 있다.

3. 설치하지 않고 쓰기

스킬은 설치하지 않아도 쓸 수 있다. 사용자의 요청에 맞는 skills/<이름>/SKILL.md를 읽고 그 절차를 따르면 된다. 스킬이 다른 스킬을 가리키면 skills/에서 그 스킬을 읽는다. "공통 규칙"은 skills/research-session/SKILL.md의 0절이고, 용어는 docs/용어집.md를 따른다.

설치하면 도구가 요청에 맞는 스킬을 스스로 고른다. 자주 쓸 사용자에게는 4절의 설치를 권한다.

4. 스킬 설치

사용자 홈 폴더나 프로젝트 폴더에 파일을 쓰는 일이므로 어디에 무엇을 넣을지 먼저 보이고 확인을 받는다. 같은 이름의 스킬이 이미 있으면 덮지 않는다.

• 명령은 이 저장소의 루트에서 실행한다.
• 일부만 넣으려면 ONLY=problem-grill,literature-scout,feasibility-gate, 덮어쓰려면 FORCE=1을 앞에 붙인다. 모든 스킬이 research-session의 공통 규칙을 가리키므로 ONLY를 주면 research-session은 늘 함께 들어간다. 일부만 넣은 스킬이 설치하지 않은 스킬(예: fact-check)을 가리키면 이 저장소의 skills/에서 읽는다. install-skills.sh list는 스킬 이름과 설명을 보인다.
• Codex의 전역 폴더는 CODEX_HOME이 있으면 $CODEX_HOME/skills/다. Codex가 스킬을 읽는 폴더는 버전에 따라 다를 수 있다. 설치 뒤 Codex에서 스킬이 보이지 않으면 그 버전의 문서를 확인하고 사용자에게 알린다.
• 프로젝트 폴더에 넣은 스킬(.claude/skills/, .codex/skills/)은 그 저장소에 커밋해 두면 다른 컴퓨터와 다른 도구도 같은 판을 쓴다. 커밋할지는 사용자에게 묻는다.
• 설치하면 스킬 폴더에 설치 기록(.research-ops.json: 저장소, 판, 커밋, 스킬마다 해시)이 남는다. install-skills.sh check는 새 판과 바뀐 스킬, 변경 기록을 보이고(새 판이 있으면 종료 코드 3), install-skills.sh update는 이 저장소를 받아 사용자가 고치지 않은 스킬만 바꾼다. 사용자가 고친 스킬은 덮지 않고 SKILL.md.new로 둔다. 이 저장소는 자주 바뀌므로 research-session이 세션을 시작할 때 정해진 주기(기본 7일)로 확인하고 알린다. 갱신은 사용자 확인 뒤에 한다(설정에서 자동으로 바꿀 수 있다).
• claude.ai에 올리는 일은 사용자가 한다. 도구는 zip을 만들어 건네고 올리는 곳을 알린다. research-scaffold와 research-session은 bash와 git이 있어야 제대로 쓰이므로 claude.ai에서는 절차 참고용이다.

5. 연구 프로젝트 만들기

skills/research-scaffold/SKILL.md를 따른다. 요점은 다음과 같다.

1. 필요한 것: bash, git, python3(봉인), gh(원격 저장소를 만들 때만).
2. 대화에서 정해지지 않은 값만 묻는다. 폴더 경로와 한 줄 설명은 꼭 받는다. 프로젝트 이름은 원격 저장소 이름이 되므로 영문 소문자, 숫자, ., _, -만 쓰고, 정하지 않으면 폴더 이름을 쓴다. 사용자 이름과 메일은 커밋 작성자가 되고 문서에 들어가므로 git config user.name이 도구 이름(claude 등)이거나 메일이 도구의 주소면 묻는다. 만든 프로젝트의 커밋은 사용자가 작성자, 도구가 공동 작성자다. 산출물 단위(기본 "원고")와 사용자 확인 없이 하면 안 되는 일(기본 "실험 실행")은 기본값을 쓰고 그렇게 했다고 말한다.
3. 이 저장소의 루트에서 실행한다. 도구가 돌릴 때는 원격 저장소를 만들지 않게 SCAFFOLD_PUSH=n을 붙인다.

   SCAFFOLD_USER="<사용자 이름>" SCAFFOLD_EMAIL="<사용자 메일>" SCAFFOLD_TOOLS=claude SCAFFOLD_PUSH=n scaffold/new-project.sh ~/Projects/my-study my-study "한 줄 설명"
   SCAFFOLD_USER="<사용자 이름>" SCAFFOLD_EMAIL="<사용자 메일>" SCAFFOLD_PUSH=n scaffold/new-project.sh ~/Projects/old-study old-study "한 줄 설명" --existing

   새 저장소의 브랜치는 main이다. 겹치는 파일이 있으면 아무것도 바꾸지 않고 멈춘다. --existing은 어느 자리에 붙여도 되고, 기존 파일을 덮지 않는다. 겹치는 AGENTS.md, CLAUDE.md, README.md, .gitignore는 .scaffold를 붙여 두므로 기존 파일과 손으로 합친다.
4. 만든 폴더의 docs/설정.md를 사용자와 채운다(도구, 역할별 모델, 원고의 언어와 투고처와 쪽 상한과 마감, 지킬 것).
5. 쓰는 도구를 SCAFFOLD_TOOLS로 준다. 기본은 claude,chatgpt다. Claude Code만 쓰면 SCAFFOLD_TOOLS=claude, Codex만 쓰면 SCAFFOLD_TOOLS=codex이고, 도구가 하나면 인계 노트 없이 세션 기록만 쓰는 틀이 만들어진다. 사용자에게 어떤 도구를 쓰는지 묻지 않았다면 지금 쓰고 있는 도구 하나로 만든다.
6. 원격 저장소 생성과 첫 push는 사용자 확인 뒤에 한다. 명령은 스크립트가 끝에 보인다.
7. 그 뒤로 그 프로젝트에서 일할 때는 그 폴더의 AGENTS.md와 research-session을 따른다.

6. 사용자에게 맞추기

• 문체 스킬 둘(korean-academic-style, english-academic-style)은 이 체계를 만든 한 연구자의 규범이다. 처음 쓰는 사용자에게는 그 사실을 알리고, 그대로 쓸지 자기 규범으로 고쳐 쓸지 묻는다. 묻지 않고 사용자의 원고에 일괄 적용하지 않는다.
• 역할별 모델, 품질 기준의 기본값(심사 횟수, 쪽 상한, 막힌 곳 수)은 프로젝트의 docs/설정.md로 바꾼다. 스킬 파일을 고칠 필요는 없다.
• 공개 저장소를 따로 둘 사용자에게는 공개하면 안 되는 단어 목록을 비공개 쪽에 두고 push 전에 code/scripts/check-banned.sh로 검사하라고 권한다. 훅으로 거는 법은 그 스크립트 머리에 있다(research-scaffold 3절 5번).
• 문서는 국문이다. 사용자가 다른 언어를 쓰면 대화와 보고는 사용자의 언어로 하고, 스킬의 절차는 그대로 따른다.

7. 이 체계로 일할 때 지킬 것

공통 규칙 전체는 research-session 0절에 있다. 그 가운데 처음 쓰는 도구가 가장 자주 어기는 것은 다음과 같다.

• 사용자만 하는 일(제출, 공개 저장소 push, 원격 저장소 생성과 첫 push, 계정과 보안 설정, 사용자 컴퓨터에 설치, 되돌릴 수 없는 결정)은 직전 단계까지만 준비한다. 계획 승인과 실행 승인은 다르다. 이미 만든 비공개 연구 저장소의 일상 push는 그 프로젝트의 AGENTS.md와 research-session 3절을 따른다.
• 결과를 본 뒤 기준을 바꾸지 않는다. 바꿔야 하면 사용자가 정하고 승인기록에 남긴다.
• 검산과 심사는 새로 띄운 에이전트가 하고, 앞선 대화와 집계 코드를 넘기지 않는다. 따로 띄울 수 없는 환경이면 그 사실을 보고에 적는다.
• 문헌을 지어내지 않는다. 찾지 못했으면 찾지 못했다고 쓰고 쓴 검색어를 남긴다.
• 결과와 숫자를 숨기거나 바꾸지 않는다. 하지 않은 일과 확인하지 못한 것은 그렇다고 적는다.
• 사용자가 자리를 비운 동안에는 승인된 맡김 지시서 없이 돌리지 않고, 사용자 검토 전에 결과를 main에 합치지 않는다.
• 시각은 date로 읽는다.
• 진행을 숨기지 않는다. 일곱 상태어([예정] [진행] [대기] [막힘] [멈춤] [완료] [건너뜀])로 적고, 응답 없는 에이전트를 [진행]으로 두지 않는다. 2분 넘게 걸릴 일 직전에는 무엇을 기다리는지, 어림, 다음 알림 시각을 보인다.

8. 이 저장소를 고칠 때

사용자가 이 체계를 자기 판으로 바꾸려 하면 저장소를 fork하거나 복사해서 고치게 한다. 원 저장소에 고친 것을 보내려면 pull request로 한다. 어느 쪽이든 공개 저장소에는 사람 이름, 연구 이름, 투고처, 개인 경로, 발표 전 측정값을 넣지 않는다. 용어는 docs/용어집.md를, 국문 문서는 korean-academic-style을 따른다. 스킬을 고치면 skills/README.md의 표와 이 파일 2절의 표도 맞춘다. 고친 뒤에는 저장소 루트에서 code/scripts/selftest.sh를 돌린다.

이 저장소에 커밋할 때는 먼저 git config user.name과 git config user.email을 확인한다. 작성자는 저장소 관리자이고, 메일은 관리자의 GitHub 계정에 등록된 주소를 쓴다(그래야 커밋이 그 계정에 잡힌다). 도구는 작성자가 되지 않고, 메시지 끝에 Co-Authored-By: <도구 이름> <주소> 줄을 붙여 공동 작성자로 적는다. 커밋 메시지에도 사람 이름, 연구 이름, 개인 경로를 쓰지 않는다. 공개 이력은 나중에 지우기 어렵다.