Code alone doesn’t tell the whole story. To truly understand a project, an AI assistant needs access to the same documentation a human developer would: API references, architectural diagrams, product requirements, and style guides. Treating your documentation as a first-class source of context is a superpower for AI-assisted development.
This guide explores how to effectively use both internal and external documentation to guide your AI partner.
Using documentation with an AI assistant creates a powerful feedback loop:
Docs as Input: You provide existing documentation (e.g., a PRD, a library’s API reference) as context for a coding task.
AI Generates Code: The AI uses the documentation to generate code that is consistent with the project’s requirements and external dependencies.
AI Generates Docs: You then ask the AI to generate or update the documentation for the new code it just wrote (e.g., creating a README.md or adding JSDoc comments).
New Docs as Input: This newly generated documentation becomes a context source for the next development task.
By integrating the AI into your documentation workflow, you ensure that your docs stay up-to-date and continuously serve as an accurate source of truth for both human and AI developers.
This is the knowledge specific to your project and organization. It’s the most critical context because the AI has no other way of knowing it.
PRDs and Specifications: Keep them in your repo (/docs/prd.md) and reference them with @.
Architectural Decision Records (ADRs): Explain the why behind your technical choices.
READMEs: Co-locate README.md files with complex modules to provide a quick overview.
Style Guides: Codify your team’s conventions in a document the AI can reference.
External Documentation
Framework and library documentation provides the rules for how to interact with third-party code. Models have a knowledge cutoff date, so providing up-to-date docs is crucial.
Cursor’s @Docs: Use @Docs to pull in official, up-to-date documentation for popular libraries and frameworks.
Cursor’s @Web: For very recent or community-driven information (like blog posts or GitHub issues), use @Web to perform a live search.
Manual Pasting: You can always copy-paste a URL or text from any documentation source directly into the chat.
When you start working on a new project, your first step is often to read the documentation. The same applies to your AI assistant. Before starting a complex task, you can prime the AI by asking it to:
Summarize the key architectural patterns described in @/docs/architecture.md and the main user flows from @/docs/prd.md.
This builds a shared understanding and ensures the AI’s subsequent work is aligned with the project’s core principles.
Instead of manually translating a Product Requirements Document into code, let the AI do the heavy lifting.
Implement the "User Profile V2" feature as described in @/docs/prd.md#user-profile-v2. Pay close attention to the acceptance criteria. Use the existing components in @/src/components/profile/.
By referencing the PRD and existing code, you provide both the intent context (what to build) and the state context (what to build it with).