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 ログインを有効化する
• 確認メールを送信する
• 必要に応じて、確認済みメールアドレスでないとサインインできないようにする
• パスワードリセットの送信処理を追加する
• パスワードルールとバリデーションを適用する
• ハッシュ動作を調整する
• 必須の migration ステップを実行する

どんな人に向いているか

このスキルは、次のようなケースに強く適合します。

• Better Auth プロジェクトに username/email ログインを追加するアプリ開発チーム
• その場しのぎの認証実装から、再現性のある導入手順に置き換えたい開発者
• Better Auth 固有の設定名や実装順序を AI エージェントに正確に踏まえてほしい AI 支援コーディングのワークフロー

一方で、認証プロバイダ自体をまだ比較検討している段階や、OAuth/passkeys のみを使い、パスワード認証が不要なアプリにはあまり向いていません。

一般的な auth プロンプトより優れている理由

汎用的なプロンプトだと、エージェントに「ログインとパスワードリセットを追加して」といった曖昧な指示になりがちです。このスキルはそれを Better Auth の実際の設定項目と導入順に落とし込みます。たとえば emailAndPassword: { enabled: true }、emailVerification.sendVerificationEmail、reset-password の処理、npx @better-auth/cli@latest migrate まで含めて扱います。結果として、email-and-password-best-practices for Access Control のような用途でも、実装の再現性と正確性がかなり高まります。

導入前に特に確認したいポイント

インストール前に、次の判断ポイントを確認してください。

• メール送信関数をすでに用意している、またはこれから用意する前提がある
• サインイン時に確認済みメールを必須にするか決める必要がある
• 期待するパスワードポリシーを把握している
• Better Auth の migration を実行できる権限や環境がある
• フロントエンドのフォームだけでなく、auth サーバー設定も編集できる

email-and-password-best-practices スキルの使い方

email-and-password-best-practices スキルの導入方法

Better Auth skills repository からこのスキルをインストールします。

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

その後、Better Auth の認証フローを設定・監査・改善したい AI コーディングセッション内で呼び出してください。

まず最初に読むファイル

最初に確認するのは次です。

• better-auth/emailAndPassword/SKILL.md

この repository の該当部分は軽量なので、大きな補助ツリーを読み回るよりも、ガイダンスを自分のコードベースに正しく当てはめることに価値があります。

スキルが必要とする入力情報

repository だけでは推測できない前提を、エージェントに渡してください。

• Better Auth の config file のパス
• email/password がすでに一部有効になっているかどうか
• 使用中のメール送信プロバイダ、または helper function
• メール確認が任意か必須か
• 望んでいる reset-password UX
• パスワードの長さや複雑性に関する要件
• custom hashing settings が必要かどうか

この前提がない場合でもエージェントはひな形を作れますが、出力はどうしても汎用的になります。

あいまいな依頼を強いプロンプトに変える

弱いプロンプト:

• “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. reset-password のメール送信を追加する。
5. パスワード検証ルールを適用する。
6. hashing settings は、カスタマイズ理由がある場合にだけ見直す。
7. migration を実行する。
8. sign-up、verification、sign-in、reset の各フローを end-to-end でテストする。

この順序にしておくと手戻りが減り、認証導入時にチームが実際に詰まりやすい箇所にも沿っています。

このスキルが軸にしている主要設定

このスキルは、主に次の Better Auth 機能を中心に組み立てられています。

• emailAndPassword: { enabled: true }
• emailVerification.sendVerificationEmail
• emailAndPassword.requireEmailVerification
• sendResetPassword
• password policy configuration
• hashing algorithm customization
• npx @better-auth/cli@latest migrate

プロンプト内でどれが必要か明示しないと、エージェントが意図しない default を選ぶことがあります。

導入時の最大の壁はメール確認

多くのチームにとって難所は、password auth を有効化すること自体ではなく、確認フローを安全に本番投入することです。このスキルが有用なのは、sendVerificationEmail が { user, url, token } を受け取り、しかも渡される url に確認リンクがすでに含まれている点をエージェントに思い出させてくれるからです。完全な URL が用意されているのに、リンクを自前で再構築して壊してしまうミスを防ぎやすくなります。

確認済みメールを必須にすべきケース

アカウント利用前に本人確認済みであることが access control 上重要なら、emailAndPassword.requireEmailVerification を使ってください。repository のガイダンスには見落としやすい挙動も書かれています。未確認ユーザーがサインインを試みると、新しい確認メールが再送されます。こうした実運用に効く挙動は、一般的なプロンプトだと抜けがちです。

パスワードリセットの実装方針

アプリでパスワード忘れ時の復旧をサポートするなら、sendResetPassword の組み込みを明示的に依頼し、あわせてユーザーの一連の体験まで出力させるのが重要です。

• リセットをリクエストする
• メールを受け取る
• リンクを開く
• 新しいパスワードを設定する
• 再度サインインする

「reset password backend だけ作って」と頼むと、送信処理のない不完全実装で終わることがあります。

パスワードポリシーとクライアント側バリデーション

