Skip to main content

AI-Ready Documentation

The Partner Well-Architected Framework is built from the ground up to work seamlessly with AI development tools. This means you can use AI assistants like Claude, Cursor, Copilot, or ChatGPT to quickly find information, generate code examples, and accelerate your integration work.

What Makes Documentation AI-Ready?​

AI-ready documentation is structured, contextual, and machine-readable while remaining human-friendly. The PWAF includes:

  • llms.txt — Complete site map with all sections, pages, and partner-type context
  • ai-context.txt — Structured guidance on partner roles, requirements, and cross-cutting topics
  • Partner-type aware prompts — AI assistants receive customized context based on your current section
  • Consistent structure — Predictable patterns with clear headings, tables, code examples, and cross-references
  • Rich metadata — Every page includes frontmatter with title, description, hierarchy, and tags
  • Working code examples — Real API calls, SQL queries, CLI commands, and configuration templates

How to Use AI Tools with This Documentation​

Using Claude, ChatGPT, or Gemini​

Use the AI Assistant Button Every page has an "AI Assistant" dropdown button that provides quick access to popular AI tools:

  • Claude - Opens Claude.ai with a pre-loaded prompt containing the current page URL, full site context, partner-type guidance, and key auth resources
  • ChatGPT - Opens ChatGPT with similar context-rich prompts
  • Gemini - Copies the prompt to your clipboard (since Gemini doesn't support URL-based prompts), then opens Gemini.google.com where you can paste it
  • Cursor - Copies the prompt to clipboard for pasting into Cursor's chat or composer

Share Page Links Directly You can also share specific documentation page URLs with your AI assistant:

"Explain this page to me: 
https://databrickslabs.github.io/partner-architecture/built-on/firefly"

Using Cursor​

Copy Prompt for Cursor Click the "AI Assistant" dropdown on any page and select "Cursor". This copies a comprehensive prompt to your clipboard that includes the current page context, partner-type guidance, and links to key resources. Paste this into Cursor's chat or composer to start working with PWAF patterns.

Index the Documentation Add this site to Cursor's documentation index so it can reference PWAF patterns while you code:

  1. Open Cursor Settings → Features → Docs
  2. Add documentation URL: https://databrickslabs.github.io/partner-architecture
  3. Cursor will automatically index the llms.txt file

AI-Optimized Features​

Page Actions​

Every documentation page includes:

  • Copy Link — Share the exact page URL with your AI assistant
  • AI Assistant Dropdown — Quick access to Claude, ChatGPT, Gemini, and Cursor with pre-loaded, context-rich prompts

Partner-Type Aware Prompts​

The AI Assistant generates context-aware prompts based on which section you're in:

  • Connected ISV Partners — Prompts focus on integration patterns, OAuth authentication, JDBC/ODBC drivers, and telemetry
  • Data Collaboration Partners — Prompts emphasize Delta Sharing, recipient management, and Marketplace listings
  • Built-On ISV Partners — Prompts cover workspace models, multi-tenancy, cost management, and SaaS architecture

Each prompt includes:

  • The current page title and URL
  • Full page content for context
  • Partner-type specific guidance and focus areas
  • Direct links to key authentication resources (OAuth M2M/U2M documentation)
  • Reference to the complete site structure (llms.txt)
  • Instructions to stay focused on the current partner type unless you explicitly ask to switch

This ensures AI assistants provide relevant answers tailored to your specific integration or product type.

Structured Context Files​

The PWAF includes two machine-readable context files:

  • llms.txt — Complete site map with hierarchical navigation, page descriptions, and quick-start guides for each partner type
  • ai-context.txt — Structured guidance for AI assistants covering partner roles, requirements, and cross-cutting topics

Firefly Integration​

The Firefly Analytics reference implementation is designed to work seamlessly with AI development tools. Once the source code is publicly available, you'll be able to:

  • Reference well-documented code with clear PWAF patterns
  • Point AI tools at working examples of SSO-SPN authentication, multi-tenant architecture, and embedded Databricks apps
  • Use inline comments that explain PWAF principles in context
  • Accelerate your development by adapting Firefly's patterns to your specific use case

Best Practices for AI-Assisted Development​

Human Oversight Required

While AI assistants can dramatically accelerate development, they are nondeterministic and can produce incorrect or outdated code. Always keep a human in the loop to validate AI-generated solutions.

We recommend an agent-based workflow with explicit planning, implementation, and verification phases:

  1. Plan — Use AI to explore options and draft an approach, then review the plan yourself
  2. Implement — Let AI generate code, but review every change before applying
  3. Verify — Test all AI-generated code, validate against official documentation, and ensure it meets your security and performance requirements

Never blindly trust AI output. AI assistants can hallucinate APIs, use deprecated patterns, or miss critical security considerations. Your expertise and judgment are essential to building production-quality integrations.

Key Best Practices:

  • Start with Context — Give your AI assistant context about your project before asking questions
  • Reference Specific Patterns — Link directly to PWAF patterns when asking for help
  • Iterate with Code Examples — Use PWAF code examples as starting points and ask AI to help you adapt them
  • Validate with Documentation — Always verify AI-generated code against the official PWAF documentation and Databricks docs
  • Combine Multiple Sources — Use PWAF alongside official Databricks documentation for comprehensive guidance

Next Steps​