Community라이팅 & 에디팅github.com

jieun1218/codex-research-project-skills

연구 포트폴리오 및 반복적 프로젝트 워크플로를 위한 Codex 스킬

codex-research-project-skills란 무엇인가요?

이 스킬은 연구 프로젝트가 진행됨에 따라 체계적으로 관리될 수 있도록 설계된 반복 작업 워크플로입니다. 핵심 원칙은 작업을 분류하고, 가장 좁은 범위에 기록하며, 증거를 보관하고, 필요한 요약과 보드만 동기화하는 것입니다. '아이디어 → 새로운 하위 프로젝트' 방식을 통해 실험 시도를 핵심 작업 단위로 삼아, 하나의 시도를 덮어쓰거나 무한 반복하지 않고 새로운 시도 폴더를 만들어 작업을 이어나갑니다. 이는 기록을 추가 전용으로 유지하고 비교 가능하게 만들어, 연구 과정을 투명하고 추적 가능하게 합니다. 또한, 프로젝트 진행 상황을 한눈에 파악할 수 있는 `PROJECT_BOARD.html`을 제공하며, 이 보드는 현재 상태를 보여주는 지도 역할을 하고 증거 파일을 가리킵니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있으며, 단일 프로젝트로 독립 실행하거나 포트폴리오 시스템의 일부로 통합하여 사용할 수 있습니다.

지원 대상~Claude Code✓Codex CLI~Cursor
npx skills add jiangjin1999/codex-research-project-skills

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

연구 프로젝트 반복 (Iterate Research Project)

이 스킬을 사용하여 연구 프로젝트의 변경 사항을 체계적으로 추적하고 관리하세요. 핵심 습관은 다음과 같습니다: 작업을 분류하고, 가장 좁고 지속 가능한 장소에 기록하며, 증거를 기록한 후, 협력자에게 필요한 요약과 보드만 동기화합니다.

모든 작업에 적용되는 두 가지 규칙:

  1. 마크다운 우선, 보드는 그 다음. 소스 마크다운 또는 _ai 노트를 먼저 업데이트하세요. 그 후에만 PROJECT_BOARD.html을 동기화합니다.
  2. 보드는 지도이지, 로그가 아닙니다. PROJECT_BOARD.html은 현재 상태를 보여주고 증거를 가리킵니다. 원시 로그, 개인 데이터, 절대 경로를 절대 저장하지 않습니다.

반복을 주도하는 한 가지 습관: 새로운 아이디어 → 새로운 하위 프로젝트. 실험 시도가 작업의 핵심입니다. 시도할 것이 있을 때, 기존 시도를 덮어쓰거나 무한 반복하지 말고 새 0-Project/<날짜>_<슬러그>/ 폴더를 만들어 그 안에서 반복하세요. 하위 프로젝트는 작고 단일 목적으로 유지하며, 중복을 두려워하지 마세요. 이렇게 하면 기록이 추가 전용으로 유지되어 비교 가능해집니다 (references/project-iteration-system.md 참조).

하위 프로젝트에는 또한 레인이 있습니다:

  • 메인 라인 (Mainline) — 현재 진행 중인 활성 경로를 정의하는 시도입니다.
  • 보류 (Parked) — 연구적 사고가 완전히 직렬적이지 않기 때문에 미리 캡처한 미래 시도 아이디어지만, 아직 실행되지 않은 것입니다. 기본 노트: 0-Project/_parking-lot.md.
  • 보관됨 (Archived) — 중단 사유와 증거를 함께 보관된, 포기되거나 대체된 시도입니다. 기본 폴더: 0-Project/_archive/.

저렴하게 보류하세요. 미래 아이디어는 _ai/task_plan.md, 1-Docs/, 또는 0-Project/_parking-lot.md에 짧은 항목으로 남길 수 있습니다. 아이디어가 충분한 입력, 기준, 또는 인계 가치를 가질 때만 전체 시도 폴더를 만드세요.

