feat: 공식 문서 근거자료, 브랜치 기능 문서 작성
This commit is contained in:
DongHyeonka
@@ -0,0 +1,91 @@
|
||||
# Contract 7 — Forbidden Marketing Words + External Evidence (+ Concept Organization Mode)
|
||||
|
||||
Root SSOT: [`rules/advisory-depth.md`](../../../../../rules/advisory-depth.md) §"Contract 7" + §"Concept Organization Mode"
|
||||
parent: [`README.md`](README.md)
|
||||
|
||||
## Contract 7 — Forbidden Marketing Words & External Evidence
|
||||
|
||||
Past failure: the agent's findings are mostly grounded, but the prose layered on top inflates them. Words like `"100%"`, `"완벽"`, `"극한"`, `"역사상 가장"` add no engineering meaning and signal that the agent is generating marketing copy on top of real analysis. Separately, claims of "well-known anti-pattern" or "industry standard practice" without an external citation are unverifiable appeals to authority.
|
||||
|
||||
This contract bans marketing inflation and forces external citations for industry-norm claims.
|
||||
|
||||
### Banned phrases in advisory text
|
||||
|
||||
The following words and phrases are forbidden in §1 Executive Summary, §4 Per-File Findings, §5 Priority Recommendations, and Direct-Response answers. They are allowed only inside a verbatim quote (in which case they are accurately citing what the source actually said).
|
||||
|
||||
**Marketing inflation:**
|
||||
|
||||
- `100%`, `100점`, `0%` (as a perfection claim — `0 errors observed` is OK, `0%까지 완벽 보장` is not)
|
||||
- `완벽`, `완벽히`, `완벽한`, `완벽무결`, `완전무결`
|
||||
- `극한`, `극도`, `극단적`, `극심하게`, `극대화`
|
||||
- `절대`, `절대적`, `절대로` (when used as universal quantifiers — `절대로 일어나서는 안 된다` is OK as a normative statement, `절대로 일어나지 않는다` as a factual claim is not)
|
||||
- `최강`, `최고`, `최정상`
|
||||
- `역사상 가장`, `사상 최고`, `세계 최초`
|
||||
- `즉시`, `즉각` (when paired with hyperbolic claims like `즉시 다운`, `즉각 폭사`)
|
||||
- `폭사`, `사살`, `섬멸` (사용자 환경에 대한 비유적 과장)
|
||||
- `명품`, `초일류`, `엔터프라이즈급` (자기 평가)
|
||||
|
||||
**Banned authority-appeals without citation:**
|
||||
|
||||
- `well-known anti-pattern`, `standard practice`, `industry consensus`, `widely accepted`, `everybody knows`
|
||||
- `대기업에서는`, `현업에서는`, `실무에서는` — when used to authorize a claim without a specific source. (Acceptable when the agent's own experience/reasoning is what's offered, but then the claim is `INFERENCE`, not authority.)
|
||||
- `AWS/Google/Netflix가 이렇게 합니다` — without a specific public doc/talk URL or `CLAUDE.md` / `templates/<x>.md` cross-reference.
|
||||
|
||||
### Replacement guidance
|
||||
|
||||
| Banned | Replacement |
|
||||
|---|---|
|
||||
| `100% 무결한 멱등성 보장` | `중복 결제 케이스 N개 차단. 잔여 엣지 케이스: <list>` |
|
||||
| `완벽한 보안 격리` | `이 시나리오 하에서 격리됨. <Y> 시나리오는 별도 통제 필요` |
|
||||
| `극한으로 깎인 스켈레톤` | `현재 명세 기준 N개 결함 식별, M개는 자동 검증 가능` |
|
||||
| `즉시 폭사` | `<X초> 내에 응답 시간이 <Y배> 증가, 임계치 초과 시 알람` |
|
||||
| `well-known anti-pattern` | 외부 문서 URL 인용 + 한 문장 인용. 인용 불가 시 `INFERENCE` 라벨 |
|
||||
|
||||
### External evidence requirement
|
||||
|
||||
권고가 "이게 표준 / 업계 모범 / RFC / 공식 패턴이다" 라는 권위에 호소하면, 해당 권고는 다음 중 하나여야 한다.
|
||||
|
||||
1. **외부 문서 인용**: RFC, AWS/GCP/Azure 공식 문서, 공식 프레임워크 reference docs (Spring, Django, Rails 등), OWASP, 또는 명확한 저자가 있는 기술 블로그를 인용. URL 또는 문서 명칭 (`RFC 8594`, `Spring Boot reference docs §6.4`, `OWASP Top 10 A03` 등) 명시. 본 wiki 의 `raw/official-docs/` 또는 `raw/company-tech-blogs/` 에 이미 발췌·보존된 자료라면 해당 raw 파일 wikilink + 원문 URL 동시 명시.
|
||||
2. **LLM Wiki CLAUDE.md / templates/* / 기존 wiki 문서 인용**: 본 저장소가 자체적으로 채택한 결정 또는 정책이라면 그 결정 라인을 verbatim quote 로 인용 (예: `CLAUDE.md §15 파이프라인 강제`, `templates/linking-rules.md §2 Mandatory Upward Link 표`).
|
||||
3. **INFERENCE 라벨**: 외부 근거가 없다면 권고를 `INFERENCE` 로 라벨링하고, "제가 reasoning 한 결과" 라고 명시. 자기 추론은 합법적이지만 권위 호소로 위장하면 안 된다.
|
||||
|
||||
### Pre-send check (Contract 7)
|
||||
|
||||
송신 직전 다음 점검. 위반 1건이라도 발견되면 draft `BLOCKED` 및 재작성.
|
||||
|
||||
1. 금지 단어 grep: `egrep -oh '(100%|완벽|극한|극도|절대로|최강|역사상)' <draft.md>` 결과 비어 있음? (verbatim quote 내부 등장만 허용)
|
||||
2. `well-known/standard practice/industry consensus/대기업에서는/현업에서는` 등의 표현 등장한 곳마다 외부 문서 URL 또는 명세 인용 동반?
|
||||
3. 권위 호소 + 인용 없음 → 해당 finding `INFERENCE` 라벨링?
|
||||
|
||||
## Concept Organization Mode
|
||||
|
||||
When the user asks for a concept explanation, terminology clarification, or "교통 정리" of an area they have not thought through, the agent uses this expansion of the direct-response template:
|
||||
|
||||
```markdown
|
||||
## 1. 개념 정의 / Concept definition
|
||||
- <짧고 정확한 정의>
|
||||
- 흔한 오해 / Common confusions: ...
|
||||
|
||||
## 2. 구성 요소 / Components
|
||||
- <subcomponents or related sub-concepts, each defined once>
|
||||
|
||||
## 3. 적용 / Where it applies
|
||||
- <real situations where the concept matters in this project>
|
||||
|
||||
## 4. 대안 / Alternatives and adjacent concepts
|
||||
- <other ways to model the same problem, with one-line trade-offs>
|
||||
|
||||
## 5. 이 wiki / 프로젝트에서의 적용 / How it applies here
|
||||
- <link to CLAUDE.md / templates/<x>.md / 기존 wiki/concepts/<...>.md / 관련 raw/branch-notes 등 본 개념이 이미 등장하는 파일>
|
||||
- <gaps in the current setup, if any>
|
||||
|
||||
## 6. 추천 학습 순서 / Suggested order to internalize
|
||||
- <if the concept is layered, give the order to study its parts>
|
||||
```
|
||||
|
||||
## Antigravity-specific 메모
|
||||
|
||||
- Hook G2 가 `docs/superpowers/specs/*.md` write 시 자동 enforce — 금지어 ("100%", "완벽", "극한", "절대로", "최강", "역사상 가장", "명품") 가 verbatim quote / code fence / blockquote 밖에 있으면 deny.
|
||||
- **단 hook 은 7개 핵심 금지어만 검사**. `극도`, `극단적`, `극심하게`, `극대화`, `즉시`, `즉각`, `폭사`, `사살`, `섬멸`, `초일류`, `엔터프라이즈급`, `완벽무결`, `완전무결`, `절대`, `절대적`, `최고`, `최정상`, `사상 최고`, `세계 최초`, `well-known`, `standard practice`, `industry consensus`, `widely accepted`, `대기업에서는`, `현업에서는`, `실무에서는` 등은 hook 미커버 — agent self-check 단독.
|
||||
- chat 본문 응답 / `raw/` · `wiki/` 등 다른 경로 write 도 hook 미커버.
|
||||
- External evidence 요구 (INFERENCE 라벨링) 는 hook 미커버 — 권위 호소 + 인용 없음 자동 BLOCKED 정책은 agent self-check 단독.
|
||||
Reference in New Issue
Block a user