email-and-password-best-practices

email-and-password-best-practices 스킬 개요

email-and-password-best-practices 스킬은 전통적인 자격 증명 기반 로그인 구현 시 팀이 자주 놓치는 보안 요소들, 즉 이메일 인증, 비밀번호 재설정, 비밀번호 정책, 비밀번호 해싱 설정까지 포함해 Better Auth를 제대로 구성할 수 있도록 돕는 집중형 가이드입니다. 이미 Better Auth를 쓰기로 결정했고, 일반적인 인증 개요 설명이 아니라 운영 가능한 수준의 email/password 플로우를 빠르고 정확하게 구축하려는 개발자에게 특히 잘 맞습니다.

이 스킬로 할 수 있는 일

실제 목표가 “출시 가능한 수준으로 안전한 email/password 플로우를 완성하는 것”이라면 이 스킬을 쓰는 것이 좋습니다:

• Better Auth email/password 로그인 활성화
• 인증 이메일 발송
• 필요 시 로그인 전에 이메일 인증 강제
• 비밀번호 재설정 메일 발송 추가
• 비밀번호 규칙 및 검증 적용
• 해싱 동작 조정
• 필수 마이그레이션 단계 실행

누가 설치하면 좋은가

이 스킬은 다음과 같은 경우 특히 잘 맞습니다:

• Better Auth 프로젝트에 username/email 로그인을 추가하는 앱 팀
• 임시방편 인증 구현을 반복 가능한 설정 절차로 바꾸려는 개발자
• Better Auth 전용 설정 이름과 적용 순서를 에이전트가 정확히 기억하길 원하는 AI 코딩 워크플로우

반대로, 아직 인증 제공자를 비교 중이거나 앱이 OAuth/passkeys만 사용하고 비밀번호가 필요 없는 경우에는 활용도가 낮습니다.

일반적인 auth 프롬프트보다 왜 나은가

일반적인 프롬프트는 에이전트에게 “로그인과 비밀번호 재설정을 추가해” 정도로 지시할 수 있습니다. 하지만 이 스킬은 이를 Better Auth의 실제 설정 포인트와 기대되는 작업 순서로 구체화합니다. 예를 들어 emailAndPassword: { enabled: true }, emailVerification.sendVerificationEmail, reset-password 처리, npx @better-auth/cli@latest migrate까지 포함합니다. 그래서 Access Control용 email-and-password-best-practices 활용 시 훨씬 더 안정적으로 결과를 얻을 수 있습니다.

도입 전에 가장 먼저 확인할 것

설치 전에 아래 판단 기준을 확인하세요:

• 이메일 발송 함수가 이미 준비되어 있거나 최소한 도입 계획이 있어야 함
• 로그인 시 이메일 인증을 필수로 할지 결정해야 함
• 비밀번호 정책에 대한 기대치가 정리되어 있어야 함
• Better Auth 마이그레이션을 실행할 권한이 있어야 함
• 프론트엔드 폼만이 아니라 auth 서버 설정도 직접 수정할 수 있어야 함

email-and-password-best-practices 스킬 사용 방법

email-and-password-best-practices 스킬 설치 맥락

Better Auth skills 저장소에서 스킬을 설치하세요:

npx skills add https://github.com/better-auth/skills --skill emailAndPassword

그다음 AI 코딩 세션에서 Better Auth 자격 증명 기반 플로우를 설정, 점검, 개선하고 싶을 때 호출하면 됩니다.

먼저 읽어야 할 파일

가장 먼저 볼 파일은 다음입니다:

• better-auth/emailAndPassword/SKILL.md

이 저장소 구간은 가볍고 구조가 크지 않기 때문에, 많은 보조 파일을 탐색하는 것보다 가이드를 현재 코드베이스에 정확히 적용하는 데 핵심 가치가 있습니다.

이 스킬이 사용자에게 필요로 하는 입력

저장소만으로는 알 수 없는 맥락을 에이전트에게 직접 알려줘야 합니다:

