Having recently implemented a Windsurf-based workflow for my team, I encountered a persistent friction point: the disconnect between our core application code and the sprawling, often ambiguous, product specifications living in various company documents. While Windsurf excels at leveraging the immediate codebase context, its suggestions for new features or major refactors would occasionally miss crucial business logic or domain-specific constraints defined outside the repository.
This led me to investigate the "Custom Retrieval" feature as a potential solution for grounding Windsurf's outputs in our company's proprietary knowledge. The hypothesis was that by integrating our internal API docs, product requirement documents (PRDs), and architecture decision records (ADRs), we could significantly improve the functional accuracy of generated code, moving it closer to "correct by specification" on the first attempt.
The configuration process is straightforward but requires careful curation of source material. I began by creating a dedicated directory, `company_knowledge/`, within our monorepo. This directory houses only non-code, Markdown-formatted documents, as this format yields the best retrieval results. The structure is flat, with descriptive filenames.
```
company_knowledge/
├── product_prd__event_priority_rules.md
├── api_spec__internal_service_x_v2.md
├── adr_004_ message_delivery_guarantees.md
└── glossary_domain_terms.md
```
The critical step is the `windsurf.json` configuration. Here, you must explicitly enable and define the retrieval sources. Note the use of glob patterns to target the knowledge directory, while carefully excluding any actual source code to avoid context pollution.
```json
{
"customRetrieval": {
"enabled": true,
"sources": [
{
"type": "file",
"path": "company_knowledge/**/*.md",
"exclude": ["**/node_modules/**", "src/**", "lib/**"]
}
]
}
}
```
The operational impact is subtle but measurable. When I now open a file related to our event-processing pipeline and prompt Windsurf with "Implement the priority enqueuing logic for the Order events," the suggestions are notably more precise. Instead of generating a generic priority queue, it references the specific three-tier priority model (CustomerImpact, Financial, Operational) defined in `event_priority_rules.md` and incorporates the idempotency key requirement noted in the API spec. The suggestions include inline comments referencing the relevant document, which is a significant boost for traceability.
However, several pitfalls emerged during testing:
* **Document Quality is Paramount:** Poorly structured or overly verbose documents lead to noisy retrievals. I found pre-processing documents to be concise, single-topic pages drastically improved relevance.
* **No Real-Time Indexing:** Changes to the knowledge base files are not detected until the Windsurf VS Code extension is reloaded. This necessitates a manual reload after significant documentation updates.
* **Context Window Consideration:** The retrieved text consumes part of the precious context window. Overloading the knowledge base with every company document can crowd out relevant code context, creating a diminishing return.
In conclusion, this feature transforms Windsurf from a powerful generic autopilot into a more informed team member. It does not replace the need for developer oversight, but it substantially reduces the back-and-forth correction cycle for business logic. The key to success lies in maintaining a curated, well-structured, and concise knowledge corpus. The integration has now become a standard part of our onboarding repository setup.
testing all the things
throughput first