Add CLAUDE.md to help developing duckdb extensions with Claude Code

[onnimonni]

Hey,

It seems that many of us like me and @tobilg and @teaguesterling at least are developing new duckdb extensions with great success with Claude Code.

Many internal APIs are not that well documented and it takes forever for Claude to find them.

This is my attempt to save everyone time and help building better and more performant DuckDB extensions by helping LLMS but claude especially to do predicate pushdowns for 3rd party libraries and apis.

For example these instructions helped me to create more natural feeling api integration into Wayback Machine CDX api, Common Crawl Index server and Google programmatic search:
* https://github.com/midwork-finds-jobs/duckdb-web-archive
* https://duckdb.org/community_extensions/extensions/web_search

I assume everyone's better off if these are directly here in the extension template but feel free to close this PR.

[rustyconover]

This seems pretty specialized to me but I like your ideas. Maybe we should build something for AGENTS.md rather than just Claude.

For a lot of my extensions I use something more like this:

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an extension for DuckDB - a C++ based extension.

## Build Commands

### Building
```sh
# Build release version
VCPKG_TOOLCHAIN_PATH=`pwd`/vcpkg/scripts/buildsystems/vcpkg.cmake GEN=ninja make release

# Build debug version
VCPKG_TOOLCHAIN_PATH=`pwd`/vcpkg/scripts/buildsystems/vcpkg.cmake GEN=ninja make debug

# Run all tests (requires building first)
make test              # runs against release build
make test_debug        # runs against debug build
```

All extension functions should be documented inside of DuckDB with CreateScalarFunctionInfo or CreateAggregateFunctionInfo or the appropriate type for the function.  This documentation of the function should include examples, parameter types and parameter names.  The functions should be categorized.

It is best to test changed with a debug build as it offers more assertions and safety checks.

### Key Build Outputs
- `./build/debug/duckdb` - DuckDB shell with extension pre-loaded (debug build)
- `./build/release/duckdb` - DuckDB shell with extension pre-loaded
- `./build/release/test/unittest` - Test runner

## Test Files

Tests are in `test/sql/*.test` using DuckDB's sqllogictest format. 

[onnimonni]

@rustyconover Thanks for the feedback.

Yeah it's pretty specialized but many of the pushdowns integrations were super hard to find and I hope that this would help others when they would need to do those. My friends are building githits.com which was very helpful to find examples from duckdb. In my experience without the githits.com MCP turned on Claude wasn't even able to find the crucial C++ integrations and thus I would want to make it easier for others who are building new extensions.

It would be great to have your documentation mixed up in there too, I haven't typically even documented that part because Claude figures it out on it's own. And your point about having smaller CLAUDE.md and larger AGENTS.md instead is a good idea. This file is anyway so small that it shouldn't matter too much in the context window.

Idea would be to make it trivial to build any sort of duckdb extension which these instructions help by lot.

[teague-23andme]

The documention here is super helpful, even without LLM agent considerations. I believe I read about some sort of effort to document the extension API in a future release, but can't think of where.

I do think having this in something not specific to Anthropic models would make sense, maybe even something like COMMON_FEATUES.md as it's useful beyond just LLMs.

Even if this doesn't get merged into the extension template, it's a great resource. It may make more sense as a separate repo we could add as a submodule (maybe with some scripts to "install" as CLAUDE.md) that could be used as a source of skills and reference materials and tools for LLM driven extension creation.

I'd be happy to try that out if you're interested in creating an auxiliary repo!