논의와 시도를 별도로 분류하세요: 논의, 결정, 비교, 방법 설명은 1-Docs/<날짜>_<주제>.md로 이동합니다. 입력, 기준, 출력 또는 결과가 있는 구체적인 실험은 0-Project/<날짜>_<슬러그>/로 이동합니다. 시도-로컬 논의는 0-Project/<시도>/docs/<날짜>_<주제>.md로 이동합니다.

독립 실행 또는 포트폴리오 내에서. 이 스킬은 자체 완결적입니다: 단일 프로젝트를 위해 어떤 경로에서든 독립적으로 사용할 수 있습니다 — 포트폴리오가 필요하지 않습니다. 프로젝트에 필요한 모든 것(폴더, 진입 파일, 보드, 작업 메모리, Git 정책)은 프로젝트 폴더 안에 있습니다. 선택적으로, 프로젝트가 포트폴리오 (<슬러그>-project/<project>/) 안에 있을 때, manage-research-portfolio 스킬을 사용하여 상태, 소유자, 우선순위, 공개 상태를 포트폴리오 대시보드에 동기화합니다. 독립 실행 시, 이 스킬의 모든 "포트폴리오 대시보드" 및 "레지스트리" 단계를 건너뛰세요 — 이는 선택적 통합이며, 필수 조건이 아닙니다.

프로젝트 계약 (Project Contract)

프로젝트에 이미 동등한 이름이 없는 한 이 구조를 사용하세요. 이것은 복사 가능한 _PROJECT_TEMPLATE 스켈레톤입니다.

<project>/
├── README.md              진입점: 한 문장 목표, 폴더 맵, 빠른 시작, 현재 상태
├── PROJECT_GUIDELINES.md  프로젝트-로컬 동기화 규칙, 폴더 경계, HTML 분류
├── PROJECT_BOARD.html     보드 (看板): 현재 상태 지도 및 탐색
├── GIT_WORKFLOW.md        이 프로젝트의 Git 신원 + 변경별 커밋 정책
├── scripts/
│   └── init_project_git.sh   신원 설정 및 첫 커밋을 위한 선택적 도우미
├── 0-Project/             구체적인 시도 / 실험 (시도당 하나의 0-Project/<날짜>_<슬러그>/)
├── 1-Docs/
│   └── README.md          단일 고정 문서 진입점 + 주제 색인
├── 2-Data/
│   └── DATA.md            출처, 출처 증명, 권한, 버전, 스키마, QC, 경계
├── 3-Paper_Survey/
│   └── README.md          읽기 큐, 논문 노트, 증거 매트릭스, 방법 출처
├── 4-Skills/
│   └── PROJECT_SKILLS.md  프로젝트-로컬 프롬프트, AI 규칙, 재사용 가능한 절차
└── _ai/
    ├── project_overview.md   목표, 범위, 상태, 소유자, 우선순위, 다음 단계
    ├── project_board_spec.md PROJECT_BOARD.html이 소스에서 생성/동기화되는 방법
    ├── task_plan.md          현재 단계, 계획, 차단 요인, 다음 단계
    ├── findings.md           안정적인 발견, 미해결 질문
    └── progress.md           가장 최근의 의미 있는 동기화, 작업, 검증, 커밋

루트 파일은 진입점 + 규칙 + 보드 + Git 정책입니다. 모든 구체적인 내용은 가장 일치하는 번호가 매겨진 폴더로 이동합니다. 프로젝트 루트에 자료를 쌓지 말고, 프로젝트 개요, 보드 규칙 또는 장기 지침을 0-Project/ 안에 넣지 마십시오 (해당 폴더는 구체적인 시도 전용입니다).

쓰기 전에 분류 (Classify Before Writing)

사용자가 새 자료를 제공하면, 하나의 저장 위치를 선택한 다음 보드가 변경되는지 결정하세요.

