AGENT SKILL

adr-log

Document architecture decisions with ADR (Architecture Decision Records). Use when making significant technical decisions, choosing between alternatives, or when onboarding needs context on past decisions.

License 许可
MIT
所属仓库
bg-szy/TOP-SKILLS
最近更新
2026-11-15
Stars
★ 6
Forks
0

01 前言 Front Matter

name
adr-log
license
MIT
metadata
{ "author": "antigravity-team", "version": "1.0" }
description
Document architecture decisions with ADR (Architecture Decision Records). Use when making significant technical decisions, choosing between alternatives, or when onboarding needs context on past decisions.
allowed-tools
Read, Glob, Grep, Edit, Write, Bash

02 资源文件 2

03 SKILL.md 正文

ADR (Architecture Decision Records)

아키텍처 결정을 문서화하여 "왜 그렇게 했는지"를 기록하는 스킬입니다.

Core Principle

"결정의 '무엇'보다 '왜'가 중요하다." "6개월 후의 나도 알아볼 수 있게 기록한다."

ADR이 필요한 경우

상황 예시
기술 선택 React vs Vue, PostgreSQL vs MongoDB
아키텍처 패턴 Monolith vs Microservices
의존성 추가 새 라이브러리 도입
보안 결정 인증 방식 선택
성능 트레이드오프 캐싱 전략 결정
표준 변경 코딩 컨벤션 변경

ADR 폴더 구조

docs/
└── adr/
    ├── 0000-adr-template.md
    ├── 0001-use-nextjs-app-router.md
    ├── 0002-choose-postgresql-over-mongodb.md
    ├── 0003-implement-jwt-authentication.md
    └── README.md

ADR 템플릿

docs/adr/0000-adr-template.md

# [번호]. [결정 제목]

날짜: YYYY-MM-DD

## 상태

