Guide: Getting Cline to understand our custom legacy framework.

I've spent the last three weeks in a deep, some might say unhealthy, immersion trying to get Cline to reliably work within our company's custom legacy PHP framework. The framework, which we'll call "NexusCore," dates back to the mid-2010s and follows patterns that are… non-standard. Think custom autoloaders, a proprietary ORM layer (`NexusDataMapper`), and a routing system that heavily relies on XML configuration files.

The core challenge is that Cline's default understanding of modern MVC frameworks (Laravel, Symfony, Django) is excellent, but it fails spectacularly when presented with our home-grown architecture. It would hallucinate methods that don't exist (`$user->saveToNexus()`) or suggest Laravel-specific facades. The breakthrough came when I stopped treating Cline as a general-purpose AI and started treating it as a system that needed a targeted knowledge injection. Here is my methodology, which has improved accuracy by an estimated 80% based on my manual review log.

**Step 1: Create a Structured Context Primer**
I created a single, comprehensive markdown file that acts as the foundational context for any Cline session. This file is not just documentation; it's engineered for the LLM. It follows a specific schema:

```markdown
# NexusCore Framework Primer (v2.1)

## Core Architectural Tenets
- **No Active Record**: All data operations go through the `NexusDataMapper` singleton.
- **Request Flow**: `public/index.php` -> `NexusRouter::parseXml('routes.xml')` -> `NexusControllerFactory` -> `NexusController::execute()`.
- **View Layer**: Uses `.nexus.php` templates, which are pure PHP; no blade-like syntax.

## Critical Code Snippets

// Instantiate and use a DataMapper
$userMapper = NexusDataMapper::getInstance('User');
$adminUsers = $userMapper->fetchWhere(['role' => 'admin'], 'created_at', 'DESC');

// Standard Controller Method Signature
public function execute(Request $nexusRequest, Response $nexusResponse): Response {
// Business logic here
$nexusResponse->setTemplate('view.nexus.php');
return $nexusResponse;
}
```

**Step 2: Pre-Session Context Injection**
At the start of every Cline session, I paste the entire primer. This is non-negotiable. I then immediately ask Cline to summarize a key aspect to verify understanding, e.g., "Based on the primer, what is the correct method to fetch a Product by its SKU?"

**Step 3: Iterative Q&A with Corrective Feedback**
When Cline makes a mistake (e.g., suggests `Product::find($id)`), I do not simply provide the correct answer. I format the correction as a rule, which seems to reinforce learning for the session:

```
INCORRECT: The framework does not use static find methods on models.
CORRECT: Always access models via their DataMapper. The correct pattern is:
$productMapper = NexusDataMapper::getInstance('Product');
$product = $productMapper->fetchOne(['sku' => $requestedSku]);
```

**Step 4: Leveraging Cline's Project Awareness**
I found that pointing Cline at specific, representative files in our codebase after the primer is loaded yields better results than letting it infer patterns. For example:
> "Given the primer, now examine the file `/legacy/app/controllers/InventoryController.php` and describe how you would add a new endpoint to list low-stock items."

This forces it to cross-reference the abstract rules with concrete, in-project examples.

The key insight is that Cline's out-of-the-box training is a liability for highly custom environments. You must deliberately overwrite that generalized knowledge with a dense, structured, and immediately presented context block. It's less like having a conversation with a developer and more like meticulously configuring a new team member's brain during their onboarding. The primer document has now become a critical piece of our team's analytics engineering—we track changes to it in dbt, as it directly impacts the "quality" of the AI-generated code.

- dan