사용자 의도저장 위치보드 뷰에 영향을 줄 수 있음
"이것은 논의 / 방법 / 결정 / 비교입니다"1-Docs/<날짜>_<주제>.md + 1-Docs/README.md 업데이트문서 지도 (Docs Map)
"이것은 구체적인 실험 / 시도입니다"0-Project/<날짜>_<슬러그>/; 시도-로컬 노트는 docs/ 아래에 배치작업 (Tasks)
"이것은 기존 시도에 대한 노트입니다"0-Project/<시도>/docs/<날짜>_<주제>.md일반적으로 작업, 프로젝트 수준 색인을 변경하면 문서 지도
"이것은 미래 시도 아이디어입니다"_ai/task_plan.md, 1-Docs/, 또는 0-Project/_parking-lot.md; 구체적인 경우에만 전체 시도 폴더일반적으로 없음, 또는 보류된 작업 레인
"이 시도는 중단 / 대체되었습니다"시도 폴더 유지 또는 0-Project/_archive/로 이동; 중단 사유, 증거 및 대체 항목과 함께 보관됨으로 표시보관됨/축소된 작업 레인
"이것은 데이터 / 벤치마크 정보입니다"2-Data/DATA.md자료 (Materials)
"이것은 논문 / 외부 출처 / 증거입니다"3-Paper_Survey/README.md + 증거 매트릭스참고문헌 (References)
"이것은 재사용 가능한 워크플로 / 프롬프트 / AI 규칙입니다"4-Skills/PROJECT_SKILLS.md(일반적으로 없음)
"이것은 상태 / 다음 조치 / 차단 요인을 변경합니다"_ai/project_overview.md, _ai/task_plan.md상단 개요 + 진행 상황

분류가 프로젝트 범위, 평가 기준, 데이터 경계, 공개 노출, 또는 시도가 프로젝트에 속하는지 여부를 변경하는 경우, 확인된 것으로 처리하기 전에 질문하십시오. 위험이 낮은 이름 지정/형식 지정의 경우 보수적인 옵션을 선택하고 가정을 _ai/progress.md에 기록하십시오.

보드 (看板)

PROJECT_BOARD.html은 단일 프로젝트 보드입니다. 한눈에 다음을 알 수 있습니다: 이 프로젝트가 무엇인지, 현재 상태는 무엇인지, 무엇이 변경되었는지, 증거는 어디에 있는지, 그리고 어디서 계속할지. 폴더와 조정됩니다 — 각 뷰는 특정 폴더 또는 _ai 파일에서 제공됩니다.

기본 요소:

  • 홈 / 뒤로 가기 링크 (영구): 페이지 맨 앞, 왼쪽 상단 브랜드 영역에 링크. 포트폴리오 내에 있는 경우 사이트 루트 /를 가리키는 대시보드로 돌아가기 링크로 만드십시오. 독립 실행형인 경우 생략하거나 프로젝트 자체 README.md를 가리키십시오. 페이지를 생성, 복사, 게시 또는 업데이트할 때 선택한 것을 유지하십시오.

  • 버전 상태: 페이지 버전 YYYY-MM-DD-vN 및 마지막 동기화 마커 (선택적으로 최신 상태/새로 고침 컨트롤).

  • 상단 개요 (항상 표시, 가볍게): 프로젝트 이름, 한 문장 설명, 상태, 소유자, 최근 동기화, 현재 초점, 그리고 최대 한 줄의 진행 라인. 출처: _ai/project_overview.md. 단계 목록, 버전 카드, 시도 목록 또는 장기 경로를 여기에 두지 마십시오.

  • 다섯 개의 상호 배타적인 뷰, 각각 폴더에 매핑됨:

    뷰제공 대상표시 내용
    진행 상황 (Progress)_ai/progress.md, _ai/findings.md, 1-Docs/README.md목표, 범위, 단계, 주요 출력, 판단, 공개 상태, 간결한 버전 요약 등 프로젝트 수준의 주요 변경 사항만
    문서 지도 (Docs Map)1-Docs/README.md + 루트 구조문서 주제 색인 + VS Code 탐색기 스타일 구조 트리 (루트 레벨-1 파일/폴더 및 <details>/<summary>를 통한 레벨-2), 공개 안전 이름만
    작업 (Tasks)0-Project/<시도>/메인라인 시도 우선; 보류된 미래 시도 및 보관됨/더 이상 사용되지 않는 시도는 별도의 축소된 레인에만 표시
    자료 (Materials)2-Data/DATA.md데이터 블록, 공개 여부, 버전, 품질, 사용 경계
    참고문헌 (References)3-Paper_Survey/README.md논문, 방법 출처, 증거 상태, 영향; 내용이 있는 경우에만

