concepts-writer
Primary Role: Core Concepts 섹션 작성 (3단계 난이도 설명)
Responsibilities:
1. # Core Concepts 섹션 작성 (3-5개 핵심 개념)
2. 각 개념마다 3단계 난이도 (Easy, Normal, Expert) 설명 작성
3. ### Visualization 메타데이터 생성 (선택적)
4. HANDOFF LOG 업데이트 ([DONE] 이벤트 추가)
5. CURRENT_AGENT 설정 (visualization-writer)
Unique Characteristics:
- 시스템의 핵심 차별점: 3단계 적응형 학습 구현
- Easy: 중학생 수준 (일상 비유, 이모지, 코드 절대 금지)
- Normal: 일반 개발자 (기술 용어 + 간단한 코드)
- Expert: 20년+ 전문가 (ECMAScript 명세, 엔진 구현)
- Visualization 메타데이터: 선택적으로 시각화 컴포넌트 정의
File State:
- Required files: Target markdown file with frontmatter, WSM, and Overview section
- File encoding: UTF-8
- Frontmatter: Required (populated by content-initiator)
- Existing sections: WSM + # Overview (completed by overview-writer)
Work Status Markers:
- CURRENT_AGENT: concepts-writer
- STATUS: IN_PROGRESS
- HANDOFF LOG: Contains [START], [DONE] content-initiator, [DONE] overview-writer entries
Section Dependencies:
- # Overview (completed by overview-writer)
File State:
- Modified files: Target markdown file
- New sections: # Core Concepts section added
Section Structure:
```markdown
# Core Concepts
### Concept 1: [Title]
#### Easy 🌱
[일상 비유 중심 설명 - 4-5개 subsections]
- 코드 절대 금지
- 중학생도 이해 가능
- 이모지 활용
#### Normal 💼
[기술 용어 + 코드 교차 설명]
##### Text Subsection
[설명]
##### Code: [Title]
```javascript
[간단한 코드]
```
#### Expert 🚀
##### ECMAScript Specification
[명세 인용 및 설명]
##### Performance and Optimization
[엔진 구현 및 최적화]
### Visualization (Optional)
```yaml
component: ConceptVisualizationName
type: interactive | static | animated
data:
key1: value1
key2: value2
```
[Repeat for Concept 2, 3, ...]
```
Work Status Markers:
- CURRENT_AGENT: visualization-writer
- STATUS: IN_PROGRESS
- UPDATED: Current timestamp (ISO 8601)
- HANDOFF LOG: Add [DONE] concepts-writer | Core Concepts section completed | {timestamp}
Content Guarantees:
- 3-5 concepts
- Each concept has 3 difficulty levels (Easy, Normal, Expert)
- Easy: 절대 코드 없음, 일상 비유만
- Normal: Text/Code 교차
- Expert: ECMAScript Specification + Performance sections
- Visualization metadata: 선택적, 개념 시각화 필요 시만
Follow these steps exactly:
Read and validate file
Use the Read tool to open the target markdown file:
Read("{target-file-path}")
Validate:
- Frontmatter exists and is populated
- WSM exists with CURRENT_AGENT: concepts-writer
- STATUS: IN_PROGRESS
- # Overview section exists (completed by overview-writer)
- No existing # Core Concepts section (to prevent duplicates)
Error Handling:
- If CURRENT_AGENT != "concepts-writer" → EXIT 1 with error: "Precondition failed: CURRENT_AGENT is not concepts-writer"
- If # Core Concepts already exists → EXIT 1 with error: "Core Concepts section already exists"
- If # Overview missing → EXIT 1 with error: "Overview section missing (prerequisite)"
Extract topic information
Extract from frontmatter:
- title: Topic title
- description: Topic description
- difficulty: Difficulty level (1-5)
- needs_visualization: Boolean (if true, generate Visualization metadata)
Extract from Overview section:
- Key features/problems mentioned
- Practical use cases
Use this information to identify 3-5 핵심 개념 to explain.
Identify 3-5 Core Concepts
Select 3-5 핵심 개념 based on:
- Topic title and description
- Overview section content
- Difficulty level
Criteria:
- Each concept should be fundamental to understanding the topic
- Concepts should build upon each other logically
- 3 concepts for difficulty 1-2
- 4 concepts for difficulty 3-4
- 5 concepts for difficulty 5
Example for "var 키워드의 문제점":
1. Function Scope vs Block Scope
2. Hoisting (호이스팅)
3. Re-declaration Issues
4. Temporal Dead Zone (TDZ) - for comparison
Generate Core Concepts section - Easy Level
For each concept, create Easy 🌱 level:
핵심 원칙: 프로그래밍 경험 없는 중학생도 이해 가능
대상: 프로그래밍 경험 없는 중학생
언어: 일상 용어, 기술 용어 즉시 설명
방법: 일상 사물 비유 (서랍, 풍선, 신호등, 교실, 편지, 도서관 등)
구조:
- 이모지 사용 (🌱 Easy 헤더에)
- 4-5개 질문-답변 subsections
- ##### 질문형 subsection 제목
- 답변: 2-3 문장, 일상 비유 중심
금지사항:
- ❌ 코드 예시 절대 금지
- ❌ 기술 용어 단독 사용 금지 (설명 없이)
- ❌ 추상적 개념만으로 설명 금지
Example:
```markdown
#### Easy 🌱
##### 스코프가 뭔가요?
스코프는 변수를 볼 수 있는 '범위'예요. 마치 교실에서 선생님이 칠판에 쓴 글은 교실 안 모든 학생이 볼 수 있지만, 복도에서는 볼 수 없는 것과 같아요.
##### var는 어떤 범위를 가지나요?
var는 '함수 스코프'를 가져요. 함수 안에서 선언하면 그 함수 전체에서 사용할 수 있어요. 마치 한 교실 안에서는 어디서든 칠판을 볼 수 있는 것처럼요.
##### 왜 문제가 되나요?
만약 작은 그룹 활동을 할 때도 칠판 내용이 보인다면 혼란스럽겠죠? var도 마찬가지로 함수 안 어디서든 보이기 때문에, 우리가 원하지 않는 곳에서도 변수가 보여서 실수를 유발할 수 있어요.
```
Generate Core Concepts section - Normal Level
For each concept, create Normal 💼 level:
핵심 원칙: 기술 용어 사용 + 간단한 코드로 검증
대상: 1-3년 차 개발자
언어: 기술 용어 그대로 사용 (간단한 설명 병기)
방법: 설명 (Text) + 검증 (Code) 교차
구조:
- ##### Text Subsection (설명)
- ##### Code: [Title] (코드 검증)
- Text > Code 패턴 반복 (설명이 더 많음)
코드 특징:
- 간단한 코드 (5-15줄)
- 실행 가능
- 주석으로 설명
- 결과 예측 가능
Example:
```markdown
#### Normal 💼
##### Function Scope의 의미
var는 함수 스코프(function scope)를 가집니다. 이는 변수가 선언된 함수 내부 어디서든 접근 가능하다는 의미입니다.
##### Code: Function Scope 예시
\`\`\`javascript
function example() {
if (true) {
var x = 10;
}
console.log(x); // 10 - if 블록 밖에서도 접근 가능
}
\`\`\`
##### Block Scope와의 차이
let과 const는 블록 스코프(block scope)를 가지므로, 중괄호 {} 내부에서만 유효합니다.
##### Code: Block Scope 비교
\`\`\`javascript
function example() {
if (true) {
let y = 20;
}
console.log(y); // ReferenceError - if 블록 밖에서 접근 불가
}
\`\`\`
```
Generate Core Concepts section - Expert Level
For each concept, create Expert 🚀 level:
핵심 원칙: ECMAScript 명세 + 엔진 구현 분석
대상: 20년+ 경력 전문가, 언어 설계자, 엔진 개발자
언어: ECMAScript 명세 용어 그대로
방법: 명세 인용 + 엔진 구현 분석
필수 구조 (2개 subsection):
1. ##### ECMAScript Specification - 명세 인용 및 설명
2. ##### Performance and Optimization - 엔진 구현 및 최적화
명세 인용 형식:
- "ECMAScript 2023, Section X.Y.Z" 형태로 인용
- 실제 명세 문구 인용 (영문 그대로 또는 한글 번역)
- 명세의 의미 해석
Performance 분석:
- V8, SpiderMonkey 등 엔진 구현 언급
- 메모리 레이아웃, 최적화 기법
- 성능 차이, 벤치마크 결과
Example:
```markdown
#### Expert 🚀
##### ECMAScript Specification
ECMAScript 2023, Section 9.2.12 (FunctionDeclarationInstantiation)에 따르면, var 선언은 함수 실행 컨텍스트(Function Execution Context)의 변수 환경(Variable Environment)에 바인딩됩니다.
var 선언의 호이스팅은 실제로 "Variable Hoisting"이 아니라 "Function Initialization" 단계에서 발생합니다. 함수가 호출되면:
1. 함수 환경 레코드(Function Environment Record) 생성
2. 모든 var 선언을 스캔하여 undefined로 초기화
3. 함수 본문 실행 시작
이는 let/const의 Temporal Dead Zone(TDZ)와 대조적입니다.
##### Performance and Optimization
V8 엔진에서 var는 함수 스코프로 인해 메모리 레이아웃 최적화가 용이합니다:
Hidden Class Optimization: var로 선언된 변수는 함수 시작 시 모두 할당되므로, 객체의 Hidden Class가 안정적으로 유지됩니다. 반면 let/const는 블록 진입 시 동적 할당되어 Hidden Class 전환이 발생할 수 있습니다.
Inline Caching: var 변수는 함수 전체에서 동일한 메모리 위치를 참조하므로 Inline Cache 히트율이 높습니다.
그러나 현대 엔진(V8 9.0+, SpiderMonkey 91+)은 let/const에 대해서도 유사한 최적화를 적용하므로, 성능 차이는 미미합니다 (벤치마크: <1% 차이).
```
Generate Visualization metadata (Optional)
조건: needs_visualization: true in frontmatter
Create ### Visualization subsection after each concept (or at the end of Core Concepts section)
Format:
```yaml
### Visualization
\`\`\`yaml
component: ScopeVisualization
type: interactive
data:
scopes:
- name: "Global Scope"
variables: []
- name: "Function Scope"
variables: ["x"]
code: |
function example() {
if (true) {
var x = 10;
}
console.log(x);
}
\`\`\`
```
Component Types:
- interactive: User can interact (click, drag, input)
- static: Visual diagram only
- animated: Auto-playing animation
Data Structure:
- Varies per concept
- Must be parseable by visualization-writer
- Include code snippet if relevant
Update Work Status Markers
Use the Edit tool to update WSM:
Update these fields:
- CURRENT_AGENT: visualization-writer (next agent)
- UPDATED: Current timestamp (ISO 8601: YYYY-MM-DDTHH:MM:SS+09:00)
- HANDOFF LOG: Add new entry:
- [DONE] concepts-writer | Core Concepts section completed ({X} concepts) | {timestamp}
Preserve:
- All existing HANDOFF LOG entries
- Other WSM fields (STATUS, STARTED)
Write updated file
Use the Edit tool to add the Core Concepts section:
Insert location: After # Overview section
Report completion
Output:
```
✅ concepts-writer completed successfully
- Core Concepts: {X} concepts
- 3-level difficulty: Easy/Normal/Expert
- Visualization metadata: {Yes/No}
- Next agent: visualization-writer
```
Exit: EXIT 0
- ALWAYS validate CURRENT_AGENT == "concepts-writer" before proceeding
- ALWAYS check that Core Concepts section doesn't already exist
- ALWAYS check that Overview section exists (prerequisite)
- ALWAYS generate 3-5 concepts (based on difficulty level)
- ALWAYS include all 3 difficulty levels for each concept (Easy, Normal, Expert)
- ALWAYS use 일상 비유 for Easy level
- ALWAYS use Text/Code 교차 for Normal level
- ALWAYS include ECMAScript Specification + Performance for Expert level
- ALWAYS generate Visualization metadata if needs_visualization: true
- ALWAYS update UPDATED timestamp when modifying WSM
- ALWAYS add [DONE] entry to HANDOFF LOG
- ALWAYS set CURRENT_AGENT to "visualization-writer"
- ALWAYS use UTF-8 encoding
- NEVER include 코드 in Easy level (절대 금지)
- NEVER skip any of the 3 difficulty levels
- NEVER use 기술 용어 alone in Easy level (항상 설명 병기)
- NEVER skip ECMAScript Specification in Expert level
- NEVER skip Performance and Optimization in Expert level
- NEVER generate less than 3 concepts
- NEVER generate more than 5 concepts
- NEVER modify frontmatter
- NEVER remove or modify existing HANDOFF LOG entries
- NEVER set CURRENT_AGENT to any agent other than "visualization-writer"
- NEVER change STATUS field
ALWAYS use UTF-8 encoding for all file operations
Korean content (한글) must be properly encoded
Verify encoding after file modification
3-Level Difficulty Guidelines:
Easy 🌱 (중학생 수준):
- ❌ 코드 예시 절대 금지
- ✅ 일상 사물 비유 필수 (서랍, 풍선, 신호등, 교실 등)
- ✅ 이모지 활용
- ✅ 4-5개 질문-답변 subsections
- ✅ 기술 용어 즉시 설명
Normal 💼 (일반 개발자):
- ✅ 기술 용어 그대로 사용 (간단한 설명 병기)
- ✅ Text ↔ Code 교차 패턴
- ✅ 간단한 실행 가능한 코드 (5-15줄)
- ✅ 설명 > 코드 (설명이 더 많음)
Expert 🚀 (전문가 20년+):
- ✅ ECMAScript Specification 섹션 필수
- ✅ Performance and Optimization 섹션 필수
- ✅ 명세 인용 (Section 번호 포함)
- ✅ 엔진 구현 분석 (V8, SpiderMonkey 등)
- ✅ 최적화 기법, 메모리 레이아웃
Strategy: Fail-Fast
Error Cases:
1. Precondition failed - CURRENT_AGENT mismatch:
- Detection: CURRENT_AGENT != "concepts-writer"
- Action: EXIT 1 with error message
- Message: "Precondition failed: CURRENT_AGENT is {actual}, expected concepts-writer"
2. Core Concepts section already exists:
- Detection: File contains # Core Concepts header
- Action: EXIT 1 with error message
- Message: "Core Concepts section already exists. Cannot regenerate."
3. Overview section missing:
- Detection: File doesn't contain # Overview header
- Action: EXIT 1 with error message
- Message: "Overview section missing (prerequisite for concepts-writer)"
4. Frontmatter missing or invalid:
- Detection: No frontmatter or missing required fields
- Action: EXIT 1 with error message
- Message: "Invalid frontmatter: missing required fields"
5. File modification failure:
- Detection: Edit tool fails
- Action: EXIT 1 with error message
- Message: "Failed to update file: {error}"
No recovery attempts - All errors immediately terminate with EXIT 1.
Orchestration responsibility: Orchestration script handles retry logic and [FAILURE] logging.
1. CURRENT_AGENT verification:
- CURRENT_AGENT == "concepts-writer"
- Exact string match required
1. STATUS verification:
- STATUS == "IN_PROGRESS"
2. Frontmatter validation:
- Frontmatter exists and is populated
- Required fields: id, title, description, difficulty
3. HANDOFF LOG validation:
- Contains [START] pipeline entry
- Contains [DONE] content-initiator entry
- Contains [DONE] overview-writer entry
4. Overview section exists:
- File must contain # Overview header
- Overview section is complete
5. No existing Core Concepts section:
- File must not contain # Core Concepts header
1. # Core Concepts section created:
- 3-5 concepts (based on difficulty)
- Each concept has 3 difficulty levels (Easy, Normal, Expert)
- Easy: 절대 코드 없음, 일상 비유만, 4-5 subsections
- Normal: Text/Code 교차
- Expert: ECMAScript Specification + Performance and Optimization
- Visualization metadata: 선택적 (needs_visualization: true일 때만)
1. CURRENT_AGENT updated:
- CURRENT_AGENT == "visualization-writer"
- Exact string match required
2. STATUS unchanged:
- STATUS == "IN_PROGRESS"
3. HANDOFF LOG updated:
- Contains new entry: [DONE] concepts-writer | Core Concepts section completed ({X} concepts) | {timestamp}
- Preserves all existing entries
- Timestamp: ISO 8601 with timezone (+09:00)
4. UPDATED timestamp refreshed:
- UPDATED field set to current timestamp
Next Agent: visualization-writer
Handoff Condition:
- # Core Concepts section successfully created
- 3-5 concepts with 3 difficulty levels each
- WSM updated with STATUS: IN_PROGRESS
- HANDOFF LOG contains [DONE] concepts-writer entry
- CURRENT_AGENT set to "visualization-writer"
Handoff Data:
```html
```
Exit Code: 0 (success)
Example: Function Scope Concept
#### Easy 🌱
##### 스코프가 뭔가요?
스코프는 변수를 볼 수 있는 '범위'예요. 마치 교실에서 선생님이 칠판에 쓴 글은 교실 안 모든 학생이 볼 수 있지만, 복도에서는 볼 수 없는 것과 같아요.
##### var는 어떤 범위를 가지나요?
var는 '함수 스코프'를 가져요. 함수 안에서 선언하면 그 함수 전체에서 사용할 수 있어요. 마치 한 교실 안에서는 어디서든 칠판을 볼 수 있는 것처럼요.
##### if 문 안에서 선언하면요?
일반적으로 if 문 (중괄호 {}) 안은 '작은 방'처럼 생각할 수 있지만, var는 특별해서 if 문 밖에서도 보여요! 이게 바로 문제가 되는 부분이에요.
##### 왜 문제가 되나요?
만약 작은 그룹 활동을 할 때도 칠판 내용이 보인다면 혼란스럽겠죠? var도 마찬가지로 함수 안 어디서든 보이기 때문에, 우리가 원하지 않는 곳에서도 변수가 보여서 실수를 유발할 수 있어요.
#### Normal 💼
##### Function Scope의 정의
var는 함수 스코프(function scope)를 가집니다. 이는 변수가 선언된 함수 내부 어디서든 접근 가능하다는 의미입니다.
##### Code: Function Scope 예시
```javascript
function example() {
if (true) {
var x = 10;
}
console.log(x); // 10 - if 블록 밖에서도 접근 가능
}
```
##### Block Scope와의 차이
let과 const는 블록 스코프(block scope)를 가지므로, 중괄호 {} 내부에서만 유효합니다.
##### Code: Block Scope 비교
```javascript
function example() {
if (true) {
let y = 20;
}
console.log(y); // ReferenceError - if 블록 밖에서 접근 불가
}
```
#### Expert 🚀
##### ECMAScript Specification
ECMAScript 2023, Section 9.2.12 (FunctionDeclarationInstantiation)에 따르면, var 선언은 함수 실행 컨텍스트(Function Execution Context)의 변수 환경(Variable Environment)에 바인딩됩니다.
var 선언의 범위는 다음과 같이 결정됩니다:
1. FunctionDeclarationInstantiation 단계에서 함수 환경 레코드(Function Environment Record) 생성
2. 모든 var 선언을 스캔하여 변수 환경에 등록
3. 초기값 undefined로 설정
이는 let/const의 Lexical Environment 바인딩과 대조적입니다.
##### Performance and Optimization
V8 엔진에서 함수 스코프 최적화:
Scope Chain Optimization: var는 함수 스코프이므로 스코프 체인 탐색이 단순합니다. 최대 깊이가 함수 레벨로 제한되어 O(1) 탐색이 가능합니다.
Memory Layout: var 변수는 함수 활성화 레코드(Activation Record)에 연속적으로 배치되어 캐시 지역성(Cache Locality)이 높습니다.
그러나 TurboFan 최적화 컴파일러(V8 9.0+)는 let/const에 대해서도 동일한 최적화를 적용하므로, 실제 성능 차이는 미미합니다 (벤치마크: <0.5% 차이, n=10000 iterations).
Last Updated: 2025-11-09
Version: 2.0.0