• Better Auth 설정 파일 경로
• email/password가 이미 일부 활성화되어 있는지 여부
• 사용하는 이메일 발송 provider 또는 helper function
• 이메일 인증이 선택인지 필수인지
• 원하는 reset-password UX
• 비밀번호 길이 또는 복잡도 요구사항
• 커스텀 해싱 설정이 필요한지 여부

이 정보가 없더라도 에이전트가 기본 골격은 만들 수 있지만, 결과물은 다소 일반론적으로 흐를 가능성이 큽니다.

막연한 목표를 강한 프롬프트로 바꾸기

약한 프롬프트:

• “Set up auth with Better Auth.”

더 좋은 프롬프트:

• “Use the email-and-password-best-practices skill to configure Better Auth email/password login in src/lib/auth.ts, require email verification before sign-in, add sendVerificationEmail using our existing sendEmail() helper, implement reset-password email sending, and tell me what migration command and test steps I need.”

이 프롬프트가 더 잘 작동하는 이유는 파일 위치, 원하는 강제 정책, 기존 메일 발송 수단, 기대 산출물을 모두 함께 제공하기 때문입니다.

권장 설정 워크플로우

실무적으로는 다음 순서가 가장 무난합니다:

1. Better Auth에서 email/password를 활성화합니다.
2. 인증 이메일 발송을 추가합니다.
3. 로그인 전에 이메일 인증을 강제할지 결정합니다.
4. 비밀번호 재설정 이메일 발송을 추가합니다.
5. 비밀번호 검증 규칙을 적용합니다.
6. 해싱 설정은 커스터마이즈할 이유가 있을 때만 검토합니다.
7. 마이그레이션을 실행합니다.
8. 회원가입, 인증, 로그인, 재설정 플로우를 end-to-end로 테스트합니다.

이 순서는 재작업을 줄여 주고, 팀이 실제로 인증 기능을 롤아웃할 때 디버깅하는 방식과도 잘 맞습니다.

이 스킬이 중심에 두는 핵심 설정

이 스킬은 다음 Better Auth 기능들을 중심으로 구성되어 있습니다:

• emailAndPassword: { enabled: true }
• emailVerification.sendVerificationEmail
• emailAndPassword.requireEmailVerification
• sendResetPassword
• 비밀번호 정책 설정
• 해싱 알고리즘 커스터마이징
• npx @better-auth/cli@latest migrate

프롬프트에서 이 중 어떤 항목이 필요한지 분명히 말하지 않으면, 에이전트가 의도와 다른 기본값을 선택할 수 있습니다.

이메일 인증이 실제 도입의 가장 큰 난관인 경우가 많다

대부분의 팀에게 어려운 지점은 비밀번호 인증 자체를 켜는 일이 아니라, 인증 메일을 안전하게 운영 수준으로 붙이는 일입니다. 이 스킬이 유용한 이유는 sendVerificationEmail이 { user, url, token }를 받는다는 점, 그리고 제공되는 url에 이미 인증 링크가 포함되어 있다는 점을 에이전트에게 상기시켜 주기 때문입니다. 덕분에 전체 URL이 이미 있는데도 링크를 잘못 다시 조합하는 실수를 줄일 수 있습니다.

언제 이메일 인증을 필수로 해야 하나

계정 사용 전에 확인된 신원을 전제로 접근 제어를 설계했다면 emailAndPassword.requireEmailVerification를 사용하세요. 저장소 가이드에는 중요한 동작 하나도 함께 나와 있습니다. 인증되지 않은 사용자가 로그인을 시도하면 새 인증 이메일이 다시 발송됩니다. 이런 실무적인 동작은 일반적인 프롬프트에서는 자주 빠집니다.

비밀번호 재설정 사용 가이드

앱에서 비밀번호 분실 복구를 지원한다면, 에이전트에게 sendResetPassword 연결을 명시적으로 요청하고 전체 사용자 여정을 보여 달라고 하세요:

