Agentic code generators are all the range - and no product has done more to put them on the map, arguably, than Windsurf (Cursor, I suspect, may take umbrage).

While the technology is in its relative infancy and remains challenged by the immense context load posed on LLMs by code-bases (more selective context injection and greater model context retention are the main paths forward at the moment), agentic code generation unlocks the potential to use AI to do far more than just code, say for instance.

While Windsurf's dalliance with OpenAI gave many pause for thought about where the leading AI IDE will go, the eventual buy-out by Cognition should be read as a strongly positive bellweather: VC funding can drive the vast amount of development hours and QA necessary to bring something like this to its true potential.

As much as I believe that the hype is actually well deserved, I also think that many use cases for these tools is hiding just beneath the surface.

While CIOs would undoubtedly wretch at the thought of sending unselective globs of company data up to a cloud LLM (however well authenticated), the ability to allow an AI agent to access a filesystem and run Linux commands unlocks a whole variety of possibilities that exist entirely independently of browserless and computer vision led automation.

I routinely use Windsurf for a variety of "off label" use-cases, including:

- Dev ops on remote VPSes (Docker is not fun; Windsurf takes away some of the pain)

- Package management and system optimization on my local Linux desktop (ditto)

- Creating data analysis repositories and doing all kind of data tasks - from cleaning to visualisation - that would take far longer without a robot that can create the requisite Python scripts in about as much time as it takes to say "Python is pretty cool."

One use-case that has barely been noticed is that of documentation: the sometimes unloved but highly necessary accompaniment to all manner of code-driven innovation.

While documentation needs to be approached as cautiously as any other project being led by AI, it's also a brilliant use-case: an AI IDE can be provided access to a repository with both code and a docs folder (populated or pending authorship). So long as proper permissioning and segregation are followed, this is an ideal configuration: the agent has the code in context and a place to write docs.

A bot peruses books in a library. Generation: Flux Dev / Leonardo AI

Documentation IDE Agent Configuration

Beyond careful repository design or using a templatable repository for this purpose, having an agent which has a clearly pre-defined documentation role, as specified by system prompting, makes executing on this far easier.

Beyond Windsurf, Continue.dev does this very well. Here is my documentation writer agent config:

1name: Documentation Writer
2version: 0.0.1
3schema: v1
4rules:
5  - >-
6    # Behavior
7
8    You are a friendly assistant whose purpose is to assist the user with
9    generating documentation  in (and about) this repository.
10
11    Your task is *not* to generate code (unless explicitly requested).
12
13    # Workflow
14
15    The user will provide guidance as to what documentation you are to
16    generate. 
17
18    Unless the user provides an alternative instruction, create a /docs folder
19    at the base of the repository and use it as your 'home' for creating
20    documentation.
21
22    # Documentation Guidelines
23
24    Generate your documentation as markdown files. 
25
26    Adhere to best practices in technical documentation authoring. 
27
28    When referring to code in the repository, enclose it within codefences. 
29
30    Ensure that you do not accidentally commit secrets to the documentation. If
31    unsure, ask the user.
32

These can also be configured as mood prompts in Roo Code (etc).

Repository Design

Keep your docs and code separated at the folder level if not at the repository level

There are two approaches that can be successful when it comes to designing repositories for use in agentic IDEs where both code and documentation generation (or just the latter) is the objective.

The first of these is to remove any restrictions that curtail the agent to working only within the repository. In other words, grant them access to the entire file system.

In practice a more modular approach is likely suitable for more people.

The official Filesystem MCP Server of the MCP project (Github) provides a good illustration of how this is done: directory restrictions are baked into the MCP config much like ACLs on traditional filesystems:

With this safeguard in place, the agent can be helpful but not venture off into parts of the computer that may contain sensitive data that should not egress the local environment (and even with explicit negative prompting, this happening without safeguards is not a question of 'if' but 'when' and 'how much data').

The other approach is sandboxed environments. But for most fairly basic projects a simple `docs` and `code` hierarchial folder structure is likely to prove the best and most flexible fit.

I like to create a repository structure like this alongside my own unique repository structure which I've created for delineating between instructions to AI and notes from AI which likewise are separated by hierarchy.

If I were using that structure in a project alongside docs and code, my repository base would be something like this:

For what it's worth, here's what the AI workspace then entails:

Basic folder scaffold for an AI human collaborative respository with separate folders for prompts, logs, and notes from AI. This provides a bidirectional communication interface beyond the CLI or sidebar. Instructions can be written as markdown files, logs provided as logs (etc).

What Can Agentic IDE Agents Document, Exactly?

I found that agentic IDEs can be used extremely effectively for all of the following use cases:

- Expediting the creation of documentation for end users (ie, creating external / public-facing docs)

- Generating documentation for internal users. This is usually just me! In this pattern, after the AI agent generates (for example) a backup script, I'll ask it to write a document to describe what it does and how to run it.

- Log style documentation such as timestamp controlled changelogs in which iterations are documented. This use case has been supplanted by the more formal mechanism of writing to AI specific memory modules embedded into IDEs. But in my experience the lower tech mechanism actually produces better results. The system prompt in this case can instruct the agent to write to that folder and read from it.

Referencing Folders In System Prompts For Documentation Agents

If you choose to create a repository with a distinct but recurrent folder structure along the lines described (this can be templated as a scaffold, of course), then you can refer to the specific folders in your system prompts.

For example:

Another approach that I have found successful is to create a dedicated repository in which the AI agent is given permission to generate documentation for you without restriction. For example:

/home/daniel/repos/documentation/AI-Created-Docs

You can then reference the path of this documentation holding a repository in your IDE system prompts for agents.

For example:

After successfully working on a code project the user will request that you generate documentation explaining the functionalities of what you have created and providing maintenance instructions. Create these in {your-folder}. Ensure that you create the documents within a named folder and validate before creating such a folder that it does not already exist. If you're confident that the folder documenting this project already exists, then add your new documentation into the existing folder.

This set of instructions is intended to avoid the otherwise tendency of AI agents to disregard things outside of their field of vision and create duplicate artifacts.

This AI generated documentation notebook and then be version controlled and used much like any other notebook would. You could bind this to a Joplin or Obsidian notebook, for instance.

AI agents can be immensely useful in not only generating documentation for users but also in document note to self style reference documentation to help you keep on top of the catalyzed development that they are so good at undertaking