보드 규칙: 소유자, 상태, 우선순위 또는 미래 단계를 발명하지 마십시오. 독립형 "다음 단계" 뷰를 추가하지 마십시오 (다음 조치는 상단 개요, _ai/task_plan.md 또는 시도에 있음). 시도 및 구조 트리에 축소된 <details>를 사용하십시오. 조용한 연구 워크벤치로 유지하고 랜딩 페이지로 만들지 마십시오. 미래 아이디어와 중단된 시도는 활성 경로와 시각적으로 경쟁해서는 안 됩니다. 생성 규칙은 _ai/project_board_spec.md에 있습니다. 전체 계약은 references/project-board.md를 참조하십시오.

반복 루프 (Iteration Loop)

  1. _ai/project_overview.md, _ai/project_board_spec.md, _ai/task_plan.md, _ai/findings.md, _ai/progress.md 및 관련 폴더 README에서 컨텍스트를 복원합니다.
  2. 프로젝트 파일을 편집하기 전에 운영자의 Git 신원을 확인합니다. 누락된 경우 사용자에게 직접 구성하도록 요청하고 일시 중지합니다.
  3. 현재 반복을 한 문장으로 명명합니다: 질문, 시도 또는 결정.
  4. 먼저 가장 좁은 소스 파일을 생성하거나 업데이트합니다.
  5. 방향을 바꾸는 발견 사항을 _ai/findings.md에 기록합니다. 작업, 검증 및 실패 경로를 _ai/progress.md에 기록합니다.
  6. 단계, 차단 요인 또는 다음 조치가 변경될 때 _ai/task_plan.md를 업데이트합니다.
  7. 컨텍스트 압축 전, 작은 단계 완료 후, 또는 주제/하위 프로젝트 전환 전에 가장 좁은 일치하는 Markdown 파일에 간결한 인계를 작성합니다.
  8. 동기화 척도를 적용하여 PROJECT_BOARD.html을 건드릴지 결정한 다음, 변경된 안전한 파일을 명시적 경로와 함께 커밋합니다.

컨텍스트 압축 및 인계 위생 (Context Compression And Handoff Hygiene)

대화 비용이 많이 들기 전에 사전에 컨텍스트를 기록하십시오. 컨텍스트 창이 커지거나, 작은 단계가 완료되거나, 하위 프로젝트가 결정 지점에 도달하거나, 다음 조치가 다른 주제, 프로젝트 또는 시도로 전환될 때 이 작업을 수행하십시오.

가장 좁은 위치를 선택하십시오:

상황인계 위치
프로젝트 수준 논의, 결정 또는 방법 노트1-Docs/<날짜>_<주제>.md
시도 수준 단계, 관찰 또는 로컬 논의0-Project/<시도>/docs/<날짜>_<주제>.md
프로젝트 상태, 차단 요인, 다음 조치 또는 검증 요약_ai/progress.md, _ai/findings.md, _ai/task_plan.md
교차 프로젝트 또는 포트폴리오 컨텍스트포트폴리오가 존재하는 경우 해당 포트폴리오의 <슬러그>-ai/<날짜>_<주제>.md

최소 인계 필드: 현재 목표, 완료된 단계, 주요 결정, 증거 경로, 미해결 질문, 다음 조치 및 보드 동기화 필요 여부. 간결하게 유지하십시오. 전체 대화 기록이나 원시 로그를 붙여넣지 마십시오.

동기화 척도 (Sync Scale)