• 재설정 요청
• 이메일 수신
• 링크 접속
• 새 비밀번호 설정
• 다시 로그인

“reset password backend만 만들어 줘”처럼 요청하면, 메일 발송 단계가 빠진 반쪽짜리 구현이 나올 수 있습니다.

비밀번호 정책과 클라이언트 검증

이 스킬은 비밀번호 정책도 다루지만, 아래 항목을 명확히 적어 줄수록 결과가 좋아집니다:

• 최소 길이
• 특수문자 필수 여부
• 프론트엔드 검증이 백엔드 규칙을 그대로 따라야 하는지 여부
• 사용자 친화적 검증 메시지를 반환할지 여부

특히 회원가입, 비밀번호 변경, 재설정 플로우 전반에서 일관된 동작을 원한다면 이 부분이 중요합니다.

해싱 커스터마이징은 항상 필요한 것은 아니다

email-and-password-best-practices 사용 흐름에는 해싱 커스터마이징도 포함되지만, 이는 고급 요구사항으로 보는 편이 맞습니다. 컴플라이언스, 마이그레이션, 성능 같은 명확한 이유가 없다면 알고리즘을 섣불리 바꾸기보다, 안전한 기본값을 유지하고 그 이유를 설명해 달라고 요청하는 편이 낫습니다.

구현 후 바로 써먹을 수 있는 테스트 체크리스트

에이전트에게 아래 시나리오를 검증하게 하세요:

• 신규 사용자 회원가입 성공
• 인증 이메일 발송
• 인증 링크 정상 동작
• 필요 시 미인증 사용자 로그인 차단
• 예상한 조건에서 재로그인 시 새 인증 이메일 발송
• 비밀번호 재설정 이메일 정상 발송
• 재설정 후 기존 비밀번호가 더 이상 동작하지 않음
• 약한 비밀번호 입력 시 명확하게 검증 실패 처리

이 지점에서 email-and-password-best-practices 가이드는 저장소를 대충 훑는 것보다 훨씬 가치가 커집니다. 단순히 설정을 붙이는 데서 끝나지 않고, 실제 동작을 검증하도록 도와주기 때문입니다.

email-and-password-best-practices 스킬 FAQ

이 스킬은 Better Auth 전용인가요?

네. 이 스킬은 Better Auth 설정과 플로우를 위한 provider 전용 스킬입니다. Better Auth를 사용하지 않는다면 설정 이름과 마이그레이션 단계는 그대로 옮겨 쓸 수 없습니다.

email-and-password-best-practices 스킬은 초보자도 쓰기 쉬운가요?

대체로 그렇습니다. 다만 auth 설정 파일이 어디에 있는지, 앱이 이메일을 어떤 방식으로 보내는지 정도는 이미 알고 있어야 합니다. SMTP, transactional email provider, route 연결, 프론트엔드 폼 같은 부분은 완전 초보자에게 별도의 도움이 더 필요할 수 있습니다.

이 스킬이 뭔가를 스스로 설치하나요?

아니요. 이 스킬은 AI 워크플로우를 위한 가이드입니다. 실제 프로젝트에는 Better Auth가 이미 설정되어 있어야 하고, 사용하는 이메일 provider 연동도 필요하며, 마이그레이션 명령도 직접 실행해야 합니다.

언제 이 스킬을 쓰지 않는 편이 좋은가요?

다음 경우라면 건너뛰는 편이 낫습니다:

• OAuth 또는 passkeys만 필요할 때
• Better Auth를 구현하는 것이 아니라 인증 플랫폼을 비교 중일 때
• 앱 정책상 비밀번호 로그인을 완전히 금지할 때
• Better Auth 설정 작업이 아니라 더 넓은 보안 아키텍처 리뷰가 필요할 때

LLM에게 그냥 auth 도움을 요청하는 것과 뭐가 다른가요?