[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## 컨텍스트

이 결정이 필요한 배경/문제 상황을 설명합니다.

- 현재 상황은 무엇인가?
- 어떤 문제를 해결하려 하는가?
- 어떤 제약 조건이 있는가?

## 결정

우리는 [X]를 선택했다.

### 고려한 대안들

1. **대안 A**: [설명]
   - 장점: ...
   - 단점: ...

2. **대안 B**: [설명]
   - 장점: ...
   - 단점: ...

3. **선택: 대안 C**: [설명]
   - 장점: ...
   - 단점: ...

## 결과

### 긍정적 영향
- ...

### 부정적 영향
- ...

### 리스크
- ...

## 참고 자료

- [링크1]
- [링크2]

실제 ADR 예시

docs/adr/0001-use-nextjs-app-router.md

# 1. Next.js App Router 사용

날짜: 2024-01-15

## 상태

Accepted

## 컨텍스트

새 프로젝트의 프론트엔드 프레임워크를 선택해야 한다.

요구사항:
- SEO 최적화 필요 (마케팅 페이지)
- 빠른 초기 로딩
- 팀의 React 경험 활용
- 서버 사이드 데이터 페칭

## 결정

**Next.js 14 App Router**를 선택한다.

### 고려한 대안들

1. **Next.js Pages Router**
   - 장점: 안정적, 레퍼런스 많음
   - 단점: 레거시화 진행 중, 새 기능 제한적

2. **Remix**
   - 장점: 뛰어난 데이터 로딩, 프로그레시브 향상
   - 단점: 팀 학습 비용, 상대적으로 작은 생태계

3. **선택: Next.js App Router**
   - 장점: React Server Components, 향상된 캐싱, Vercel 최적화
   - 단점: 일부 라이브러리 호환성 이슈, 학습 곡선

## 결과

### 긍정적 영향
- React Server Components로 번들 크기 감소
- 레이아웃 중첩으로 코드 재사용성 향상
- Vercel 배포 최적화

### 부정적 영향
- 일부 클라이언트 전용 라이브러리 사용 시 'use client' 필요
- Pages Router 경험자의 학습 필요

### 리스크
- App Router의 상대적인 신규성 (안정성 확인 필요)
- 일부 third-party 라이브러리 호환성

## 참고 자료

- [Next.js App Router Docs](https://nextjs.org/docs/app)
- [Server Components RFC](https://github.com/reactjs/rfcs/pull/188)

docs/adr/0002-choose-postgresql-over-mongodb.md

# 2. PostgreSQL 선택 (MongoDB 대신)

날짜: 2024-01-20

## 상태

Accepted

## 컨텍스트

프로젝트의 주 데이터베이스를 선택해야 한다.

데이터 특성:
- 사용자, 프로젝트, 미디어 간 관계 존재
- 트랜잭션 무결성 필요 (결제 연동 예정)
- 복잡한 쿼리 (필터링, 정렬, 집계)

## 결정

**PostgreSQL**을 선택한다.

### 고려한 대안들

1. **MongoDB**
   - 장점: 스키마 유연성, 수평 확장 용이
   - 단점: 복잡한 JOIN 어려움, 트랜잭션 제한

2. **선택: PostgreSQL**
   - 장점: ACID 보장, 강력한 JOIN, JSON 지원
   - 단점: 수평 확장 복잡, 스키마 변경 마이그레이션 필요

## 결과

### 긍정적 영향
- Prisma와 완벽한 호환
- 복잡한 관계 쿼리 최적화
- 결제 데이터 무결성 보장

### 부정적 영향
- 스키마 변경 시 마이그레이션 필요
- 초기 스키마 설계 중요

### 관련 결정
- Prisma ORM 사용 (ADR-003 예정)
- 마이그레이션 전략 수립 필요

ADR 작성 가이드

번호 체계

0001 ~ 0099: 기초 아키텍처 결정
0100 ~ 0199: 프론트엔드 관련
0200 ~ 0299: 백엔드 관련
0300 ~ 0399: 인프라/DevOps 관련
0400 ~ 0499: 보안 관련

상태 흐름

Proposed → Accepted → [Deprecated | Superseded]
  • Proposed: 검토 중
  • Accepted: 승인되어 적용 중
  • Deprecated: 더 이상 유효하지 않음
  • Superseded by ADR-XXXX: 새 결정으로 대체됨

작성 팁

## 컨텍스트 작성 팁
- 배경 설명은 신규 팀원도 이해할 수 있게
- 제약 조건(시간, 예산, 기술 스택) 명시
- 문제의 긴급성/중요도 언급

## 결정 작성 팁
- 결정 내용을 한 문장으로 요약
- 대안들을 공정하게 비교
- 선택 이유를 명확히

## 결과 작성 팁
- 트레이드오프를 솔직하게
- 예상 리스크와 대응 방안
- 관련된 후속 결정 언급

ADR 도구

adr-tools (CLI)

# macOS
brew install adr-tools

# 초기화
adr init docs/adr

# 새 ADR 생성
adr new "Use Next.js App Router"

# ADR 목록
adr list

# ADR 생성 (대체)
adr new -s 1 "Switch to Remix"

README.md (ADR 인덱스)

# Architecture Decision Records

| 번호 | 제목 | 상태 | 날짜 |
|------|------|------|------|
| [0001](0001-use-nextjs-app-router.md) | Next.js App Router 사용 | Accepted | 2024-01-15 |
| [0002](0002-choose-postgresql-over-mongodb.md) | PostgreSQL 선택 | Accepted | 2024-01-20 |
| [0003](0003-jwt-authentication.md) | JWT 인증 구현 | Accepted | 2024-01-25 |

Workflow

ADR 작성 시점

1. 기술 선택/변경 논의 시작
2. 대안 검토 및 비교
3. 팀 논의 (PR 또는 미팅)
4. 결정 후 ADR 작성
5. PR로 ADR 추가
6. 리뷰 후 머지

코드 리뷰에서

PR 리뷰어:
"이 라이브러리 선택에 대한 ADR이 있나요?"

작성자:
"ADR-0015에 근거 정리되어 있습니다."
또는
"ADR 추가하겠습니다."

Checklist

프로젝트 설정

  • [ ] docs/adr/ 폴더 생성
  • [ ] ADR 템플릿 파일 추가
  • [ ] README.md (인덱스) 생성
  • [ ] 번호 체계 정의

ADR 작성 시

  • [ ] 컨텍스트가 충분히 설명되었는가?
  • [ ] 대안들이 공정하게 비교되었는가?
  • [ ] 결정 이유가 명확한가?
  • [ ] 트레이드오프가 솔직하게 기록되었는가?
  • [ ] 관련 ADR/이슈가 링크되었는가?

References

04 同仓库更多 Skills

bg-szy
bg-szy/TOP-SKILLS

serpmaven

Scrape Google search results (SERP) to JSON with SERP Maven (serpmaven) - a real Chrome browser on a residential proxy with sticky sessions. Run it as a CLI, a Python library, a local HTTP search API (`serve`), an MCP server or a Docker image; set the proxy login, workers, pages and cost tracking. Use when the user wants Google results, rank tracking, a self-hosted SERP API, or live Google search for an AI agent.

★ 6
bg-szy
bg-szy/TOP-SKILLS

revnu-landing-page-audit

Find out why a landing page isn't turning visitors into signups, demos or sales. Audits one page against what the ad, post or search that sends people there promised, then checks the first screen, proof, call to action, friction and mobile. Returns at most 7 prioritized fixes, plus what is fine and what could not be checked; rewrites specific lines and fixes the page in the repo when asked. Never promises a conversion lift. Works without a Revnu account. Use when the user says or asks: "audit my landing page", "why isn't this page converting", "review my homepage", "my ads get clicks but no signups", "people bounce from the pricing page", "CRO review", "improve conversion rate", "is my hero section clear", "roast my landing page", "rewrite my headline", "what's wrong with this page", "landing page feedback", "make the signup page convert better". Not for SEO or AI-search audits, page speed engineering on its own, or building a new page from scratch.

★ 6
bg-szy
bg-szy/TOP-SKILLS

revnu-growth-context

Write down once who buys, what they're stuck on, what it costs, what proof you have and what you've already tried, so every growth task starts from facts instead of a questionnaire. Creates or updates .agents/revnu-growth.md from the repo, the live site and the user, and imports an existing product-marketing.md. Use when the user says "set up our marketing context", "who is our ideal customer", "write our ICP", "describe the product for marketing", "positioning doc", "what's our brand voice", "remember this about our customers", "log what we tried", "what have we learned from marketing", "we changed pricing, update the context", "update our growth notes", "summarize the business for the agent", "import my product-marketing.md", "start a growth doc", or before a first marketing, SEO, outreach or launch task when no context file exists. Works without a Revnu account.

★ 6
bg-szy
bg-szy/TOP-SKILLS

revnu-get-listed

Get onto the third-party pages AI answers and search cite when buyers ask for the best tool in your category: "best X" roundups, directories, review sites, GitHub awesome lists, community threads and comparison pages. Finds which ones are cited, ranks them by fit and effort, and drafts each submission, PR or pitch by the target's own rules. Use when the user says "get us listed", "which directories should we submit to", "how do we get into best-of lists", "why does ChatGPT recommend competitors and not us", "get mentioned in AI answers", "submit to awesome lists", "get on G2", "where are our competitors listed", "pitch listicle authors", "find backlink opportunities", "launch directories", "get into roundups", "Product Hunt alternatives", "where should we be listed", "get cited by Perplexity". Never submits, pays or posts without a yes. Works without a Revnu account.

★ 6
bg-szy
bg-szy/TOP-SKILLS

revnu-ai-readiness-audit

Audit whether your website gives ChatGPT, Perplexity, Claude, Gemini and Google's AI Overviews something worth quoting, and fix the pages that don't. Use when the user says or asks "is my site ready for AI search", "audit my site for AI answers", "AEO audit", "GEO audit", "why doesn't ChatGPT quote our pricing", "make our pages citable by AI", "do I need llms.txt", "does schema help with ChatGPT", "check our structured data", "is our content visible without JavaScript", "AI SEO audit", "optimize our homepage for AI answers", "LLM SEO check", "why does AI get our product wrong", "fix our site for AI Overviews". Checks fetchability and indexability, answers in the raw HTML, entity facts, schema (including JS-injected markup), headings, dates and llms.txt, then gives at most 10 prioritised fixes and edits the repo when asked. Works without a Revnu account.

★ 6
bg-szy
bg-szy/TOP-SKILLS

proxy-troubleshooting

Diagnose residential proxy failures, with NodeMaven's gateway as the reference - 407 with correct credentials, 406, 410, 500, a connection that hangs, ERR_TUNNEL_CONNECTION_FAILED in a browser, Playwright or Puppeteer ignoring proxy credentials, a sticky session that changes IP, geo-targeting that is silently ignored, passwords with special characters, and unexpected traffic from headless Chrome. Use when a proxy connection fails, returns the wrong location, or costs more traffic than expected.

★ 6