보드를 편집하기 전에 모든 변경 사항을 이 척도로 판단하십시오.

수준트리거업데이트
0읽기 전용 탐색, 새로운 결정 없음없음
1사소한 발견, 작은 실패 분기, 임시 노트Markdown 또는 _ai만
2새 아티팩트/경로/QC 결과, 차단 요인, 다음 조치, 상태, 문서 지도, 구조 트리, 데이터 경계, 참고문헌 또는 시도 변경됨소스 Markdown 또는 _ai, 그런 다음 PROJECT_BOARD.html 동기화
3단계, 이정표, 공개 주장, 소유자, 우선순위 또는 공개 상태 변경됨소스 Markdown, 보드, PROJECT_GUIDELINES.md, 그리고 프로젝트가 포트폴리오에 속하는 경우에만 포트폴리오 대시보드

컨텍스트 인계 노트는 일반적으로 수준 1입니다. 다음 조치, 상태, 차단 요인, 문서 지도, 데이터 경계, 참고문헌 상태 또는 시도 상태를 변경하는 경우에만 수준 2로 올리십시오.

모든 편집 시 보드를 동기화하지 마십시오. 협력자가 새 상태를 필요로 할 때 동기화하십시오.

하위 프로젝트 기록 (Subproject Records)

각 0-Project/<날짜>_<슬러그>/README.md는 다음 질문에 답해야 합니다: 시도가 테스트하는 질문; 사용하는 입력, 논문, 데이터 노트 또는 가정; 실행되거나 추론된 내용 (목표, 가설, 입력, 명령, 메트릭); 실패, 변경 또는 안정화된 내용; 결론 및 다음 조치; 그리고 프로젝트 상태, 데이터 노트, 문헌 노트 또는 보드에 영향을 미치는지 여부. 시도-로컬 논의, 단계 인계 및 설계 노트는 해당 시도의 docs/ 폴더에 넣으십시오.

실패한 시도를 기록하십시오. 명확한 이유가 있는 실패 경로는 유용한 프로젝트 자산입니다. 중단되거나 대체된 경우, 중단 사유, 대체 항목(있는 경우), 마지막 증거 및 반복하지 말아야 할 사항과 함께 보관됨으로 표시하십시오. 안정적인 단계 또는 결정 지점에 도달한 후에만 보조 축소 항목으로 보드에 표시하십시오.

데이터 및 문헌 (Data And Literature)

  • 2-Data/DATA.md를 출처 증명, 버전, 액세스 클래스, 허용 위치, 스키마, QC 및 파생 아티팩트 경계에 사용하십시오. 프로젝트 파생 데이터(특징, 궤적, 분석 준비 테이블, QC 중간물)는 전역 데이터 영역이 아닌 이 프로젝트의 2-Data/ 아래에 보관하십시오. 원시 민감 레코드, 신원을 나타내는 예, 자격 증명 또는 미공개 발췌문을 노트, 보드 또는 공개 사본에 절대 작성하지 마십시오.
  • 3-Paper_Survey/README.md를 방법, 평가, 범위 또는 해석을 변경할 수 있는 증거에 사용하십시오. 문제, 방법, 데이터 또는 벤치마크, 결과, 한계 및 이 프로젝트에 대한 시사점별로 논문을 요약하십시오. 여러 출처가 하나의 주장에 영향을 미칠 때 증거 매트릭스를 사용하십시오. 긴 인용문보다 간결한 의역 및 링크를 선호하십시오.

참고자료 (References)

  • 프로젝트 구조, 진입 파일, 하위 프로젝트, 작업 메모리 파일 또는 동기화 규칙을 생성할 때 references/project-iteration-system.md를 읽으십시오.
  • PROJECT_BOARD.html을 생성, 검토 또는 동기화할 때 references/project-board.md를 읽으십시오.
  • 데이터 노트, 벤치마크 출처 증명, 문헌 요약 또는 증거-결정 업데이트를 처리하기 전에 references/data-and-literature.md를 읽으십시오.

관련 스킬