preflight: scaffold + context files
This commit is contained in:
@@ -0,0 +1,168 @@
|
||||
# Freshness Rules for LiveKit Development
|
||||
|
||||
This document provides detailed guidance on maintaining accuracy when building with LiveKit Agents. These rules exist because model training data becomes outdated immediately, and LiveKit's SDK evolves rapidly.
|
||||
|
||||
## The Core Problem
|
||||
|
||||
Coding agents (Claude, GPT, etc.) are trained on historical data. This training includes:
|
||||
- Old versions of LiveKit documentation
|
||||
- Outdated code examples from blogs and tutorials
|
||||
- Previous SDK versions with different APIs
|
||||
- Community answers that may no longer be accurate
|
||||
|
||||
When an agent "knows" something about LiveKit, that knowledge may be months or years out of date.
|
||||
|
||||
## Verification Requirements
|
||||
|
||||
### Before Writing Any LiveKit Code
|
||||
|
||||
1. **Identify what needs verification**
|
||||
- Method names and signatures
|
||||
- Configuration options and their types
|
||||
- Import paths and module structure
|
||||
- Default values and behaviors
|
||||
|
||||
2. **Query the documentation**
|
||||
- Use MCP to search for the specific feature
|
||||
- Read the current documentation, not cached knowledge
|
||||
- Look for version notes or recent changes
|
||||
|
||||
3. **Cite your source**
|
||||
- Note which documentation page informed the implementation
|
||||
- If something cannot be verified, explicitly state this
|
||||
|
||||
### During Implementation
|
||||
|
||||
When writing code, verify:
|
||||
|
||||
| Element | Why It Changes | How to Verify |
|
||||
|---------|----------------|---------------|
|
||||
| Import statements | Module restructuring | Search docs for current import paths |
|
||||
| Method signatures | API evolution | Look up method in API reference |
|
||||
| Configuration keys | Naming conventions change | Check configuration documentation |
|
||||
| Default behaviors | Defaults are tuned over time | Read parameter documentation |
|
||||
| Event names | Event systems evolve | Check events/callbacks documentation |
|
||||
|
||||
### After Implementation
|
||||
|
||||
Before presenting code to the user:
|
||||
- Confirm all APIs used are documented
|
||||
- Verify example patterns match current best practices
|
||||
- Check for deprecation warnings in documentation
|
||||
|
||||
## What Cannot Be Verified
|
||||
|
||||
Some things legitimately cannot be verified against documentation:
|
||||
- User's specific environment or configuration
|
||||
- Integration with user's existing codebase
|
||||
- Business logic and application requirements
|
||||
|
||||
When providing guidance on these topics, clearly distinguish between:
|
||||
- "According to LiveKit documentation..." (verified)
|
||||
- "Based on your requirements..." (application-specific)
|
||||
- "This may need adjustment..." (uncertain)
|
||||
|
||||
## Red Flags: When to Stop and Verify
|
||||
|
||||
Pause and verify against documentation when:
|
||||
|
||||
1. **Writing from memory** - If you're typing an API call without having just looked it up, verify it
|
||||
2. **"I think" or "I believe"** - Uncertainty about LiveKit APIs requires verification
|
||||
3. **Complex configurations** - Multi-option configurations are likely to have evolved
|
||||
4. **Error handling** - Exception types and error formats change
|
||||
5. **Newer features** - Recently added features have the highest drift risk
|
||||
|
||||
## Communication with Users
|
||||
|
||||
### When Verified
|
||||
|
||||
```
|
||||
According to the LiveKit Agents documentation, the correct approach is...
|
||||
[implementation]
|
||||
```
|
||||
|
||||
### When Partially Verified
|
||||
|
||||
```
|
||||
The workflow structure follows LiveKit's documented patterns. However, I could not
|
||||
verify [specific detail] against current documentation. Please confirm this matches
|
||||
your SDK version.
|
||||
```
|
||||
|
||||
### When Unverified
|
||||
|
||||
```
|
||||
I cannot verify this implementation against current LiveKit documentation. This is
|
||||
based on general patterns and may require adjustment. I recommend:
|
||||
1. Checking the official documentation at [link]
|
||||
2. Testing this implementation before relying on it
|
||||
```
|
||||
|
||||
## MCP Server Unavailable
|
||||
|
||||
If the LiveKit MCP server is not installed or accessible:
|
||||
|
||||
1. **Inform the user immediately** - They should know verification isn't possible
|
||||
2. **Recommend installation** - Point to https://docs.livekit.io/mcp
|
||||
3. **Proceed with caution** - Clearly mark all LiveKit-specific code as unverified
|
||||
4. **Suggest manual verification** - User should check docs before using the code
|
||||
|
||||
Do not pretend to have verified something when MCP access was unavailable.
|
||||
|
||||
## Version Awareness
|
||||
|
||||
LiveKit Agents has distinct versions with potentially different APIs:
|
||||
- Python SDK (`livekit-agents`)
|
||||
- Node.js/TypeScript SDK (`@livekit/agents`)
|
||||
|
||||
Each has its own release cycle and API surface. When working with LiveKit:
|
||||
- Determine which SDK the user is using
|
||||
- Search documentation specific to that SDK
|
||||
- Do not assume API parity between Python and Node.js versions
|
||||
|
||||
## Examples of Drift
|
||||
|
||||
These examples illustrate why verification matters:
|
||||
|
||||
### Configuration Changes
|
||||
Old tutorials might show:
|
||||
```python
|
||||
agent = VoiceAgent(config={"model": "gpt-4"})
|
||||
```
|
||||
|
||||
Current API might be:
|
||||
```python
|
||||
agent = VoiceAgent(llm=SomeLLMClass(...))
|
||||
```
|
||||
|
||||
### Method Renames
|
||||
What was once:
|
||||
```python
|
||||
agent.start_session()
|
||||
```
|
||||
|
||||
Might now be:
|
||||
```python
|
||||
agent.start()
|
||||
```
|
||||
|
||||
### Import Restructuring
|
||||
Previous:
|
||||
```python
|
||||
from livekit.agents.voice import VoiceAgent
|
||||
```
|
||||
|
||||
Current:
|
||||
```python
|
||||
from livekit.agents import VoiceAgent
|
||||
```
|
||||
|
||||
None of these changes are predictable from training data. Only live documentation reflects current state.
|
||||
|
||||
## Summary
|
||||
|
||||
1. **Default to distrust** - Assume any LiveKit knowledge from memory is outdated
|
||||
2. **Verify actively** - Use MCP to check documentation before implementation
|
||||
3. **Communicate uncertainty** - Tell users when something cannot be verified
|
||||
4. **Cite sources** - Reference documentation when providing verified information
|
||||
5. **Recommend MCP** - If unavailable, make installation a priority
|
||||
Reference in New Issue
Block a user