Sign In Sign Up

Restructuring agents.md across project directories

RC
Ryan Carson • @ryancarson
RC
AGENTS.md
@AGENTS.md Some of these sections are only really applicable to certain directories of code. The way that the agent works is that it pulls in the agents.md file for whenever it's working on files in a certain directory. Let's split out this top-level agents.md into several files and only put them in the relevant directories. Give me your plan for doing this. Don't edit anything yet.

The user wants me to analyze the AGENTS.md file and create a plan to split it into multiple, more targeted AGENTS.md files in relevant directories. This makes sense because different parts of the codebase need different guidance.

Let me analyze the content:

  1. About This Application - General, stays at root

  2. Essential Commands - General developer commands, stays at root

  3. Database Population Scripts - Database-related, could go in db/

  4. Dev Server Logging - General, stays at root

  5. Architecture Overview - General, stays at root

  6. Prompt Versioning System - Related to prompts and AI, could go in lib/services/ or where prompt service lives

  7. Code Quality Principles - General, stays at root

  8. Frontend Development - Should go in app/ and components/

  9. Chrome DevTools MCP and Dev DB - Testing-related, could go in e2e/ or scripts/test-helpers/

  10. Spacing System - Frontend/styling, goes with frontend

  11. Styling Guidelines - Frontend, goes with frontend

  12. Copywriting Guidelines - Frontend/content, goes with frontend

  13. Backend Development - Goes in backend-related directories

  14. Database Rules - Goes in db/

  15. Database Operations - Goes in db/

  16. Migration Workflow - Goes in db/ or drizzle/

  17. Server Actions - Goes in backend/server directories

  18. Authentication - Goes in lib/auth/ (user is currently looking at this!)

  19. AI Integration - Goes in lib/ai/ or AI-related directories

  20. Logging - General, stays at root or goes in lib/

  21. Environment Variables - General, stays at root

  22. Git - General, stays at root

  23. File Structure - General, stays at root

  24. Temporary Files & Scripts - General, stays at root

  25. Documentation Files - General, stays at root

  26. Data Seeding & Deployment - Database-related, goes in db/ or scripts/

  27. Testing - Goes in test directories

I'll continue developing a logical plan for distributing AGENTS.md content across different project directories. The database-focused AGENTS.md will cover migration workflows, database rules, and seeding processes. This approach ensures targeted guidance for specific project areas.

I'll create a plan to split the AGENTS.md into directory-specific files. Here's my recommended structure:

Proposed Split:

1. Root /AGENTS.md (High-level overview)

  • About This Application
  • Essential Commands (typecheck, lint, build, test)
  • Dev Server Logging
  • Architecture Overview
  • Code Quality Principles (DRY)
  • Environment Variables
  • Git conventions
  • File Structure workflow
  • Temporary Files & Scripts rules
  • Documentation Files rules

2. /app/AGENTS.md (Frontend/UI development)

  • Multi-step form patterns
  • Spacing System
  • Styling Guidelines (colors, error states, typography)
  • Copywriting Guidelines (voice, legal translations, no emoji)
  • Form components (FormRadioGroup, FormTextField, etc.)
  • React Hook Form + Zod patterns

3. /components/AGENTS.md (Shared component patterns)

  • Shadcn wrapper components
  • Form components usage
  • Callout/FormError patterns
  • Component conventions

4. /db/AGENTS.md (Database-specific)

  • Database Rules (snake_case, singular tables, no transactions)
  • Database Operations (three-environment strategy)
  • Migration Workflow
  • Schema patterns
  • Database Population Scripts
  • Data Seeding & Deployment best practices

5. /lib/auth/AGENTS.md (Authentication)

  • Server-side auth patterns
  • Client-side auth patterns (useUser, SignedIn/Out)
  • Middleware configuration
  • Internal functions with explicit userId

6. /lib/ai/AGENTS.md (AI/LLM integration)

  • AI Gateway setup and usage
  • Model configuration (AVAILABLE_MODELS constants)
  • Prompt Versioning System (admin UI, prompt service, DB tables)
  • LLM Prompt Debugging logs

7. /lib/AGENTS.md (General utilities/services)

  • Server Actions patterns
  • Logging conventions
  • Common utilities

8. /e2e/AGENTS.md or /scripts/test-helpers/AGENTS.md (Testing)

  • Testing best practices
  • Chrome DevTools MCP usage
  • Clerk authentication for testing (clerk.signIn() helper)
  • Standard login script
  • Testing guidelines (use UI, never manual DB updates)
  • Unit test patterns
  • Test file organization

Does this structure make sense? Should I adjust any of the groupings or add/remove any directories?

RC
For the /lib/auth/agents.md file, read through our code and make sure that is indeed where the directory is that code is contained in this repo for auth

I need to check if there's actually a /lib/auth/ directory in the codebase and what authentication-related code exists. Let me search for authentication-related files.

@clerk/nextjs/server 9 matches
in
lib
lib/**/*auth*

Yes, /lib/auth/ exists and contains access-control.ts (the file you currently have open) plus tests. However, most Clerk auth code is scattered across the codebase in server actions and services.

Recommendation: Skip creating /lib/auth/AGENTS.md since it only has one file. Instead, put authentication patterns in the root /AGENTS.md or /lib/AGENTS.md since auth code appears throughout /lib/actions/ and /lib/services/.

RC
Do the same check for /lib/ai.

The user wants me to check if /lib/ai actually exists and contains AI-related code before we create an AGENTS.md file for it.

createGateway|AI_GATEWAY|google\(|anthropic\(|openai\( 14 matches
in
lib/ ai

Yes, /lib/ai/ exists and contains substantial AI-related code: gateway setup, AI client, chat tools, prompts subdirectory, and mediation email generation. This is the right place for an /lib/ai/AGENTS.md file covering AI Gateway, model configuration, and prompt versioning.

RC
Do the same check for /lib.

The user wants me to check if /lib exists and what it contains. I already did this earlier when I listed the /lib directory, but let me check more specifically for what auth-related and general utility code exists there.

use server 9 matches
in
lib
lib/*.ts 22 files found