Files

T

Antigravity Agent 93ec7e9056 [G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00

8.3 KiB

Raw Blame History

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

title

Documentation

코드 자체로 충분 X. README, ADR (architectural decisions), runbook, API docs, onboarding. Doc as code (markdown in git). Diataxis framework.

📖 핵심 개념

README: 프로젝트의 입구.
ADR: 결정의 기록 (왜 X 가 아닌 Y 선택).
Runbook: incident / migration 의 step.
Diataxis: 4 categories — tutorial / how-to / reference / explanation.

💻 코드 패턴

README template

# Project Name

Short description (1-2 sentences).

## Status
🚧 Active development | ⚠️ Maintenance only | ⛔ Deprecated

## Quickstart
```bash
git clone ...
cd project
yarn install
yarn dev

Setup

Node 20+
Postgres 16+
Redis 7+
Env vars in .env.example

Development

yarn dev          # local dev server
yarn test         # tests
yarn build        # production build
yarn lint         # lint
yarn typecheck    # tsc

Deploy

See DEPLOY.md

Architecture

[Brief overview, link to ADRs]

Contributing

See CONTRIBUTING.md

License

MIT


### ADR (Architecture Decision Record)
```markdown
# 0001. Use Postgres for primary database

Date: 2026-05-09
Status: Accepted
Authors: @alice, @bob

## Context
We need a primary database for user / order / inventory data.

Requirements:
- ACID transactions
- Strong relational queries
- Mature ecosystem
- Cloud-managed option

## Options considered
1. **Postgres** — mature, strong SQL, JSON support
2. **MySQL** — popular, simpler
3. **MongoDB** — flexible schema
4. **DynamoDB** — managed, scales

## Decision
**Postgres** because:
- Best-in-class SQL features (CTE, window, JSONB)
- Free + open
- Great cloud options (RDS, Aurora, Supabase, Neon)
- Team familiar

## Consequences
- ✅ Strong analytics queries
- ✅ JSONB for flexible data
- ⚠️ Need to manage scaling (PgBouncer for connections)
- ⚠️ Manual sharding 필요 시 — Citus / 자체

## References
- https://www.postgresql.org/

→ Numbered + immutable. 새 결정 = 새 ADR + supersede 옛.

ADR storage

docs/
├── adr/
│   ├── 0001-use-postgres.md
│   ├── 0002-use-react-typescript.md
│   ├── 0003-monorepo-with-turborepo.md
│   └── README.md           # 목록

adr-tools (자동화)

adr-new "Use Redis for cache"
# → 0004-use-redis-for-cache.md (template)

adr-link 4 supersedes 1
# → 0001 가 superseded by 0004

Diataxis framework

4 종류 documentation:

1. Tutorial (학습): "Get started with X"
   - Step-by-step, guided
   - 새 사용자
   - 작은 win
   
2. How-to (작업): "How to do X"
   - Recipe / cookbook
   - 알 사용자
   - 빠른 reference
   
3. Reference (정보): API spec, config options
   - 정확 / 완전
   - 알파벳 정렬
   
4. Explanation (이해): "Why does X work this way"
   - Concept, history
   - 깊이 학습

→ 한 문서 가 한 종류. 섞으면 헷갈림.

docs/ 구조

docs/
├── README.md              # 입구
├── tutorials/
│   └── getting-started.md
├── how-to/
│   ├── deploy.md
│   ├── add-feature-flag.md
│   └── debug-slow-query.md
├── reference/
│   ├── api.md
│   └── config.md
├── explanation/
│   ├── architecture.md
│   └── why-postgres.md
├── adr/
└── runbooks/
    ├── api-down.md
    └── db-failover.md

API docs (자동)

// OpenAPI spec → 자동 docs
// Scalar / Stoplight / Redoc / Swagger UI

// 또는 TypeDoc
yarn typedoc src/index.ts

Code comment 가이드

// ❌ "i 를 increment"
i++;  // 의미 없음

// ❌ "Set name to user.name"
this.name = user.name;

// ✅ "왜" 가 명확하지 않을 때
// User.deletedAt 가 null 이라도 admin 가 soft-delete 했을 수 있음
const isActive = user.deletedAt === null && user.adminBan === null;

// ✅ Tricky math / algorithm
// Boyer-Moore voting algorithm — O(N) majority element

JSDoc / TSDoc

/**
 * Calculates the order total including tax and shipping.
 *
 * @param items - Order line items
 * @param region - Shipping region for tax calculation
 * @returns Total in USD with 2 decimal precision
 * @throws {InvalidRegionError} When region not supported
 *
 * @example
 * ```ts
 * const total = calculateTotal(items, 'US-CA');
 * // 99.99
 * ```
 */
function calculateTotal(items: Item[], region: Region): number {
  // ...
}

Changelog (KEEPACHANGELOG)

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- Cursor pagination for /orders endpoint

## [1.5.0] - 2026-05-01

### Added
- New checkout flow (#123)

### Fixed
- Login race condition (#456)

### Changed
- Updated React to 19

### Deprecated
- /v1/users — use /v2/users

### Removed
- ...

### Security
- Updated dependencies

→ semantic-release 가 자동 생성 가능.

CONTRIBUTING.md

# Contributing

## Setup
[link to README setup section]

## Workflow
1. Fork & clone
2. Create branch: `feat/your-feature`
3. Commit (conventional commits)
4. Push & open PR
5. Address review feedback
6. Squash merge

## Code style
- Run `yarn lint` and `yarn format` before push
- Husky pre-commit hooks enforce this

## Tests
- Unit tests required for new logic
- Run `yarn test` locally

## Reporting bugs
- GitHub Issues with reproduction

Onboarding doc

# Engineering Onboarding

Welcome! This is for your first 2 weeks.

## Day 1
- [ ] Setup laptop
- [ ] Access: GitHub, Slack, AWS, Linear, etc.
- [ ] Read this doc
- [ ] Read [ARCHITECTURE.md](./ARCHITECTURE.md)
- [ ] Get coffee ☕

## Week 1
- [ ] Run app locally
- [ ] First small PR (typo / docs fix)
- [ ] Pair with engineer on a feature
- [ ] Read recent ADRs

## Week 2
- [ ] Take a small task from backlog
- [ ] Shadow oncall
- [ ] Attend retro

## Resources
- [Slack channels](#)
- [Wiki](#)
- [Tooling](#)

Docs review

Code review = code 만 X.
Documentation review = docs 도.

PR template:
- [ ] Docs updated (README, API docs, ADR if applicable)

Stale docs detection

# Last modified date
find docs -name '*.md' -mtime +180

# 또는 docs lint
markdown-lint docs/
vale docs/        # style guide

→ 6 months+ 안 변경 = 검토.

Docs-as-code

- Markdown in git
- Same review process as code
- Version controlled
- Linked from code

→ Notion / Confluence 보다 좋음 (drift 적음).

MkDocs / Docusaurus / Nextra (host)

# MkDocs
mkdocs new docs
mkdocs serve

# Docusaurus
npx create-docusaurus@latest

# Nextra (Next.js 친화)

→ docs/ → website 자동.

Comments vs docs

Comment: "왜 이 줄"
Docs: "왜 이 system / flow"

코드 안 = 작은 why
Docs = 큰 why + how

Living docs

README 의 "How to deploy" = step
실제 deploy = 같은 step

→ 다르면 docs 업데이트.
"Code 가 truth" 가 아닌 "Code + docs 가 truth".

Internal vs public

Internal: 자세한 — implementation, decision
Public: 사용자 — API, integration

다른 audience.

🤔 의사결정 기준

Doc 종류	추천
새 프로젝트	README + CONTRIBUTING
기술 결정	ADR
API	OpenAPI + Scalar
Runbook	Per service / per migration
학습	Tutorial
깊이 이해	Explanation
Reference	Auto-generated when 가능

❌ 안티패턴

Stale docs: code 와 다름 — worse than 없음.
모든 거 README: 큰 → 안 읽음. Split.
Comments 가 "what": code 가 보임.
No ADR: 결정 잊혀짐.
No onboarding: 새 사람 헛수고.
Notion + git docs 둘 다: drift.
Docs review 없음 (code 만): stale.

🤖 LLM 활용 힌트

README + ADR + runbook 3종 baseline.
Diataxis 4 categories.
Docs-as-code (markdown in git).
매 PR 가 docs 업데이트 검토.

8.3 KiB Raw Blame History