このスキルは password policy も扱いますが、次の点を具体的に伝えるほど結果が良くなります。

• 最小文字数
• 記号を必須にするか
• frontend validation を backend rules と一致させるか
• ユーザー向けにわかりやすい validation message を返すか

特に、sign-up、パスワード変更、reset フローで一貫した挙動を求めるチームには重要です。

hashing のカスタマイズが不要なことも多い

email-and-password-best-practices の利用には hashing customization も含まれますが、これは上級者向け要件として扱うのが適切です。コンプライアンス、移行要件、性能上の理由がない限り、不要にアルゴリズムを変えるより、安全な default を維持しつつその理由を説明させるほうが実用的です。

実装後の実践的なテストチェックリスト

エージェントには、少なくとも次のシナリオを検証させてください。

• 新規ユーザーの sign-up が成功する
• 確認メールが送信される
• 確認リンクが正しく機能する
• 必須設定時、未確認ユーザーの sign-in がブロックされる
• 想定どおりであれば、再度の sign-in で確認メールが再送される
• reset-password メールが正常に送信される
• reset 後は古いパスワードでログインできなくなる
• 弱いパスワード入力時に、明確な validation failure が返る

ここで email-and-password-best-practices ガイドの価値がはっきり出ます。単に config を貼るだけでなく、挙動まで検証できるからです。

email-and-password-best-practices スキル FAQ

このスキルは Better Auth 専用ですか？

はい。これは Better Auth の設定と認証フローに特化した provider-specific skill です。Better Auth を使っていない場合、設定名や migration 手順はそのまま流用できません。

email-and-password-best-practices スキルは初心者向けですか？

基本的には yes ですが、少なくとも auth config がどこにあるか、アプリがどうメール送信しているかは把握している前提です。完全な初心者であれば、SMTP、transactional email provider、route wiring、frontend form については別途サポートが必要になることがあります。

これだけで何か自動インストールされますか？

いいえ。このスキルは AI ワークフロー向けのガイダンスです。実際のプロジェクト側では、Better Auth のセットアップ、利用するメールプロバイダ連携、そして環境上での migration command 実行が必要です。

このスキルを使わないほうがいいのはどんなときですか？

次のような場合は見送って構いません。

• OAuth または passkeys しか必要ない
• Better Auth を実装するのではなく、auth platform を比較中
• アプリの方針として password login を完全に禁止している
• Better Auth の config 作業ではなく、より広い security architecture review を求めている

LLM に普通に auth の相談をするのと何が違いますか？

email-and-password-best-practices スキルは、対象範囲が狭いぶん実装に直結しやすいのが違いです。Better Auth の実際の設定面と、verification / reset フローの運用上の細部にモデルを寄せられるため、存在しない API をでっち上げたり、必要工程を落としたりするリスクを減らせます。

email-and-password-best-practices for Access Control にも役立ちますか？

はい。特に、確認済みの本人性を前提に app access を与える access control では有効です。未確認ユーザーの sign-in をブロックする要件は、このスキルが正しく実装しやすくしてくれる最重要ポリシーのひとつです。

email-and-password-best-practices スキルを改善するには

正確な auth file と mail helper を渡す

出力品質を最も手早く上げる方法は、対象ファイルと既存のメール utility を明示することです。たとえば次のように伝えます。

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

これだけで推測が減り、実在しない abstraction を作られにくくなります。

verification policy を最初に明言する

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.”

これを指定しないと、安全ではあってもプロダクト要件には合わない実装になることがあります。

config だけでなく end-to-end フローまで求める

より強い依頼は次の形です。

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

こう依頼すると、auth server だけ設定されて、ユーザーがどう完了するのか誰もわからない、といった中途半端な出力を避けやすくなります。

よくある失敗パターンを確認する

このスキル利用時によくある問題は次のとおりです。

• 実際のメール送信処理を実装し忘れる
• url がすでにあるのに独自の verification link を生成してしまう
• verification は有効にしたのに、sign-in を止めるかどうか決めていない
• reset-password の送信経路だけつないで callback path を検証していない
• frontend の password rules と backend validation が一致していない

強いパスワード運用にはポリシー詳細を渡す

パスワード強度が重要な環境なら、要件は具体的に伝えてください。“Use strong passwords” では曖昧すぎます。より良いプロンプトでは、文字数、禁止パターン、reset 時の期待、既存ユーザーにも即時適用するのか、変更/reset 時のみ適用するのかまで明記します。

コード修正だけでなく tradeoff の説明も求める

有効な追加指示の例:

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

こうしておくとレビューしやすくなり、形だけの security change をチームが無批判に取り込むのを防ぎやすくなります。

初稿のあとに失敗ケース込みで再レビューする

エージェントが最初の実装を出したあと、次のように追加で依頼すると改善しやすくなります。

• “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.”

この 2 回目の見直しで、email-and-password-best-practices の導入価値が特に効いてきます。一般的な auth アドバイスに流れず、Better Auth の実際の挙動に沿って改善を進められるためです。