172 lines
6.4 KiB
Markdown
172 lines
6.4 KiB
Markdown
# Prompts — Meta
|
|
|
|
> **Purpose:** Reusable prompt templates and working methodology for LLM-assisted development on Lila. Use these as preambles when starting a new task with any LLM.
|
|
> **Last updated:** 2026-05-15
|
|
|
|
---
|
|
|
|
## Working Methodology
|
|
|
|
This project is a learning exercise. The goal is to understand the code, not just to ship it.
|
|
|
|
### How to use an LLM for help
|
|
|
|
1. **Paste the relevant AI-context files as context** (00-project-overview.md + domain files + 99-current-task.md)
|
|
2. **Describe what you're working on and what you're stuck on**
|
|
3. **Ask for hints and explanations, not raw solutions** — understand the concept, then implement it yourself
|
|
4. **After completing a task, ask the LLM what docs need updating**
|
|
|
|
### Refactoring workflow
|
|
|
|
After completing a task: share the code, ask what to refactor and why. The LLM should explain the concept, not write the implementation.
|
|
|
|
---
|
|
|
|
## Base Prompt Template
|
|
|
|
Use this as the opening when starting any task with an LLM:
|
|
|
|
```
|
|
I'm working on Lila, a vocabulary learning app. Here's the project context:
|
|
|
|
[PASTE: 00-project-overview.md]
|
|
[PASTE: relevant domain file(s) from ai-context/]
|
|
|
|
My current task: [describe what you're building or fixing]
|
|
|
|
Please follow these rules:
|
|
|
|
1. Tell me which files you need to see to get the full context of the problem.
|
|
Do not assume you know the codebase — ask for files.
|
|
|
|
2. Walk me text-only through the problem and the solution.
|
|
Explain the concept before showing code.
|
|
|
|
3. If we need to update multiple files, let's go through them one by one,
|
|
no matter how many files there are.
|
|
|
|
4. If we go through a file, we'll do it slowly section by section,
|
|
no matter how many sections.
|
|
|
|
5. Suggest a feature branch name. Tell me when it's time to git commit
|
|
and provide a commit message.
|
|
|
|
6. If we have multiple options, provide options that reflect current
|
|
industry standards and best practices. Explain the trade-offs.
|
|
|
|
7. Never assume anything. Always ask for clarification if uncertain.
|
|
|
|
8. For every completed task, tell me which documentation files need updates.
|
|
Use this format:
|
|
- FILE: [filename] — REASON: [what changed and why the doc needs updating]
|
|
|
|
Let's start.
|
|
```
|
|
|
|
---
|
|
|
|
## Task-Specific Prompt Templates
|
|
|
|
### Generate a Feature
|
|
|
|
```
|
|
[Base prompt template above]
|
|
|
|
Additional context:
|
|
- This is a [feature/bugfix/refactor] task
|
|
- It touches these areas: [frontend/backend/database/websocket/pipeline]
|
|
- The user-facing behavior should be: [describe]
|
|
- Technical constraints: [e.g., must work with existing Zod schemas, must not break WebSocket protocol]
|
|
```
|
|
|
|
### Review Code for Bugs
|
|
|
|
```
|
|
[Base prompt template above]
|
|
|
|
Additional context:
|
|
- I'm seeing this symptom: [error message, unexpected behavior]
|
|
- It happens when: [reproduction steps]
|
|
- I've checked these files already: [list]
|
|
- Focus on: [race conditions, null handling, async flow, type safety, etc.]
|
|
```
|
|
|
|
### Generate Tests
|
|
|
|
```
|
|
[Base prompt template above]
|
|
|
|
Additional context:
|
|
- Test type: [unit/integration/e2e]
|
|
- What to test: [function/component/endpoint]
|
|
- Current test coverage: [none/existing but incomplete]
|
|
- Mocking strategy: [mock DB/mock WS/mock auth]
|
|
```
|
|
|
|
### Debug an Issue
|
|
|
|
```
|
|
[Base prompt template above]
|
|
|
|
Additional context:
|
|
- Error message: [paste full error]
|
|
- Stack trace: [paste if available]
|
|
- Recent changes: [what was modified before it broke]
|
|
- Environment: [dev/production/local/CI]
|
|
```
|
|
|
|
---
|
|
|
|
## Post-Work Doc Update Checklist
|
|
|
|
After completing any task, the LLM should check these files for needed updates:
|
|
|
|
| File | Check if... |
|
|
| ---------------------------------- | ----------------------------------------------------------------------- |
|
|
| `documentation/STATUS.md` | Task changes what's working or what's blocked |
|
|
| `documentation/BACKLOG.md` | Task completes a backlog item or creates a new one |
|
|
| `documentation/DECISIONS.md` | Task involved choosing between alternatives with long-term consequences |
|
|
| `documentation/ARCHITECTURE.md` | Task changes monorepo structure, data flow, or layer boundaries |
|
|
| `documentation/ai-context/*.md` | Task changes schemas, endpoints, protocol, or pipeline stages |
|
|
| `packages/shared/src/schemas/*.ts` | Task changes request/response shapes or WS message types |
|
|
| `README.md` | Task changes quickstart steps, stack, or current status |
|
|
|
|
**Format for doc updates:**
|
|
|
|
```
|
|
- FILE: documentation/STATUS.md — REASON: Guest play flow is now live, update "What Works Today"
|
|
- FILE: documentation/ai-context/03-api-contract.md — REASON: New endpoint POST /api/v1/game/guest-start added
|
|
- FILE: packages/shared/src/schemas/game.ts — REASON: Added GuestGameRequestSchema
|
|
```
|
|
|
|
---
|
|
|
|
## Ticket File Convention
|
|
|
|
For completed tasks, produce a ticket file in `documentation/tickets/`:
|
|
|
|
| Prefix | Use when... | Example |
|
|
| -------- | ---------------------------------------------------- | ----------------------------------- |
|
|
| `adr-` | Decision between options with long-term consequences | `adr-websocket-library.md` |
|
|
| `feat-` | New feature shipped | `feat-guest-play.md` |
|
|
| `fix-` | Bug fixed | `fix-race-condition-lobby-join.md` |
|
|
| `chore-` | Routine maintenance, refactoring, tooling | `chore-batch-distractor-queries.md` |
|
|
|
|
**Ticket contents:**
|
|
|
|
- What was done (summary)
|
|
- Why it was needed (context)
|
|
- What files changed (list)
|
|
- Any follow-up work (notes)
|
|
- Setup guide if applicable (how to verify it works)
|
|
|
|
---
|
|
|
|
## Tips for Effective LLM Collaboration
|
|
|
|
1. **Start small.** Give the LLM one file or one function at a time, not the whole codebase.
|
|
2. **Verify assumptions.** If the LLM assumes something about your stack, correct it immediately — wrong assumptions compound.
|
|
3. **Ask for alternatives.** "What's the simplest way to do this?" vs. "What's the most robust way?" often yield different answers.
|
|
4. **Don't accept code you don't understand.** Ask the LLM to explain a line until you do.
|
|
5. **Test everything.** The LLM can suggest tests, but you run them. Trust nothing until it passes.
|
|
6. **Keep context fresh.** If a conversation gets long, start a new one with the base prompt + current task template.
|