Extending Laravel Boost Guidelines: A Better Approach

Hey guys! Let's dive into a common scenario when working with Laravel Boost: extending guidelines without completely replacing them. It’s super useful when you want to add your own twist to the existing rules. We'll break down the issue, explore why it happens, and provide a solid workaround.

The Challenge: Appending Instructions to Existing Guidelines

So, here's the deal: Sometimes, overriding guidelines just doesn't cut it. Imagine you're using Pest for testing in your Laravel project, and you want to add a specific rule after the core Pest rules, without messing with the original setup. A user in our community wanted to add this instruction: "Only write tests if the user explicitly requests you to do so." The goal? To leverage the Pest rules but make test creation conditional.

Now, when they tried creating a custom guideline in .ai/guidelines/testing and running boost:update, the custom guideline ended up at the top of the generated guidelines.md file. But here's the kicker: it seemed to be ignored! The coding agent (in this case, Junie) kept writing tests regardless. The likely reason? The Pest rules, being read later, were taking precedence. This is a classic case of needing a more nuanced approach to guideline management.

Why does this happen? Well, Boost, like many similar tools, processes guidelines in a specific order. If a later rule contradicts an earlier one, the later rule often wins. This is particularly true when the rules are quite specific. So, how do we solve this?

Understanding How Boost Handles Guidelines

Before we jump into solutions, let's quickly understand how Boost handles guidelines. When you run boost:update, Boost typically does the following:

1. Reads Core Guidelines: It starts with its built-in guidelines.
2. Merges Custom Guidelines: It then merges any custom guidelines you've added, usually placing them at the beginning or end based on configuration.
3. Generates guidelines.md: Finally, it generates the guidelines.md file, which the coding agent uses to make decisions.

The order here is crucial. If your custom guideline is meant to extend rather than override, simply placing it at the top might not achieve the desired effect. The agent might still prioritize the more specific, built-in rules.

Solution: Modifying the Original Guidelines (With Caution)

One straightforward approach is to directly modify the original Pest guidelines. However, proceed with caution! Modifying core files can make updates trickier and might lead to conflicts down the road. If you're comfortable with this, here’s how:

1. Locate the Pest Guidelines: Find the relevant Pest guideline file within the Boost directory (usually in the vendor directory if you installed Boost via Composer).
2. Add Your Conditional Logic: Insert your "Only write tests if the user explicitly requests you to do so" instruction within the Pest guideline, ensuring it logically extends the existing rules.

Here's an example of how you might modify a Pest guideline:

**Original Pest Rule:**
- Write comprehensive tests for all new features.

**Modified Pest Rule:**
- Write comprehensive tests for all new features, *unless* the user explicitly requests that tests not be written.
- If the user requests no tests, document the reasons why in the code comments.

By embedding your condition directly into the Pest rule, you ensure it's considered in conjunction with the original rule.

Important: Always back up the original file before making changes! This way, you can easily revert if something goes wrong.

Alternative: Using More Specific Prompts or Directives

Another, often safer, approach involves using more specific prompts or directives when you invoke your coding agent (Junie). Instead of relying solely on the general guidelines, you can provide context-specific instructions.

For example, when you're asking Junie to implement a feature, you could include a directive like:

"Implement this feature. Do not write tests unless explicitly instructed."

This approach has several advantages:

• Non-Invasive: It doesn't require modifying core guideline files.
• Contextual: It allows you to control test creation on a case-by-case basis.
• Clear Intent: It makes your intentions crystal clear to the coding agent.

However, it also requires more manual effort. You need to remember to include the directive each time you want to skip test creation.

Advanced: Custom Rule Processing (If Boost Allows)

Some advanced tools allow you to define custom rule processors. These processors can intercept and modify the standard rule processing logic. If Boost offers this capability (check its documentation), you could create a processor that:

1. Detects Your Custom Guideline: Identifies your "Only write tests if requested" guideline.
2. Modifies the Pest Rules: Dynamically adjusts the Pest rules based on the presence of your custom guideline.

This is a more complex solution, but it offers the most flexibility and control. It allows you to create a truly extensible guideline system without directly modifying core files.

Best Practices for Extending Guidelines

Regardless of the method you choose, here are some best practices to keep in mind:

• Keep it Clear: Ensure your guidelines are clear, concise, and easy to understand. Ambiguous guidelines can lead to unpredictable behavior.
• Be Specific: The more specific your guidelines, the better. Avoid general statements that can be interpreted in multiple ways.
• Test Thoroughly: After making any changes to guidelines, test your coding agent extensively to ensure it's behaving as expected.
• Document Everything: Document your custom guidelines and any modifications you've made to core guidelines. This will help you and your team understand how the system works and troubleshoot issues.
• Version Control: Use version control (like Git) to track changes to your guidelines. This makes it easy to revert to previous versions if needed.

Real-World Example: Implementing a Feature Without Tests

Let's walk through a real-world example using the directive approach. Suppose you want Junie to implement a simple user registration feature, but you don't want to write tests for it (perhaps it's a temporary feature or you're under a tight deadline).

You could use the following prompt:

"Implement a user registration feature with fields for name, email, and password. Do not write tests for this feature."

Junie should then generate the necessary code for the user registration feature without creating any test files. You can always add tests later if needed.

Troubleshooting Common Issues

Here are some common issues you might encounter when extending guidelines and how to troubleshoot them:

• Guidelines Seem to Be Ignored:
  • Check Order: Ensure your guidelines are being processed in the correct order.
  • Specificity: Make sure your guidelines are specific enough to override the default rules.
  • Conflicts: Look for conflicting guidelines that might be canceling each other out.
• Coding Agent Behaves Unexpectedly:
  • Review Guidelines: Carefully review your guidelines to ensure they're clear and unambiguous.
  • Test Cases: Create specific test cases to verify that the coding agent is following your guidelines.
  • Debugging: Use debugging tools (if available) to trace the execution of the coding agent and see how it's interpreting the guidelines.
• Difficulty Modifying Core Guidelines:
  • Backup: Always back up the original file before making changes.
  • Diff Tools: Use diff tools to compare your changes with the original file and identify any unintended modifications.
  • Revert: If something goes wrong, revert to the original file.

Conclusion: Mastering Guideline Extensions

Extending guidelines in Laravel Boost requires a bit of finesse. Whether you choose to modify core files, use specific prompts, or create custom rule processors, understanding how Boost handles guidelines is key. By following the best practices and troubleshooting common issues, you can create a flexible and powerful guideline system that meets your specific needs. Remember, the goal is to guide your coding agent effectively, ensuring it produces code that aligns with your project's requirements and standards. Happy coding, and may your guidelines always lead to cleaner, more efficient code!