70 lines
1.8 KiB
Markdown
70 lines
1.8 KiB
Markdown
# The reference.md Pattern
|
|
|
|
Every directory in `references/` must have a `reference.md` file. It's the routing layer that tells the AI what's here and when to go deeper.
|
|
|
|
## Purpose
|
|
|
|
The reference.md file answers three questions:
|
|
1. What knowledge lives in this directory?
|
|
2. When should I read each file?
|
|
3. Do I need to go deeper into subdirectories?
|
|
|
|
## Required sections
|
|
|
|
### What's here
|
|
|
|
A table listing each file/subdirectory with:
|
|
- Name
|
|
- Purpose (one line)
|
|
- When to read it
|
|
|
|
```markdown
|
|
## What's here
|
|
|
|
| File | Purpose | When to read |
|
|
|------|---------|--------------|
|
|
| `foo.md` | Explains X | When doing Y |
|
|
| `bar/` | Details about Z | When you need deep Z knowledge |
|
|
```
|
|
|
|
### When to use this module
|
|
|
|
Brief description of the scenarios where this directory's knowledge applies.
|
|
|
|
### Model guidance
|
|
|
|
Hints about whether cheap or stronger models should handle this content.
|
|
|
|
## Optional sections
|
|
|
|
- **Prerequisites**: What the AI should know/have before reading this
|
|
- **Child topics**: If subdirectories exist, brief descriptions of when to descend
|
|
|
|
## Anti-patterns
|
|
|
|
- Don't duplicate knowledge from child files in reference.md
|
|
- Don't make reference.md longer than ~50 lines
|
|
- Don't skip the "when to read" column - it's the whole point
|
|
|
|
## Example
|
|
|
|
```markdown
|
|
# Authentication References
|
|
|
|
## What's here
|
|
|
|
| File | Purpose | When to read |
|
|
|------|---------|--------------|
|
|
| `oauth-flow.md` | OAuth 2.0 implementation details | When the API uses OAuth |
|
|
| `api-keys.md` | API key authentication patterns | When the API uses simple API keys |
|
|
| `rate-limiting.md` | How to handle rate limits | After auth is working, before production |
|
|
|
|
## When to use this module
|
|
|
|
You're implementing authentication for an API wrapper and need to understand the auth mechanism.
|
|
|
|
## Model guidance
|
|
|
|
Factual/procedural content. Cheap model is fine.
|
|
```
|