The-Utopia-Studio/prompt-engineer

Prompt Engineer

Makes your repository "AI-native" so any coding agent (Claude Code, Cursor, Copilot, Gemini CLI, Codex) can understand and work with your codebase effectively.

How It Works

1. Analyze codebase patterns and conventions
2. Create AGENTS.md following the WHAT/WHY/HOW framework
3. Create .cursorrules with code style and framework patterns
4. Add directory-level READMEs for agent navigation

Key Principle

Source: HumanLayer - "Writing a good CLAUDE.md"

Claude Code injects CLAUDE.md with a system note: "this context may or may not be relevant to your tasks." This means agents WILL IGNORE instructions that aren't universally applicable. Only include information that's relevant to EVERY task.

Step-by-Step Procedure

Step 1: Analyze Codebase Patterns

# Identify tech stack
cat package.json 2>/dev/null | head -30
cat requirements.txt pyproject.toml 2>/dev/null | head -20

# Identify naming conventions
find . -name "*.ts" -not -path "*/node_modules/*" | head -5 | xargs head -20

# Identify file structure pattern
find . -type f -not -path "./.git/*" -not -path "*/node_modules/*" -not -path "*/.next/*" -maxdepth 3 | head -40

# Identify available scripts/commands
cat package.json 2>/dev/null | python3 -c "import sys,json; [print(f'  {k}: {v}') for k,v in json.load(sys.stdin).get('scripts',{}).items()]" 2>/dev/null

# Check for existing agent config
ls AGENTS.md CLAUDE.md .cursorrules .cursor/rules/ .github/copilot/ 2>/dev/null

Step 2: Create AGENTS.md

Framework: WHAT (tech & structure) → WHY (purpose) → HOW (commands & verification)

Generate this template filled with detected values:

# AGENTS.md

## Project Overview
{One sentence: what this project does and who it's for.}

## Tech Stack
- **Runtime:** {Node.js 20 / Python 3.11 / etc.}
- **Framework:** {Next.js 14 / FastAPI / etc.}
- **Database:** {PostgreSQL + Prisma / MongoDB + Mongoose / etc.}
- **Styling:** {Tailwind CSS / styled-components / etc.}
- **Auth:** {NextAuth / Clerk / Supabase Auth / etc.}
- **Hosting:** {Vercel / AWS / Railway / etc.}

## Commands
```bash
{package_manager} run dev     # Start development server
{package_manager} run build   # Production build
{package_manager} run test    # Run tests
{package_manager} run lint    # Run linter

Project Structure

{root}/
├── app/          # {description}
├── components/   # {description}
├── lib/          # {description}
├── prisma/       # {description}
└── public/       # {description}

Conventions

• {Naming convention: e.g., "camelCase for variables, PascalCase for components"}
• {Import convention: e.g., "Use @/ alias for project imports"}
• {Error handling: e.g., "Use try/catch with structured logging via pino"}
• {State management: e.g., "Server components by default, client only when needed"}

Boundaries

• DO NOT modify prisma/schema.prisma without running npx prisma generate
• DO NOT commit .env files — use .env.example for documentation
• DO NOT use any type in TypeScript — use proper types or unknown
• ALWAYS run {package_manager} run build before committing to verify no errors

### Step 3: Create .cursorrules

```markdown
# {Project Name} — Cursor Rules

## Code Style
- Use {detected naming convention}
- Prefer {detected import style}
- {Framework-specific: e.g., "Use Server Components by default in Next.js App Router"}
- {Error handling: e.g., "Always use try/catch, never silently swallow errors"}

## File Organization
- New pages go in `app/{route}/page.tsx`
- Shared components go in `components/`
- Utility functions go in `lib/`
- API routes go in `app/api/{route}/route.ts`

## Do NOT
- Use `var` — use `const` or `let`
- Use `any` type — use proper types
- Put business logic in components — extract to `lib/`
- Commit without building first

Step 4: Verify Agent Config Works

Test by asking the agent: "What tech stack does this project use?"

• If agent answers correctly from AGENTS.md: ✅ working
• If agent reads source files instead: ⚠️ AGENTS.md may need more specificity

Output Format

## 🤖 AI-Readiness Report

### Files Created
| File | Purpose | Size |
|------|---------|------|
| `AGENTS.md` | Onboards any AI agent to the codebase (WHAT/WHY/HOW) | {N} lines |
| `.cursorrules` | Code style + framework rules for Cursor IDE | {N} lines |
| `.cursor/rules/{name}.mdc` | Scoped rules for specific directories | {N} lines |

### What Each File Teaches the Agent
- **AGENTS.md:** Tech stack ({stack}), commands ({N} scripts), structure ({N} directories), conventions ({N} rules), boundaries ({N} guardrails)
- **.cursorrules:** Code style ({N} rules), file organization ({N} patterns), anti-patterns ({N} "Do NOTs")

### Verification
- [x] AGENTS.md covers WHAT/WHY/HOW
- [x] Only universally-applicable instructions included (per HumanLayer best practice)
- [x] Commands listed early (per GitHub AGENTS.md analysis)
- [x] Boundaries set (what NOT to do)
- [ ] Test: Ask agent "What tech stack does this project use?" → should answer from AGENTS.md