refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,275 @@
|
||||
---
|
||||
id: wiki-2026-0508-be-detailed
|
||||
title: Be Detailed (Specificity Principle)
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [구체화, specificity, prompt detail, requirement specification, edge case enumeration]
|
||||
duplicate_of: none
|
||||
source_trust_level: B
|
||||
confidence_score: 0.85
|
||||
verification_status: applied
|
||||
tags: [communication, prompt-engineering, requirements, spec, detail, edge-case, anti-vague]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: communication / spec
|
||||
applicable_to: [Prompt Engineering, RFC, Spec Writing, Bug Reports]
|
||||
---
|
||||
|
||||
# Be Detailed (Specificity Principle)
|
||||
|
||||
## 📌 한 줄 통찰
|
||||
> **"매 devil 의 detail"**. 매 abstraction 의 hide X — 매 number, 매 context, 매 edge. 매 prompt engineering 의 single biggest lever — 매 vague "make it good" → 매 hallucination, 매 specific "max 50 words, 매 active voice" → 매 reliable.
|
||||
|
||||
## 📖 핵심
|
||||
|
||||
### 매 specificity tool
|
||||
|
||||
#### 1. Quantification
|
||||
- ❌ "매우 빠름"
|
||||
- ✅ "p99 < 100ms"
|
||||
- ❌ "큰 file"
|
||||
- ✅ "100MB 이상"
|
||||
|
||||
#### 2. Contextualization
|
||||
- ❌ "login button"
|
||||
- ✅ "centered modal with email + password + social OAuth (Google, Apple), max-width 400px"
|
||||
|
||||
#### 3. Edge case enumeration
|
||||
- 매 happy path 의 X.
|
||||
- 매 empty / null / overflow / unicode / negative / boundary.
|
||||
- 매 concurrent / partial failure / network split.
|
||||
|
||||
#### 4. Negative spec
|
||||
- "should NOT" 의 explicit.
|
||||
- 매 boundary 의 clarify.
|
||||
|
||||
#### 5. Acceptance criteria
|
||||
- 매 verifiable.
|
||||
- 매 Given-When-Then.
|
||||
|
||||
### 매 spec hierarchy
|
||||
|
||||
#### Vague → Specific
|
||||
1. "Make it user-friendly"
|
||||
2. "Reduce form fields"
|
||||
3. "Reduce checkout from 6 fields to 2 (email, payment)"
|
||||
4. "Reduce checkout from 6 fields to 2 (email, payment), keep address auto-fill via Stripe Address Element, A/B test 50/50 for 2 weeks"
|
||||
|
||||
→ 매 step 4 만 의 actionable.
|
||||
|
||||
### 매 prompt engineering 의 detail
|
||||
|
||||
#### 매 vague (bad)
|
||||
> "Write me a poem"
|
||||
|
||||
#### 매 specific (good)
|
||||
> "Write a 4-line haiku about autumn leaves.
|
||||
> Format: 5-7-5 syllables.
|
||||
> Tone: melancholic.
|
||||
> No rhyming required.
|
||||
> Output: poem only, no explanation."
|
||||
|
||||
→ 매 hallucination ↓, 매 reliability ↑.
|
||||
|
||||
### 매 RFC / spec format
|
||||
1. **Motivation**: 매 why.
|
||||
2. **Detailed design**: 매 how.
|
||||
3. **Drawbacks**: 매 cost.
|
||||
4. **Alternatives**: 매 other approaches.
|
||||
5. **Unresolved questions**: 매 known gap.
|
||||
6. **Future work**: 매 next.
|
||||
|
||||
### 매 bug report (specific)
|
||||
- 매 reproducer (minimum case).
|
||||
- 매 expected vs actual.
|
||||
- 매 environment (OS, browser, version).
|
||||
- 매 logs / stack trace.
|
||||
- 매 frequency (always / 50% / random).
|
||||
- 매 impact.
|
||||
|
||||
### 매 over-detail risk
|
||||
- 매 over-spec: 매 implementation 의 lock-in.
|
||||
- 매 micro-management: 매 creativity X.
|
||||
- 매 outdated detail: 매 maintenance.
|
||||
- 매 reader 의 cognitive overload.
|
||||
|
||||
→ 매 right level 의 abstraction.
|
||||
|
||||
### 매 progressive disclosure
|
||||
- 매 summary first.
|
||||
- 매 detail on demand.
|
||||
- 매 README → 매 ADR → 매 code.
|
||||
|
||||
## 💻 패턴
|
||||
|
||||
### Specific prompt template
|
||||
```
|
||||
ROLE: Senior backend engineer.
|
||||
TASK: Refactor function X.
|
||||
CONTEXT:
|
||||
- Current: throws on error.
|
||||
- Codebase: TypeScript, neverthrow library.
|
||||
|
||||
CONSTRAINTS:
|
||||
- Keep public signature unchanged.
|
||||
- Return Result<T, E>.
|
||||
- Add unit test for both branches.
|
||||
|
||||
OUTPUT FORMAT:
|
||||
- Code only, no explanation.
|
||||
- TypeScript with neverthrow.
|
||||
|
||||
EXAMPLE OUTPUT (for similar task):
|
||||
[paste example]
|
||||
|
||||
INPUT:
|
||||
[code]
|
||||
```
|
||||
|
||||
### Acceptance criteria (Given-When-Then)
|
||||
```gherkin
|
||||
Feature: Login
|
||||
Scenario: Valid credentials
|
||||
Given a registered user with email "user@example.com"
|
||||
And password "Pass123!"
|
||||
When they submit the login form
|
||||
Then they are redirected to /dashboard
|
||||
And a session cookie "sid" is set with HttpOnly and Secure flags
|
||||
|
||||
Scenario: Invalid password
|
||||
Given a registered user
|
||||
When they submit invalid password 5 times in 1 minute
|
||||
Then they are rate-limited for 15 minutes
|
||||
And a 429 status is returned
|
||||
```
|
||||
|
||||
### Bug report template
|
||||
```markdown
|
||||
## Reproducer
|
||||
1. Login as user@example.com
|
||||
2. Click "Export CSV" on /reports/123
|
||||
3. CSV downloads but contains BOM + wrong encoding
|
||||
|
||||
## Expected
|
||||
UTF-8 without BOM (matches docs).
|
||||
|
||||
## Actual
|
||||
UTF-16 with BOM. Excel opens it but Numbers crashes.
|
||||
|
||||
## Environment
|
||||
- macOS 15.2
|
||||
- Chrome 130.0.6723
|
||||
- App version 1.42.3 (commit abc123)
|
||||
|
||||
## Frequency
|
||||
100% — every export since deploy on 2026-05-08.
|
||||
|
||||
## Impact
|
||||
~200 users daily affected. Workaround: open in Excel.
|
||||
|
||||
## Logs
|
||||
[paste]
|
||||
```
|
||||
|
||||
### RFC template (short)
|
||||
```markdown
|
||||
# RFC-0042: Adopt Kafka for events
|
||||
|
||||
## Motivation
|
||||
3 services need async coordination. Sync HTTP causes cascade.
|
||||
|
||||
## Detailed design
|
||||
- Events: Avro schema.
|
||||
- Topic: domain.event_type.v{version}.
|
||||
- Retention: 7 days.
|
||||
- Consumer group per service.
|
||||
|
||||
## Drawbacks
|
||||
- Operational complexity (Kafka cluster).
|
||||
- Async debugging harder.
|
||||
|
||||
## Alternatives
|
||||
1. RabbitMQ — simpler, less throughput.
|
||||
2. SQS — vendor lock-in, less ordering.
|
||||
|
||||
## Unresolved
|
||||
- Schema registry choice.
|
||||
- DLQ strategy.
|
||||
|
||||
## Future
|
||||
- Stream processing (Flink).
|
||||
```
|
||||
|
||||
### Edge case checklist (function spec)
|
||||
```
|
||||
For function process(input):
|
||||
|
||||
Empty:
|
||||
[ ] input = null
|
||||
[ ] input = undefined
|
||||
[ ] input = ''
|
||||
[ ] input = []
|
||||
[ ] input = {}
|
||||
|
||||
Boundary:
|
||||
[ ] input.length = 0
|
||||
[ ] input.length = 1
|
||||
[ ] input.length = MAX_INT
|
||||
[ ] input.length = MAX_INT + 1
|
||||
|
||||
Type:
|
||||
[ ] input = number (expected string)
|
||||
[ ] input = string (expected number)
|
||||
[ ] input = function
|
||||
|
||||
Special:
|
||||
[ ] Unicode (emoji, RTL, combining)
|
||||
[ ] Negative numbers
|
||||
[ ] NaN, Infinity
|
||||
[ ] Concurrent calls
|
||||
[ ] Network failure mid-call
|
||||
```
|
||||
|
||||
## 🤔 결정 기준
|
||||
| 상황 | Detail level |
|
||||
|---|---|
|
||||
| Prompt to LLM | Maximum (constraint + example + format) |
|
||||
| Spec / RFC | High (motivation + design + alternatives) |
|
||||
| Bug report | High (repro + env + frequency) |
|
||||
| README | Medium (BLUF + 30s pitch) |
|
||||
| Slack message | Low (concise) |
|
||||
| Architecture diagram | Layered (C4) |
|
||||
|
||||
**기본값**: 매 audience + 매 task 의 calibrate. 매 vague 의 default 의 X.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Articulateness]]
|
||||
- 변형: [[Edge-Case-Enumeration]]
|
||||
- 응용: [[Prompt_Engineering|Prompt-Engineering]] · [[RFC]]
|
||||
- Adjacent: [[Progressive-Disclosure]] · [[ADR]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 LLM prompt. 매 spec 작성. 매 bug report. 매 design review.
|
||||
**언제 X**: 매 brainstorm (premature specificity). 매 creative explore.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **"매 user-friendly"** without metric: 매 unmeasurable.
|
||||
- **No edge case**: 매 production crash.
|
||||
- **Over-spec**: 매 implementation lock-in.
|
||||
- **No reproducer in bug**: 매 wasted reviewer time.
|
||||
- **No acceptance criteria**: 매 "done?" 의 ambiguous.
|
||||
- **No example in prompt**: 매 LLM 의 guess.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Pragmatic Programmer, RFC tradition, prompt engineering best practice).
|
||||
- 신뢰도 B.
|
||||
- Related: [[Articulateness]] · [[Prompt_Engineering|Prompt-Engineering]] · [[Spec-Writing]] · [[Edge-Case]].
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — specificity tool + prompt template + bug report + RFC + edge case checklist |
|
||||
Reference in New Issue
Block a user