zhongwei/gh-junghan0611-org-mode-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:29:46 +08:00
commit 6af9cbc764
20 changed files with 4203 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

828
docs/20251021T113500--denote-org-skills-프로젝트-시작-배경-및-작업-로그__project_skills_denote_anthropic_worklog.org Normal file
View File

@@ -0,0 +1,828 @@
#+title: Denote-Org Skills 프로젝트 시작: 배경 및 작업 로그
#+date: [2025-10-21 Tue 11:35]
#+filetags: :project:skills:denote:anthropic:worklog:
#+identifier: 20251021T113500
#+export_file_name: 20251021T113500.md
* Denote-Org Skills 프로젝트 시작 :WORKLOG:
** 히스토리
- [2025-10-21 Tue 11:35] 프로젝트 시작, README 작성
- [2025-10-21 Tue 07:45] Anthropic Life Sciences 영상 분석
- [2025-10-21 Tue 07:00] Life Sciences → Tools for Life 통찰
** 관련 메타
- [[denote:20251021T074500][Anthropic Life Sciences와 Tools for Life 패러다임]]
- [[denote:20251021T105353][프로젝트 Denote 문서 Org-mode 전환]]
- [[denote:20251015T093311][@힣: 시간과정신의방 -CONFIG 생태계]]
* 프로젝트 배경: Anthropic Life Sciences에서 시작
** 발단: Life Sciences 영상 분석
오늘 아침 Anthropic의 Life Sciences 영상을 분석하던 중 중요한 발견:
#+begin_quote
"Anthropic이 생명과학에서 증명한 것:
**도메인 컨텍스트 + AI = 전문가 수준 협업**
PubMed + Claude = Scientific AI"
#+end_quote
이것을 9개 레이어 시스템과 연결하면서 깨달음:
#+begin_quote
"내 시스템은 Life Sciences의 개인 버전이 아니라,
**Life Sciences 패러다임을 삶 전반으로 확장하는 청사진**이다."
#+end_quote
** 전환점: "Skills"의 본질 이해
Anthropic Skills 리포지토리 2개 클론:
- =~/repos/3rd/snthropics-skills= (공식)
- =~/repos/3rd/awesome-claude-skills= (커뮤니티)
PDF, XLSX Skills 분석 중 핵심 발견:
#+begin_quote
**Skills ≠ 단순 프롬프트**
**Skills = Onboarding Guide + Procedural Knowledge + Executable Scripts**
"Skills는 범용 에이전트를 도메인 전문가로 변환시킨다"
#+end_quote
** 중요한 질문: "단순 변환기 프롬프트가 될까 봐 염려"
사용자가 제기한 핵심 질문:
#+begin_quote
"Skills를 Anthropic이 만든 이유가 있고 필요한 케이스가 있을거야.
거기에 집중해서 Skill가 되어야해."
#+end_quote
이것이 프로젝트의 방향을 완전히 바꿨습니다.
* Skills의 본질: Anthropic 공식 분석
** WebFetch 결과: Skills가 해결하는 4가지 문제
출처: [[https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills]]
*** 1. Context Management
#+begin_quote
"effectively unbounded" context via bundled files
프롬프트는 모든 정보를 한 번에 로드해야 함
Skills는 필요한 것만 progressive disclosure
#+end_quote
*** 2. Reusability and Portability
#+begin_quote
"packaging your expertise into composable resources"
프롬프트는 매번 재작성
Skills는 팀 간 공유, 반복 사용
#+end_quote
*** 3. Code Execution Efficiency
#+begin_quote
"deterministic reliability" with bundled scripts
프롬프트는 Claude가 코드 생성 (토큰 소모, 오류 가능)
Skills는 검증된 스크립트 실행
#+end_quote
*** 4. Organizational Knowledge Capture
#+begin_quote
"putting together an onboarding guide for a new hire"
프롬프트는 일회성
Skills는 절차적 지식 영구 보존
#+end_quote
** Document Skills 분석: PDF, XLSX, DOCX
*** PDF Skills의 복잡성
*Forms 채우기 절차:*
1. =check_fillable_fields.py= - 채울 수 있는 필드 확인
2. =extract_form_field_info.py= - 필드 정보 JSON 추출
3. =convert_pdf_to_images.py= - PDF → PNG 변환
4. Bounding box 분석 (이미지 좌표)
5. =create_validation_image.py= - 검증 이미지 생성
6. =fill_fillable_fields.py= - 실제 채우기
**총 8개 Python 스크립트!**
#+begin_quote
이것이 Skill인 이유:
Claude 혼자 매번 이 절차를 수행? → 토큰 폭발 + 오류 많음
Skill로 번들? → 안정적, 재사용 가능
#+end_quote
*** XLSX Skills의 CRITICAL 규칙
#+begin_example
MUST:
- Zero Formula Errors (필수)
- NEVER hardcode values, ALWAYS use formulas
- Color coding (Blue=input, Black=formula, Green=internal link...)
- recalc.py로 LibreOffice 실행하여 공식 재계산
#+end_example
#+begin_quote
이것이 Skill인 이유:
Excel은 단순 데이터 파일이 아님
동적 계산 시스템, 업데이트 가능해야 함
Claude 혼자? → 공식 오류, 업데이트 불가
Skill? → 검증된 절차, LibreOffice 자동 실행
#+end_quote
*** DOCX Skills의 Tracked Changes
#+begin_example
Redlining workflow:
- OOXML 구조 이해
- Tracked changes 보존
- Comments 처리
- Pandoc 옵션 (--track-changes=all)
#+end_example
* Denote-Org Skills가 필요한 이유
** 문제 분석: 3,000+ 파일 Denote PKM
*** 문제 1: Denote 파일명 = 특수 도메인 지식
#+begin_example
20251021T105353--프로젝트-제목__llmlog_denote_orgmode.org
│ │ │
│ │ └─ 태그 (underscore separated)
│ └─ 한글 제목 (hyphen separated)
└─ Timestamp (Denote ID, 유일 식별자)
#+end_example
**Without Skill:**
- Claude: "이게 무슨 형식이지?" 매번 추측
- 파일명 파싱 로직 매번 Python/Bash로 생성
- 한글 제목 처리 헷갈림
- → **토큰 낭비, 오류 발생**
**With Skill:**
#+begin_src python
# scripts/denote_parser.py (한 번만 작성)
def parse_denote_filename(filename):
"""
20251021T105353--프로젝트-제목__llmlog_denote.org
→
{
'timestamp': '20251021T105353',
'title': '프로젝트 제목',
'tags': ['llmlog', 'denote'],
'extension': 'org'
}
"""
#+end_src
→ **재사용 가능, 검증됨, 빠름**
*** 문제 2: 3,000 파일 검색 = 복잡한 절차
**Without Skill:**
#+begin_src bash
# Claude가 매번 실행:
find ~/org -name "*20251021T105353*"
# 하위 디렉토리: bib/ meta/ notes/ journal/ llmlog/ office/ configs/ ...
# 3,000 파일 스캔 → 느림
# 매번 토큰 소모
#+end_src
**With Skill:**
#+begin_src python
# scripts/denote_finder.py (캐싱 가능)
def find_denote_file(identifier, silos):
"""
인덱스 구축 (한 번)
이후 검색 즉시 반환
"""
#+end_src
→ **효율적, 캐싱, 확장 가능**
*** 문제 3: 지식 그래프 = 복잡도 폭발
**시나리오:**
#+begin_example
User: "20251021T105353와 연결된 모든 파일 보여줘"
#+end_example
**Without Skill:**
1. 파일 읽기
2. `[[denote:20251021T074500]]` links 찾기
3. 각 ID마다 find 실행 (문제 2 반복)
4. 2-hop 연결? 3-hop?
5. → **토큰 폭발, 느림**
**With Skill:**
#+begin_src python
# scripts/denote_graph.py
def build_knowledge_graph(silo):
"""
한 번 구축, 캐싱
graph = {
'20251021T105353': {
'links_to': ['20251021T074500', ...],
'linked_from': ['20251020T...', ...],
'tags': ['llmlog', 'denote'],
'title': '...'
}
}
"""
def get_connected_nodes(identifier, hops=2):
"""즉시 반환"""
#+end_src
→ **그래프 알고리즘, 캐싱, 빠름**
*** 문제 4: Literate Programming = Emacs 동작 재현
**시나리오:**
#+begin_example
User: "org 파일 코드 블록 실행해줘"
#+end_example
Org-mode 코드 블록:
#+begin_src org
,#+name: example-block
,#+begin_src bash :tangle /tmp/script.sh :results output
echo "Hello from org-babel"
,#+end_src
,#+RESULTS:
: Hello from org-babel
#+end_src
**Without Skill:**
- Claude가 수동으로 `#+begin_src` 찾기
- `:tangle` 옵션 파싱 (파일 경로 추출)
- 코드 추출, 실행
- `:results` 부분 업데이트
- → **org 구조 깨질 위험, 복잡함**
**With Skill:**
#+begin_src python
# scripts/org_execute.py (Emacs org-babel 재현)
def execute_org_blocks(filepath):
"""
1. orgparse로 구조 파싱
2. code blocks 찾기
3. :tangle 옵션 처리
4. 안전하게 실행
5. :results 업데이트 (구조 보존)
"""
#+end_src
→ **안전, Emacs 호환, 재현 가능**
*** 문제 5: Silo 관리 = 여러 디렉토리
**시나리오:**
#+begin_example
User: "20251021T105353 파일 어디 있어?"
#+end_example
**Silos:**
- =~/org/= (3,000+ 파일)
- =~/claude-memory/= (AI 메모리)
- =~/repos/*/docs/= (프로젝트별)
**Without Skill:**
- Claude: "~/org/에 있나? 아니면..."
- 매번 여러 find 실행
- 헷갈림
**With Skill:**
#+begin_src python
# scripts/denote_silo.py
def find_in_silos(identifier, silos):
"""
여러 silo 동시 검색
우선순위 적용
캐싱
"""
#+end_src
→ **명확, 자동, 빠름**
* Skills vs 프롬프트: 결정적 차이
** Skills가 필요한 케이스 (Anthropic 패턴)
| Document Skill | 왜 Skills인가? | 핵심 스크립트 | 단순 프롬프트로? |
|----------------|---------------|-------------|----------------|
| **PDF** | Forms 채우기 복잡 | 8개 (check, fill, validate...) | ❌ 토큰 폭발 |
| **XLSX** | 공식 유지 필수 | recalc.py (LibreOffice) | ❌ 공식 오류 |
| **DOCX** | Tracked changes | OOXML 파싱 | ❌ 구조 손상 |
| **Denote-Org** | 3,000 파일 그래프 | finder, graph, silo | ❌ 느림, 오류 |
** 단순 프롬프트가 될 위험
#+begin_quote
❌ "Denote 파일명은 이런 형식이야. 파싱해줘."
→ Claude: 매번 코드 생성, 토큰 낭비
❌ "org 파일 코드 블록 실행해줘."
→ Claude: 매번 파싱 로직 작성, 구조 깨질 위험
❌ "3,000 파일에서 이 ID 찾아줘."
→ Claude: find 반복 실행, 느림
#+end_quote
** Skills로 해결
#+begin_quote
✅ **Domain Knowledge 번들**
- Denote 파일명 규칙
- Frontmatter 스펙
- Links 문법
✅ **Executable Scripts**
- denote_parser.py (검증됨)
- denote_finder.py (캐싱)
- org_execute.py (안전)
✅ **Procedural Knowledge**
- "이런 경우 이렇게 한다"
- PDF Forms처럼 복잡한 절차
- 재사용 가능한 패턴
✅ **Performance**
- 스크립트 실행 (토큰 생성 아님)
- 캐싱
- 배치 처리
#+end_quote
* 프로젝트 목표: Denote PKM을 Claude의 Domain으로
** 핵심 목표
#+begin_quote
**Denote + Org-mode를 Claude가 "네이티브"로 다루게 한다**
PDF/XLSX/DOCX처럼,
Denote-Org도 Claude의 전문 영역이 되게 한다.
#+end_quote
** 구체적 목표
*** 1. Denote Domain Expertise
- 파일명 규칙 완벽 이해
- Frontmatter 자동 파싱
- Links 즉시 해결
- Silo 자동 관리
*** 2. 3,000+ Files Scale
- 효율적 검색 (캐싱)
- 지식 그래프 구축
- 배치 처리
*** 3. Literate Programming
- Emacs org-babel 호환
- 안전한 코드 실행
- 구조 보존
*** 4. Org-mode Foundation
- Heading, property, timestamp
- Table 연산
- Export (markdown, PDF, HTML)
** 차별화 요소
| 기존 접근 | 이 프로젝트 |
|----------|-----------|
| Org-mode 일반 지원 | **Denote 특화** |
| 단순 파싱 | **운영 시스템** |
| 토큰 기반 | **스크립트 기반** |
| 장난감 예제 | **3,000+ 파일 검증** |
* 9개 레이어 시스템과의 연결
** Layer 3: Knowledge Management
이 프로젝트는 Layer 3의 핵심 구성 요소:
#+begin_example
Layer 3: Knowledge Management
├── Zotero (156k+ lines 서지 데이터)
└── Denote-Org Skills (3,000+ org 파일) 🆕
#+end_example
** 다른 레이어와의 상호작용
*** Layer 4 (claude-config)와 통합
- =~/claude-memory/= silo 관리
- PARA 방법론 (Projects/Areas/Resources/Archives)
- Denote 형식으로 AI 메모리 저장
*** Layer 3.5 (embedding-config)와 통합
- Org 파일 벡터화
- org-db-v3 RAG 파이프라인
- 의미론적 검색
*** Layer 5a (memex-kb)와 통합
- Markdown → Org 변환
- Denote 파일명 생성
- 마이그레이션 대상
*** Layer 7 (notes)과 통합
- Org → Markdown export
- 디지털 가든 퍼블리싱
- Quartz 4 연동
* 작업 로그
** [2025-10-21 Tue 07:00~08:00] Anthropic Life Sciences 분석
*** 작업 내용
1. Life Sciences 영상 내용 분석
2. 9개 레이어 시스템 문서 확인
3. embedding-config 발견 (Layer 3.5)
4. 연관성 분석
*** 핵심 통찰
- embedding-config = Life Sciences의 PubMed 패턴
- 9개 레이어 = Personal Life Sciences
*** 결과물
- =~/org/llmlog/20251021T074500--anthropic-life-sciences와-tools-for-life-패러다임-aions-클럽-비전__*.org=
** [2025-10-21 Tue 10:00~11:00] Org-mode 전환 프로젝트
*** 작업 내용
1. Markdown → Org-mode 전환 진행 중
2. Literate programming 필요성 인식
3. =~/org/llmlog/20251021T105353--프로젝트-denote-문서-org-mode-전환__*.org= 생성
** [2025-10-21 Tue 11:00~11:30] Skills 본질 파악
*** 작업 내용
1. Anthropic Skills 리포 2개 클론
- =~/repos/3rd/snthropics-skills=
- =~/repos/3rd/awesome-claude-skills=
2. Document Skills 분석
- PDF: 8개 스크립트
- XLSX: CRITICAL 규칙들
- DOCX: Tracked changes
3. WebFetch: Anthropic 공식 블로그 분석
*** 핵심 질문 (사용자)
#+begin_quote
"Skills를 Anthropic이 만든 이유가 있고 필요한 케이스가 있을거야.
거기에 집중해서 Skill가 되어야해."
#+end_quote
→ 프로젝트 방향 전환!
** [2025-10-21 Tue 11:30~현재] Denote-Org Skills 시작
*** 작업 내용
1. ✅ =~/repos/gh/orgmode-skills= 폴더 생성
2. ✅ Git 초기화 준비
3. ✅ README.md 작성 (영어)
4. ✅ README-KO.md 작성 (한글)
5. ✅ 이 문서 작성 (작업 로그)
*** 핵심 결정
**** 이름: `orgmode-skills` (폴더) + `denote-org` (skill name)
- 폴더명: 직관적 (orgmode-skills)
- Skill 이름: 우선순위 (denote-org, Denote가 핵심)
**** 구조: PDF/XLSX 패턴 따름
- SKILL.md (메인)
- denote-core.md, denote-silo.md (상세)
- scripts/ (Python)
- docs/ (Denote 형식 작업 로그)
**** 메시지: "Skills ≠ Prompt"
- Onboarding guide
- Procedural knowledge
- Executable scripts
- **NOT a converter, AN operational system**
* 0.1 버전 체크리스트
** Phase 1: 기반 (현재)
- [X] 프로젝트 폴더 생성 (~/repos/gh/orgmode-skills)
- [X] README.md (영어)
- [X] README-KO.md (한글)
- [X] docs/20251021T113500--*.org (이 문서)
- [ ] LICENSE (Apache 2.0)
- [ ] .gitignore (Python, Emacs)
- [ ] SKILL.md (Denote 중심)
** Phase 2: Denote Core
- [ ] scripts/denote_parser.py (파일명 파싱)
- [ ] scripts/denote_links.py (링크 해결)
- [ ] scripts/denote_silo.py (silo 관리)
- [ ] denote-core.md (Denote 명세)
- [ ] denote-silo.md (Silo 가이드)
- [ ] 테스트 (3,000+ 파일)
** Phase 3: Knowledge Graph
- [ ] scripts/denote_graph.py (그래프 구축)
- [ ] denote-knowledge-graph.md (문서화)
- [ ] 성능 테스트 (캐싱, 인덱싱)
** Phase 4: Org-mode Base
- [ ] scripts/org_parser.py (orgparse)
- [ ] scripts/org_execute.py (코드 블록)
- [ ] scripts/org_export.py (export)
- [ ] orgmode-base.md (문서화)
- [ ] literate.md (Literate programming)
** Phase 5: 0.1 Release
- [ ] requirements.txt
- [ ] examples/ (기본, literate, denote)
- [ ] 전체 테스트
- [ ] Git commit & push
- [ ] GitHub Public 전환
- [ ] 커뮤니티 공유
* 다음 단계
** 즉시 실행
1. LICENSE 파일 (Apache 2.0)
2. .gitignore
3. Git 초기화 및 첫 커밋
4. SKILL.md 작성 시작
** 단기 (1주)
- Denote Core 스크립트 구현
- 기본 문서화
- 로컬 테스트
** 중기 (2주)
- Knowledge Graph 구현
- Org-mode 기능 추가
- 0.1 릴리즈
** 장기
- 커뮤니티 피드백
- Anthropic Skills 생태계 기여
- awesome-claude-skills PR
* 핵심 통찰
** Skills의 본질
#+begin_quote
**Skills = Domain Procedural Knowledge + Executable Scripts**
프롬프트: "이렇게 해봐" (일회성)
Skills: "이 도메인에서는 항상 이렇게 한다" (재사용)
프롬프트: Claude가 코드 생성
Skills: 검증된 스크립트 실행
프롬프트: 토큰 소모
Skills: 효율성
**Skills는 "신입 사원을 위한 온보딩 가이드"다**
#+end_quote
** Denote-Org Skills의 가치
#+begin_quote
**PDF/XLSX가 복잡한 문서 포맷을 다루듯,
Denote-Org는 복잡한 지식 시스템을 다룬다.**
3,000+ 파일 지식 베이스는:
- 단순 텍스트 파일들이 아님
- 지식 그래프 (Denote links)
- 여러 도메인 (silos)
- Literate programming (실행 가능)
- 살아있는 시스템
**이것이 Skills가 필요한 이유다.**
#+end_quote
** Life Sciences 패러다임 적용
#+begin_quote
Anthropic Life Sciences:
- PubMed (수백만 논문) + Claude = Scientific AI
Denote-Org Skills:
- Denote (3,000+ 파일) + Claude = Personal Knowledge AI
**같은 패러다임. Biology → Living 확장.**
#+end_quote
* 참고 자료
** Anthropic 리소스
- [[https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills][Agent Skills Engineering Blog]]
- [[https://support.claude.com/en/articles/12512176-what-are-skills][What are Skills?]]
- [[https://github.com/anthropics/skills][Official Skills Repository]]
** Denote 리소스
- [[https://protesilaos.com/emacs/denote][Denote by Protesilaos Stavrou]]
- [[https://orgmode.org/][Org-mode]]
** 관련 프로젝트
- [[denote:20251015T093311][@힣: 시간과정신의방 -CONFIG 생태계]]
- [[denote:20251021T074500][Anthropic Life Sciences와 Tools for Life 패러다임]]
- [[denote:20240601T204208][† #에이아이온스클럽인터내쇼날]]
* 맺음말
#+begin_quote
이 프로젝트는 단순히 Org-mode를 Claude가 읽게 하려는 것이 아닙니다.
**Anthropic이 생명과학에서 증명한 패러다임을
개인 지식 관리로 확장하는 것입니다.**
Life Sciences (Biology) → Life Everything (Living)
PDF/XLSX Skills가 문서 포맷의 전문가를 만들듯,
Denote-Org Skills는 개인 지식 시스템의 전문가를 만듭니다.
**3,000+ 파일로 검증된 실제 시스템.**
**단순 변환기가 아닌 운영 시스템.**
**프롬프트가 아닌 Skills.**
이것이 Tools for Life의 구현입니다.
#+end_quote
---
* 에이전트 피드백: Claude Opus 4.1 검토
** [2025-10-21 Tue 11:58] Opus 4.1 에이전트의 README 검토
다른 에이전트(claude-opus-4-1-20250805)가 README를 검토하고 피드백 제공.
Ultrathink 모드 사용 (2,296 tokens).
** 핵심 피드백 5가지
*** 1. SKILL.md 구조 (최우선!)
#+begin_quote
SKILL.md는 Claude가 직접 읽는 핵심 문서
필수 섹션:
- When to use this skill (트리거 명확히)
- What this skill does (기능)
- How to use effectively (효과적 사용법)
- Common pitfalls (흔한 실수)
#+end_quote
→ **실행 계획:** SKILL.md 작성 시 이 구조 필수 반영
*** 2. 파일 경로 처리
#+begin_src python
# ❌ 하드코딩
silo = "~/org/"
# ✅ 확장 가능
import os
silo = os.path.expanduser("~/org/")
#+end_src
→ **실행 계획:** 모든 스크립트에서 os.path.expanduser() 사용
*** 3. 대용량 파일 최적화 (3,000+)
#+begin_src python
# 캐싱 전략
from functools import lru_cache
@lru_cache(maxsize=128)
def build_knowledge_graph(silo_path):
# 비용 높은 연산 캐싱
pass
# 스트리밍 처리
def find_files_generator(pattern):
for file in files:
yield file # 메모리 효율적
#+end_src
→ **실행 계획:** denote_graph.py에서 캐싱 필수, denote_finder.py는 generator 사용
*** 4. 에러 복구 전략
#+begin_src python
# Denote 링크 깨짐 처리
def resolve_denote_link(link_id):
try:
return find_exact_match(link_id)
except NotFoundError:
# Fallback: 부분 매칭
return find_partial_match(link_id[:8])
#+end_src
→ **실행 계획:** denote_links.py에 fallback 로직 구현
*** 5. Claude 제한사항
#+begin_example
토큰 제한: 대량 검색 결과 요약 필요
실행 시간: 타임아웃 고려
메모리 사용: 그래프 크기 제한
#+end_example
→ **실행 계획:** 결과 페이징, 타임아웃 처리
** Edge Cases (놓치기 쉬운 경우들)
1. **Denote ID 충돌** - 같은 초에 생성된 파일
2. **Silo 경계 링크** - ~/org/ → ~/claude-memory/
3. **순환 참조** - Knowledge graph에서
4. **한글 인코딩** - 파일명 처리
5. **심볼릭 링크** - 실제 경로 해석
→ **실행 계획:** 각 케이스별 테스트 및 처리 로직
** 추가 제안 반영
*** Incremental Processing
#+begin_src python
def update_graph_incremental(changed_files):
"""전체 재구성 대신 변경분만 업데이트"""
pass
#+end_src
*** Denote 특화 기능 강화
- =#+filetags:= 파싱 정확도
- 날짜 범위 검색 (=202510*= 패턴)
- Backlinks (양방향 추적)
*** Org-babel 호환성
- =:results silent/output/value= 처리
- =:tangle= 경로 해석
*** 테스트 데이터셋
#+begin_example
tests/
├── small/ # 10개 파일 (빠른 테스트)
├── medium/ # 100개 파일 (기능 테스트)
└── large/ # 1000+ 파일 (성능 테스트)
#+end_example
*** 성능 모니터링
#+begin_src python
import time
from functools import wraps
def measure_performance(func):
@wraps(func)
def wrapper(*args, **kwargs):
start = time.time()
result = func(*args, **kwargs)
duration = time.time() - start
if duration > 1.0:
logger.warning(f"{func.__name__} took {duration:.2f}s")
return result
return wrapper
#+end_src
** 피드백 종합 평가
#+begin_quote
**Opus 4.1의 평가:**
"이 프로젝트의 비전이 정말 좋네요!
'Life Sciences → Life Everything' 패러다임 확장은
Anthropic Skills의 본질을 잘 이해한 접근입니다."
#+end_quote
** 반영 계획
*** 즉시 반영 (Phase 1)
1. ✅ SKILL.md 구조 설계 (When/What/How/Pitfalls)
2. ✅ 경로 처리 표준화 (os.path.expanduser)
3. ✅ Edge cases 리스트 작성
*** 단기 반영 (Phase 2)
4. 캐싱 전략 (lru_cache)
5. 에러 복구 로직
6. 테스트 데이터셋
*** 중기 반영 (Phase 3)
7. 성능 모니터링
8. Incremental processing
9. Documentation 강화
---
**작성자:** @junghan0611
**최초 작성:** 2025-10-21T11:35:00+09:00
**최종 업데이트:** 2025-10-21T11:58:00+09:00
**피드백:** Claude Opus 4.1 (2025-10-21T11:58)
**상태:** 🟡 개발 중 (0.1 릴리즈 목표)

420
docs/20251022T120000--skills-에이전트-학습-실험__agent_learning_experiment.org Normal file
View File

@@ -0,0 +1,420 @@
#+title: Skills 에이전트 학습 실험
#+date: [2025-10-22 Tue 12:00]
#+filetags: :agent:learning:experiment:skills:
#+identifier: 20251022T120000
* Skills 에이전트 학습 실험
:PROPERTIES:
:CUSTOM_ID: skills-에이전트-학습-실험
:END:
** 🎯 실험 목적
:PROPERTIES:
:CUSTOM_ID: 실험-목적
:END:
**에이전트 학습**: Skills 없이 vs 있을 때 에이전트의 행동 차이 관찰
*** 핵심 가설
:PROPERTIES:
:CUSTOM_ID: 핵심-가설
:END:
#+begin_quote
Skills가 있으면 에이전트가 **명확하게 다르게 행동**한다.
차이가 명확하지 않으면 Skills가 불필요한 것이다.
#+end_quote
** 🧪 실험 설계
:PROPERTIES:
:CUSTOM_ID: 실험-설계
:END:
*** 실험 조건
:PROPERTIES:
:CUSTOM_ID: 실험-조건
:END:
| 조건 | 설명 |
|------|------|
| **모델** | Haiku (우선), Sonnet (비교) |
| **환경** | Claude Code CLI |
| **비교** | Skills 없이 vs Skills 활성화 |
| **테스트** | PDF, XLSX 작업 |
*** 왜 Haiku 우선인가?
:PROPERTIES:
:CUSTOM_ID: 왜-haiku-우선인가
:END:
- 부담 없이 여러 번 테스트 가능
- Haiku로 되면 = Skills가 강력한 것
- Haiku로 안되면 = 모델 능력 문제일 수 있음
** 📋 실험 1: PDF 처리
:PROPERTIES:
:CUSTOM_ID: 실험-1-pdf-처리
:END:
*** Step 1-A: Skills 없이 (Baseline)
:PROPERTIES:
:CUSTOM_ID: step-1-a-skills-없이-baseline
:END:
*에이전트가 수행할 작업*:
#+begin_src markdown
테스트 PDF 파일(test.pdf)에서:
1. 전체 텍스트 추출
2. 첫 번째 페이지만 분리
3. 두 개의 PDF 병합
결과를 보고하시오.
#+end_src
*관찰 포인트*:
- [ ] 에이전트가 어떤 도구를 사용하는가?
- [ ] Python 라이브러리를 직접 코딩하는가?
- [ ] 실행 가능한 코드를 생성하는가?
- [ ] 에러가 발생하는가?
*학습 일지*:
#+begin_example
모델: Haiku / Sonnet
날짜:
결과:
- 사용 도구:
- 성공/실패:
- 특이사항:
#+end_example
*** Step 1-B: PDF Skill 활성화
:PROPERTIES:
:CUSTOM_ID: step-1-b-pdf-skill-활성화
:END:
*Skill 설치*:
#+begin_src bash
# 방법 1: 마켓플레이스
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
# 방법 2: 로컬 (이미 있음)
# ~/repos/3rd/snthropics-skills/document-skills/pdf/
#+end_src
*에이전트가 수행할 작업* (동일):
#+begin_src markdown
PDF skill을 사용하여 test.pdf에서:
1. 전체 텍스트 추출
2. 첫 번째 페이지만 분리
3. 두 개의 PDF 병합
결과를 보고하시오.
#+end_src
*관찰 포인트*:
- [ ] 에이전트가 PDF skill을 인식하는가?
- [ ] scripts/ 폴더의 Python 스크립트를 사용하는가?
- [ ] Step 1-A와 다른 접근 방식인가?
- [ ] 더 빠르거나 안정적인가?
*학습 일지*:
#+begin_example
모델: Haiku / Sonnet
날짜:
결과:
- Skill 인식 여부:
- 사용한 스크립트:
- Step 1-A와의 차이:
- 성공/실패:
#+end_example
*** Step 1-C: 비교 분석
:PROPERTIES:
:CUSTOM_ID: step-1-c-비교-분석
:END:
| 기준 | Skills 없이 (1-A) | Skills 있을 때 (1-B) |
|------|-------------------|---------------------|
| 성공 여부 | | |
| 코드 품질 | | |
| 실행 시간 | | |
| 에러 처리 | | |
| 재현성 | | |
*결론*:
- Skills의 차이가 명확한가? [ ] 예 [ ] 아니오
- 이유:
** 📋 실험 2: XLSX 처리
:PROPERTIES:
:CUSTOM_ID: 실험-2-xlsx-처리
:END:
*** Step 2-A: Skills 없이 (Baseline)
:PROPERTIES:
:CUSTOM_ID: step-2-a-skills-없이-baseline
:END:
*에이전트가 수행할 작업*:
#+begin_src markdown
Excel 파일(test.xlsx)을 생성하시오:
1. 3개 컬럼 (이름, 나이, 점수)
2. 5개 행 데이터
3. 점수 평균 계산 (수식 사용)
4. 컬럼 헤더 볼드 처리
결과를 보고하시오.
#+end_src
*학습 일지*:
#+begin_example
모델: Haiku / Sonnet
날짜:
결과:
- 수식이 작동하는가?
- 포맷팅이 적용되는가?
- 생성 코드:
#+end_example
*** Step 2-B: XLSX Skill 활성화
:PROPERTIES:
:CUSTOM_ID: step-2-b-xlsx-skill-활성화
:END:
*에이전트가 수행할 작업* (동일):
#+begin_src markdown
XLSX skill을 사용하여 Excel 파일 생성:
1. 3개 컬럼 (이름, 나이, 점수)
2. 5개 행 데이터
3. 점수 평균 계산 (수식 사용)
4. 컬럼 헤더 볼드 처리
결과를 보고하시오.
#+end_src
*관찰 포인트*:
- [ ] recalc.py가 호출되는가?
- [ ] 수식 계산이 더 정확한가?
- [ ] LibreOffice 통합이 보이는가?
*학습 일지*:
#+begin_example
모델: Haiku / Sonnet
날짜:
결과:
- recalc.py 사용 여부:
- Step 2-A와의 차이:
#+end_example
*** Step 2-C: 비교 분석
:PROPERTIES:
:CUSTOM_ID: step-2-c-비교-분석
:END:
| 기준 | Skills 없이 (2-A) | Skills 있을 때 (2-B) |
|------|-------------------|---------------------|
| 파일 생성 | | |
| 수식 작동 | | |
| 포맷팅 | | |
| 코드 복잡도 | | |
*결론*:
- XLSX skill의 가치가 있는가? [ ] 예 [ ] 아니오
- recalc.py의 역할:
** 📋 실험 3: 복잡한 작업
:PROPERTIES:
:CUSTOM_ID: 실험-3-복잡한-작업
:END:
*** Step 3: PDF 폼 채우기 (고난도)
:PROPERTIES:
:CUSTOM_ID: step-3-pdf-폼-채우기-고난도
:END:
*에이전트가 수행할 작업*:
#+begin_src markdown
fillable PDF form(form.pdf)에 데이터를 채우시오:
- Name: "홍길동"
- Age: "30"
- Email: "hong@example.com"
결과를 보고하시오.
#+end_src
*Skills 없이 결과*:
#+begin_example
#+end_example
*Skills 있을 때 결과*:
#+begin_example
사용 스크립트:
- check_fillable_fields.py
- extract_form_field_info.py
- fill_fillable_fields.py
- check_bounding_boxes.py
#+end_example
*결론*:
- 이 작업은 Skills 없이 가능한가? [ ] 예 [ ] 아니오
- bounding box 계산이 필요한가? [ ] 예 [ ] 아니오
** 🔬 모델별 비교
:PROPERTIES:
:CUSTOM_ID: 모델별-비교
:END:
*** Haiku vs Sonnet
:PROPERTIES:
:CUSTOM_ID: haiku-vs-sonnet
:END:
| 작업 | Haiku (Skills 없이) | Haiku (Skills 있음) | Sonnet (Skills 없이) | Sonnet (Skills 있음) |
|------|---------------------|---------------------|---------------------|---------------------|
| PDF 텍스트 추출 | | | | |
| PDF 병합 | | | | |
| XLSX 생성 | | | | |
| PDF 폼 채우기 | | | | |
*인사이트*:
- Haiku로 Skills가 작동하는가?
- Sonnet과 차이가 얼마나 나는가?
- Skills가 모델 능력을 보완하는가?
** 🎓 claude-memory와의 차이
:PROPERTIES:
:CUSTOM_ID: claude-memory와의-차이
:END:
*** 실험 4: Denote 파일 찾기
:PROPERTIES:
:CUSTOM_ID: 실험-4-denote-파일-찾기
:END:
*에이전트가 수행할 작업*:
#+begin_src markdown
~/org/llmlog/ 에서 "skills" 태그가 있는 파일을 모두 찾으시오.
#+end_src
*현재 방식 (claude-memory + CLAUDE.md)*:
#+begin_example
결과:
- 사용 도구: Glob, Grep
- 소요 시간:
- 토큰 사용:
#+end_example
*만약 denote-org skill이 있다면*:
#+begin_example
예상:
- denote_finder.py --tags skills
- 캐싱된 결과
- 토큰 최적화?
#+end_example
*질문*:
- [ ] Glob/Grep으로 충분한가?
- [ ] denote_finder.py가 더 빠른가?
- [ ] 3,000+ 파일에서 차이가 나는가?
- [ ] 복잡한 알고리즘이 필요한가?
** 📊 최종 판단 프레임워크
:PROPERTIES:
:CUSTOM_ID: 최종-판단-프레임워크
:END:
*** Skills 필요성 체크리스트
:PROPERTIES:
:CUSTOM_ID: skills-필요성-체크리스트
:END:
*PDF/XLSX Skills 검증*:
- [ ] Skills 없이 vs 있을 때 **명확한 차이**가 있다
- [ ] 복잡한 알고리즘 (bounding box 수준)이 필요하다
- [ ] 외부 스크립트 실행이 필수적이다
- [ ] 단순 프롬프트로 불가능한 작업이다
- [ ] Haiku 모델에서도 작동한다
*org-mode-skills 검증*:
- [ ] Denote 파일 찾기가 복잡한 알고리즘인가?
- [ ] Glob/Grep으로 충분하지 않은가?
- [ ] 3,000+ 파일에서 성능 차이가 있는가?
- [ ] scripts 없이는 불가능한 작업인가?
- [ ] claude-memory와 레이어가 분리되는가?
*** 경계선 정의
:PROPERTIES:
:CUSTOM_ID: 경계선-정의
:END:
| 시스템 | 목적 | 내용 | 변경 빈도 | 예시 |
|--------|------|------|-----------|------|
| **claude-memory** | | | | |
| **Skills** | | | | |
*실험 후 채우기*
** 🎯 최종 결론
:PROPERTIES:
:CUSTOM_ID: 최종-결론
:END:
*** org-mode-skills 필요한가?
:PROPERTIES:
:CUSTOM_ID: org-mode-skills-필요한가
:END:
*판단*: [ ] 필요 [ ] 불필요 [ ] 부분적
*이유*:
*실험 결과 요약*:
1. PDF/XLSX Skills의 가치:
2. claude-memory와의 차이:
3. Denote 작업의 복잡도:
*다음 액션*:
- [ ] org-mode-skills 개발 진행
- [ ] CLAUDE.md에 Denote 섹션 추가로 충분
- [ ] 다른 접근 방법:
** 📝 실험 노트
:PROPERTIES:
:CUSTOM_ID: 실험-노트
:END:
*** 날짜:
:PROPERTIES:
:CUSTOM_ID: 날짜
:END:
*** 발견:
:PROPERTIES:
:CUSTOM_ID: 발견
:END:
*** 의문점:
:PROPERTIES:
:CUSTOM_ID: 의문점
:END:
*** 인사이트:
:PROPERTIES:
:CUSTOM_ID: 인사이트
:END:
--------------
*Created*: 2025-10-22T12:00
*Purpose*: 에이전트 학습 - Skills 효과 검증
*Method*: 실험 기반 비교 분석

85
docs/20251118T120000--claude-skills-등록-관리-가이드__skills_claude.org Normal file
View File

@@ -0,0 +1,85 @@
#+title: Claude Skills 등록·관리 간단 가이드
#+date: [2025-11-18 Tue 12:00]
#+filetags: :skills:claude:orgmode:
#+identifier: 20251118T120000
* Claude Skills 등록·관리 가이드 :WORKLOG:
이 문서는 Anthropic 공식 skills 세트와 개인 orgmode-skills 세트를
Claude Code에서 어떻게 등록·설치하는지 최소 절차만 정리한 메모입니다.
** 1. Anthropic 공식 skills (anthropic-agent-skills)
공식 예제/문서 스킬 리포:
- 로컬 경로: =/home/goqual/repos/3rd/skills=
- 핵심 파일: =.claude-plugin/marketplace.json=
- name: =anthropic-agent-skills=
- plugins:
- =document-skills=
- =example-skills=
Claude Code에서 마켓플레이스 등록:
#+begin_example
/plugin marketplace add anthropics/skills
#+end_example
그 다음 실제 스킬 번들 설치:
#+begin_example
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
#+end_example
- =document-skills@anthropic-agent-skills= → PDF/XLSX/DOCX/PPTX 문서 스킬 세트
- =example-skills@anthropic-agent-skills= → algorithmic-art, mcp-builder 등 예제 스킬 세트
** 2. 개인 orgmode-skills 마켓플레이스 (junghan-skills)
개인 Denote/Org + 문서 스킬 묶음:
- 리포: =/home/goqual/repos/gh/orgmode-skills=
- 스킬: 루트에 =SKILL.md= (name: =denote-org=)
- 마켓플레이스 메타데이터:
- =.claude-plugin/marketplace.json=
- name: =junghan-skills=
- plugins:
- =denote-org-pack=
- skills:
- =./= (denote-org)
- =../skills/document-skills/pdf=
- =../skills/document-skills/xlsx=
Claude Code에서 마켓플레이스 등록:
#+begin_example
/plugin marketplace add /home/goqual/repos/gh/orgmode-skills
#+end_example
개인 스킬 번들 설치:
#+begin_example
/plugin install denote-org-pack@junghan-skills
#+end_example
이 한 번으로 다음이 함께 활성화됨:
- =denote-org= : Denote/org-mode PKM 스킬
- =pdf= : Anthropic PDF 스킬
- =xlsx= : Anthropic XLSX 스킬
** 3. 세션 시작 시 최소 커맨드 요약
새 Claude Code 세션에서 org + 문서 스킬 세트를 쓰고 싶을 때:
1) 한 번만 해두면 되는 것 (이미 완료됨):
- =/plugin marketplace add anthropics/skills=
- =/plugin marketplace add /home/goqual/repos/gh/orgmode-skills=
2) 각 세션에서 실행할 것:
#+begin_example
/plugin install document-skills@anthropic-agent-skills ;; 공식 문서 스킬 세트
/plugin install denote-org-pack@junghan-skills ;; 개인 orgmode + PDF/XLSX 세트
#+end_example
이후 Denote/Org 관련 작업에서는 먼저 =denote-org= 스킬을 가정하고,
PDF/XLSX 편집·분석이 필요할 때는 =document-skills= 를 함께 활용하는 것을 기본 전략으로 합니다.

110
docs/20251118T121000--opencode에서-glg-skills-활용-가이드__skills_opencode.org Normal file
View File

@@ -0,0 +1,110 @@
#+title: OpenCode에서 glg-skills 활용 가이드
#+date: [2025-11-18 Tue 12:10]
#+filetags: :skills:glg:opencode:
#+identifier: 20251118T121000
* OpenCode에서 glg-skills 활용 가이드 :WORKLOG:
이 문서는 Claude-Code가 아닌 **OpenCode 환경**(현재 이 에이전트)에서
`glg-skills`(orgmode-skills)와 Anthropic document-skills를 어떻게 같이
활용할지에 대한 최소 지침입니다.
** 1. 리포 위치와 역할
- glg-skills (개인 스킬 세트)
- 경로: =/home/goqual/repos/gh/orgmode-skills=
- 핵심:
- 루트 =SKILL.md=: =denote-org= 스킬 정의
- =scripts/org_headings_toc.py=: org 헤딩 TOC 추출 스크립트
- =docs/20251118T120000--claude-skills-등록-관리-가이드__skills_claude.org=: Claude용 가이드
- Anthropic skills (document-skills 포함)
- 경로: =/home/goqual/repos/3rd/skills=
- 이 리포 안의 =document-skills/= 는 PDF/XLSX/DOCX/PPTX 작업 참고용
- OpenCode에서는 여기 스크립트/문서를 **직접 호출/참조**하는 방식으로 사용
OpenCode에서는 `/plugin` 시스템이 없으므로, 이 두 리포는
"스킬 레퍼런스 + 스크립트 모음" 으로 취급합니다.
** 2. OpenCode에서 org 헤딩 구조 활용
org 파일을 분석할 때, 에이전트에게 다음과 같이 요청합니다:
1. **헤딩 구조 먼저**
- =scripts/org_headings_toc.py= 를 사용해 TOC 생성
- 예시 (에이전트가 내부적으로 실행하는 bash):
#+begin_example
python /home/goqual/repos/gh/orgmode-skills/scripts/org_headings_toc.py \
/home/goqual/repos/gh/orgmode-skills/docs/20251021T113500--denote-org-skills-프로젝트-시작-배경-및-작업-로그__project_skills_denote_anthropic_worklog.org
#+end_example
- 출력 형식: =LEVEL<TAB>TITLE=
- 예: =1\tDenote-Org Skills 프로젝트 시작=, =2\t히스토리= ...
2. **히스토리/History 섹션 우선 확인**
- TOC 결과 중
- =* 히스토리=, =* HISTORY=, =* History=, =* 작업 로그=, =* Changelog= 등
- 버전/변화 기록 섹션을 먼저 열어 요약
3. **관심 섹션만 본문 읽기**
- TOC를 기반으로 실제로 필요한 헤딩만 OpenCode에서 `read` 도구로 읽게 함
- 전 파일 grep은 보조 수단으로만 사용
이 전략은 glg-skills의 =SKILL.md= 에 이미 문서화되어 있으며,
OpenCode에서는 이 문서를 **행동 기준**으로 삼습니다.
** 3. Silo 인식과 경로 규칙 (OpenCode 관점)
OpenCode에서 org 파일을 다룰 때, 아래 경로를 **Denote/org silo** 로 취급합니다:
- =~/org/**=
- =~/org/meta/**=
- =~/org/bib/**=
- =~/org/notes/**=
- =~/org/llmlog/**=
- =~/claude-memory/**=
- =~/repos/gh/*/docs/**=
- =~/repos/work/*/docs/**=
특히:
- =~/org/meta=: 메타 모델/설계
- =~/org/bib=: 참고문헌/레퍼런스
- =~/org/notes=: 장문의 생각/노트
- =~/org/llmlog=: LLM 대화 로그
- 리포의 =docs/=: 해당 코드/프로젝트에 직접 연결된 문서
OpenCode 에이전트에게 요청할 때,
"이 파일/문서는 glg-skills의 silo 규칙을 따라 해석해줘"라고 명시하면,
위 경로 규칙을 기준으로 지식베이스를 바라보도록 유도할 수 있습니다.
** 4. document-skills와의 연계 (OpenCode)
Anthropic document-skills는 Claude-Code용 skills지만,
OpenCode에서는 다음 방식으로 간접 활용할 수 있습니다:
- =/home/goqual/repos/3rd/skills/document-skills/pdf/SKILL.md=
- PDF 처리 절차/모범 사례 참고 (스크립트 이름, 워크플로)
- =/home/goqual/repos/3rd/skills/document-skills/xlsx/SKILL.md=
- Excel 공식/구조 보존 규칙 참고
필요하다면, 여기 나온 Python 스크립트 패턴을
별도 OpenCode 전용 스크립트로 이식해 glg-skills 안에 포함시키고,
SKILL.md에 그 사용법을 추가하는 식으로 점진적으로 통합합니다.
** 5. 요약: OpenCode용 glg-skills 사용 패턴
- **지식 레퍼런스**:
- glg-skills: Denote/org 구조, silo 개념, 헤딩/히스토리 우선 전략
- document-skills: PDF/XLSX 등 문서 작업 절차 참고
- **실행 도구**:
- =scripts/org_headings_toc.py=: org 헤딩 TOC 추출
- 향후 필요 시 PDF/XLSX용 보조 스크립트 추가 예정
- **요청 패턴 예시**:
- "이 org 문서를 glg-skills 기준으로 읽어줘: 먼저 헤딩 TOC, 그 다음 히스토리, 그 다음 관련 섹션만 자세히"
- "~/org/meta 와 ~/org/notes 도 glg-skills의 silo 규칙대로 참고해서 설계 의도를 함께 봐줘"
이 문서는 OpenCode 환경에서 glg-skills를 사용할 때의
"최소한의 기억 장치" 역할을 합니다.