Creating and Using a Guidelines File
A guidelines file is one of the most powerful ways to enhance BB's effectiveness for your project. It provides your LLM with essential context, constraints, and goals that help focus your conversations and deliver more relevant, aligned results.
What is a Guidelines File?
A guidelines file is a structured document that provides your LLM with context about your project's:
- Purpose and objectives
- Restrictions and guardrails
- Available resources
- File/directory structure
- Tool usage preferences
- Error handling procedures
Why Guidelines Matter
Language models perform best when they have clear context about what they're working on. A well-crafted guidelines file acts as a dedicated "project manual" that helps your LLM:
- Focus on relevance - Understand what matters most for your specific project
- Maintain consistency - Apply the same standards and approaches across conversations
- Respect boundaries - Know what actions or suggestions are off-limits
- Streamline workflows - Make informed decisions about tools and approaches
- Avoid assumptions - Replace guesswork with explicit guidance
Without Guidelines:
Your LLM has to infer project details from limited context in each conversation, potentially misunderstanding your needs or making incorrect assumptions about your project's requirements.
✗ Requires frequent clarification
✗ Inconsistent approach across conversations
✗ May miss project-specific nuances
With Guidelines:
Your LLM understands your project's purpose, structure, and requirements upfront, allowing for focused, consistent interactions aligned with your specific needs and constraints.
✓ Immediately understands project context
✓ Maintains consistency across conversations
✓ Anticipates project-specific requirements
How to Write an Effective Guidelines File
Required Sections
Every guidelines file should include these core sections:
1. Project Purpose and Scope
Define what your project aims to accomplish, its boundaries, and expected outcomes.
Good Example:
This project processes customer transaction data to:
Generate monthly sales reports by region and product category, identify trending products using ML-based analysis, and alert on suspicious transaction patterns.
Key requirements:
- 99.9% accuracy,
- real-time processing,
- PII handling.
2. Restrictions and Guardrails
Outline security requirements, privacy considerations, data handling rules, and tool usage restrictions.
Good Example:
Data Security Requirements:
1. All PII must be encrypted using project's encryption module.
2. Access patterns:
Read from: raw-data/ directory only,
Write to: processed-data/ directory only.
3. Validation:
- Verify data format against schemas/customer-data.json,
- Report validation errors with line numbers,
- Never modify raw data files.
3. Available Resources
Describe project files and structure, external resources, access methods, and authentication requirements.
Good Example:
External Data Sources:
1. Customer Verification API
- Endpoint: https://api.verify.example.com/v2,
- Authentication: Bearer token (obtain via run_command get-api-token), Rate limits: 100 requests/minute.
2. Product Database
- Access: read-only PostgreSQL connection,
- Authentication: Database credentials in .env file.
Optional Sections
Based on your project needs, consider including:
- File/Directory Structure - Naming conventions, organization requirements, special file handling instructions
- Tool Usage Guidelines - Commonly used tools, special considerations, example usage patterns
- Error Handling - How to handle incomplete information, dealing with resource unavailability, validation requirements
- Common Project Types - Specific guidance for data analysis, coding, research, or content creation aspects of your project
Common Guidelines Mistakes to Avoid
1. Vague Instructions
BAD:
"Handle errors appropriately"
GOOD:
"Log all errors to errors.log with timestamp, function name, and full stack trace"
2. Implicit Assumptions
BAD:
"Process the files in the usual way"
GOOD:
"Process files in order by timestamp, oldest first, using process_data.py script"
3. Missing Context
BAD:
"Use standard validation"
GOOD:
"Validate all inputs using validation/rules.json schema, which checks required fields presence, data type correctness, value range constraints, and format patterns"
4. Unclear Boundaries
BAD:
"Don't modify important files"
GOOD:
"Read-only files (never modify): config/*.json, templates/*, raw-data/*"
Configuring Your Project to Use Guidelines
Step 1: Create Your Guidelines File
There are two ways to create your guidelines file:
Option A: Have BB Create It For You (Recommended)
The easiest approach is to ask BB to create the guidelines file for you:
Example Prompt:
I'd like you to help me create a guidelines file for this project. This file will provide context and focus for future conversations. Please interview me about my project to gather the necessary information, then create a well-structured guidelines.md file.
Include the following sections:
- Project Purpose and Scope
- Restrictions and Guardrails
- Available Resources
- File/Directory Structure (if relevant)
- Tool Usage Guidelines (if relevant)
- Error Handling procedures (if needed)
Please format it with proper markdown, including a YAML frontmatter with version, creation date, and purpose.
BB will interview you with targeted questions about your project's goals, resources, restrictions, and requirements, then use that information to create a comprehensive guidelines file tailored to your project.
Option B: Create It Manually
- Create a new Markdown (.md) file in your project directory
- Name it descriptively (e.g.,
guidelines.md,project-guidelines.md) - Add the required sections as described above
- Save the file in your project's root directory
Pro Tip: Consider using YAML or JSON frontmatter at the top of your guidelines file to include metadata like version, creation date, and purpose.
Step 2: Configure Project Settings
- Go to Projects in navigation panel in BB
- Click on the Edit icon next to your project in the Project Manager
- Locate the LLM Guidelines File field
- Enter the name of your guidelines file (the field features auto-complete to help you select the correct file)
- Click Save to apply the changes
Step 3: Verify Configuration
To confirm your guidelines file is properly configured and being used by your LLM:
- Start a new conversation with BB
- Ask your LLM to summarize the project guidelines
- Check that your LLM's response accurately reflects your guidelines file content
Pro Tip: When starting a new conversation, your LLM will automatically have access to your guidelines file. You don't need to explicitly share it in each conversation.
Updating Guidelines
As your project evolves, you may need to update your guidelines file. After making changes:
- Save the updated guidelines file
- Start a new conversation to use the updated guidelines
- Existing conversations will continue using the guidelines version from when they were started
Guidelines Examples for Different Project Types
Development Projects
Guidelines examples for software development, focusing on code standards, testing requirements, and deployment workflows.
Research Projects
Guidelines examples for academic research, including literature review, data analysis, and manuscript preparation.
Content Projects
Guidelines examples for content creation, blog writing, marketing materials, and multi-channel publishing.
Data Analysis Projects
Guidelines examples for data analysis, visualization, and reporting workflows.
Next Steps
Last updated: April 10, 2025