email-and-password-best-practices 스킬은 범위가 더 좁고 실행 지향적입니다. 모델이 Better Auth의 실제 설정 표면과 인증/재설정 플로우의 운영상 세부 사항에 집중하게 만들어, 존재하지 않는 API를 지어내거나 필요한 단계를 빼먹을 가능성을 줄여 줍니다.

Access Control용 email-and-password-best-practices에도 유용한가요?

네. 특히 앱 접근 권한이 “인증된 신원”에 의존하는 경우 매우 유용합니다. 미인증 로그인 차단 여부는 이 스킬이 올바르게 구현하도록 도와주는 가장 중요한 정책 결정 중 하나입니다.

email-and-password-best-practices 스킬을 더 잘 활용하는 방법

정확한 auth 파일과 메일 헬퍼를 지정하세요

출력 품질을 가장 빠르게 높이는 방법은 에이전트에게 올바른 파일과 기존 이메일 유틸리티를 정확히 지정하는 것입니다. 예를 들면:

• “Edit src/lib/auth.ts and use lib/email/sendEmail.ts.”

이렇게 하면 추측할 여지가 줄고, 실체 없는 추상화가 끼어들 가능성도 낮아집니다.

이메일 인증 정책을 처음부터 명확히 말하세요

email-and-password-best-practices 작업에서는 아래 한 문장이 빠지면 수정 왕복이 크게 늘어납니다:

• “Users must verify email before first sign-in.”

또는

• “Users can sign in before verification, but we still send verification email.”

이 부분을 명시하지 않으면, 구현은 안전할 수 있어도 제품 정책에는 맞지 않는 결과가 나올 수 있습니다.

설정만이 아니라 end-to-end 플로우까지 요청하세요

더 강한 요청 방식은 다음과 같습니다:

• “Configure the backend and show the frontend/user flow, email triggers, migration command, and manual test plan.”

이렇게 요청하면 auth 서버 설정만 끝나고 실제로 사용자가 어떻게 플로우를 완료하는지는 아무도 모르는, 불완전한 결과를 피할 수 있습니다.

자주 발생하는 실패 패턴을 주의하세요

이 스킬 사용 시 흔한 문제는 다음과 같습니다:

• 실제 이메일 발송 구현을 빼먹는 경우
• url이 이미 제공되는데도 인증 링크를 따로 생성하는 경우
• 인증 기능은 켰지만 로그인 차단 여부를 결정하지 않은 경우
• reset-password 전송은 연결했지만 callback 경로를 테스트하지 않은 경우
• 프론트엔드 비밀번호 규칙이 백엔드 검증과 맞지 않는 경우

더 강한 비밀번호 처리를 원하면 정책 세부사항을 주세요

운영 환경에서 비밀번호 강도가 중요하다면 요구사항을 정확히 적어 주세요. “Use strong passwords”는 너무 모호합니다. 더 좋은 프롬프트는 길이, 금지 패턴, 재설정 시 기대 동작, 기존 사용자가 즉시 정책을 따라야 하는지 아니면 변경/재설정 시점에만 적용할지까지 명시합니다.

코드 수정만이 아니라 트레이드오프 설명도 요청하세요

좋은 프롬프트 추가 문구 예시는 다음과 같습니다:

• “Explain why you kept defaults or changed hashing settings, and note any security/usability tradeoffs.”

이렇게 하면 리뷰 가능성이 높아지고, 팀이 근거 없이 보안 설정만 따라 하는 일을 줄일 수 있습니다.

첫 초안 뒤에는 실패 케이스 중심으로 한 번 더 다듬으세요

에이전트가 1차 구현을 만든 뒤에는 이런 식으로 개선 요청을 해보세요:

• “Now review this for unverified-user edge cases.”
• “Add manual test cases for expired reset links.”
• “Check whether password validation is consistent between sign-up and reset.”

이 두 번째 패스에서 email-and-password-best-practices 설치의 가치가 특히 드러납니다. 일반적인 인증 조언으로 흐르지 않고, 실제 Better Auth 동작을 기준으로 반복 개선을 이어갈 수 있기 때문입니다.