Add agentic coding infrastructure (#27)

## Summary

- Adds the `AGENTS.md` + `.agent/` directory structure for multi-tool AI
coding support
- Creates symlinks for Claude Code (`CLAUDE.md`), Cursor
(`.cursorrules`, `.cursor/rules/`), and a pointer for Copilot
(`.github/copilot-instructions.md`)
- Updates `.gitignore` to track `.agent`, `.claude` (excluding local
sessions), and `.cursor`

This is a copy of the approach adopted in the Go SDK:
databricks/databricks-sdk-go#1520

## How is this tested?

N/A — documentation and configuration only, no code changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: Ubuntu <renaud.hartert@databricks.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: renaudhartert-db

.agent/prompts/code-review.md

@@ -0,0 +1,18 @@
+# Code Review
+
+Review the given PR or code changes for the following concerns, in order of priority:
+
+1. **Backward compatibility** — Does this change break any existing public API?
+   Check for removed or renamed exported types, functions, or methods.
+2. **Correctness** — Are there logic errors, race conditions, or unhandled edge cases?
+3. **Error handling** — Are errors wrapped with caller context? Are sentinel errors
+   used correctly? See `.agent/rules/error-handling.md`.
+4. **Test coverage** — Are new code paths tested? Do tests follow the conventions
+   in `.agent/rules/testing.md`?
+5. **API design** — Does the change follow the principles in `.agent/rules/api-design.md`?
+   Is the exported surface minimal?
+6. **Style** — Does the code follow `.agent/rules/style-guide.md`? Are names descriptive?
+   Are doc comments present on exported symbols?
+
+For each issue found, state the file and line, the concern category, and a
+concrete suggestion for how to fix it.

.agent/rules/api-design.md

@@ -0,0 +1,60 @@
+---
+description: "API design principles for the Databricks SDK."
+globs: "**/*.go"
+alwaysApply: false
+---
+
+# API Design
+
+## Public API Surface
+
+- Minimize exported API surface: if a type is only used through an interface, keep
+  the concrete type unexported
+- **Return interfaces from constructors** when the concrete type is private and adds
+  no methods beyond the interface — this prevents direct construction and keeps
+  implementation details hidden
+- Prefer new types over modifying existing exported types (additive changes only)
+- Adding a required field to a public type is a breaking change — use nil checks
+  and defaults to preserve existing behavior
+- Remove dead or unused code — don't leave unexported functions that nothing calls
+
+## Interface Design
+
+- **Keep interfaces small and focused**: avoid coupling unrelated concerns in one interface.
+  If an interface does "too many things", split it
+- **Encapsulate domain knowledge**: requirements and validation should live in the component
+  that owns the behavior, not in an external orchestrator. Every consumer should not have
+  to re-implement the same mapping logic
+- Pass specific values, not entire config objects — functions should depend on the narrowest
+  interface possible
+
+## Constructors and Defaults
+
+- Validate required fields in constructors — validate early, fail fast
+- Validation logic should live near its point of use, not in generic/shared layers
+- **Components should own their default values** — don't let callers hard-code defaults
+  that belong to the component
+- **Zero values should be the default behavior**: use negative field names (`Disable` not
+  `Enable`) so that the zero value corresponds to the intended default. A non-zero value
+  always corresponds to a special case
+- When setting default values (timeouts, retries, cache durations), comment the rationale
+- **Use variadic options** (`...Option`) for backward-compatible extensibility
+
+## Immutability and Concurrency
+
+- **Treat config objects as immutable** after construction — do not mutate config fields
+  after a type has been built from them
+- **Keep concurrency primitives internal**: locks, mutexes, and synchronization should be
+  implementation details of the type, not exposed to or managed by callers
+- **Separate mechanism from policy**: e.g., separate *how* to iterate strategies from
+  *which* strategies to try
+
+## Code Structure
+
+- Place helper functions near their callers, not at the top of the file
+- Use `switch/case` for type dispatching, not `if/else` chains
+- Split functions with multiple concerns (e.g., create temp file + atomic rename)
+  so each has one clear responsibility. Use `defer` to enforce cleanup invariants
+- Extract shared logic into helpers at 3+ duplications, not before
+- **Consolidate redundant code paths**: when two functions produce the same result,
+  have one delegate to the other rather than duplicating logic

.agent/rules/error-handling.md

@@ -0,0 +1,25 @@
+---
+description: "Error handling conventions for the Databricks SDK."
+globs: "**/*.go"
+alwaysApply: false
+---
+
+# Error Handling
+
+- Wrap errors with **caller's context**: `fmt.Errorf("resolving workspace host: %w", err)`.
+  Describe what *you* were doing, not what the callee does
+- **Add context at the caller, not in utility functions** — the caller knows the
+  operation's purpose; a utility function like `atomicWriteFile` should not prefix its
+  errors when the caller can provide better context like `"storing token in local cache"`
+- Don't add redundant wrapping — if the underlying error already contains the path/resource,
+  don't repeat it: `write /home/user/.databricks/.tmp: permission denied` is sufficient
+  without a `"write temp file: "` prefix
+- Include the specific resource/URL that failed, not just the operation name
+- Define sentinel errors as package-level `var` using `errors.New()` — never `fmt.Errorf`.
+  They must be comparable with `errors.Is()`
+- **Unexpected cases must error**: a `default` case in a `switch` should return an error
+  (e.g., `fmt.Errorf("unknown host type: %v", h)`), not silently succeed. If silence is
+  intentional, add a comment explaining why
+- **Error messages should be actionable**: include the specific field or value that is
+  wrong so the user knows what to fix (e.g., `"azure_client_id is required"`)
+- Use `%q` (not `%s`) for strings in error/log messages — makes empty strings visible as `""`

.agent/rules/style-guide.md

@@ -0,0 +1,66 @@
+---
+description: "Go code style and naming conventions for the Databricks SDK."
+globs: "**/*.go"
+alwaysApply: false
+---
+
+# Code Style
+
+- Go 1.25+ idioms: range-over-int, `min`/`max` builtins
+- Format with `gofmt`
+- All exported functions and types need doc comments: `// FuncName does X.`
+- Interface doc comments should explain the **contract/lifecycle** — when methods are called,
+  what callers expect, and when errors are appropriate — not just what they do
+- Return early on errors; avoid deeply nested if-else chains
+- Use `context.Context` as the first parameter for functions that do I/O
+
+## Naming
+
+- Acronyms are fully capitalized: `ID` not `Id`, `URL` not `Url`, `HTTP` not `Http`
+- No `Get` prefix on methods — not idiomatic in Go. Use `HostType()` not `GetHostType()`
+- Avoid abbreviations: `authTokenCommand` not `authTokenCmd`
+- Variable names describe content, not origin: `workspaceHost` not `resolvedHost`
+- Use specific names when multiple similar types exist: `httpClient` not `client`
+
+## Go Idioms
+
+- **Exhaustive switches**: prefer `switch` over `if-else` chains for type/enum dispatching.
+  Always include a `default` case that returns an error for unknown values
+- **`sync.Once`** over manual double-checked locking with mutexes — it is safer and
+  respects Go's memory model
+- **Scope variables tightly**: use `:=` inside `if` blocks when the variable is not needed
+  outside: `if err := json.Unmarshal(raw, &f); err != nil {`
+- **Use stdlib functions** over manual equivalents: `math.Ceil`, `json.Marshal`,
+  `slices.Sort`, `slices.Compact`, `sort.Strings`
+- **No forced line length**: Go does not mandate 80-char lines. Prefer keeping function
+  signatures on one line, or use one argument per line for very long signatures
+- **Config structs over long parameter lists**: when a function takes many parameters,
+  group them in a config struct
+  ([Google Go style](https://google.github.io/styleguide/go/best-practices#option-structure))
+- **Don't alias imports unnecessarily**: only alias when there is a genuine name collision
+- **Use `sync.Mutex` directly**, not through an interface — the zero value is valid and
+  needs no initialization
+
+## Code Organization
+
+- **Keep related code close together**: place constructors near the types they return,
+  move helper functions near their callers
+- **Declare variables close to where they're used**: don't declare at the top of a function
+  if the variable is only needed 30 lines later
+- **Inline simple helpers** when they obscure intent — a one-line function called once
+  adds indirection without value. Remove unnecessary intermediate variables that suggest
+  the value might be mutated when it won't be
+- **Move branching out of callbacks**: if a visitor/callback is only needed conditionally,
+  check the condition first, then register the callback — don't put the `if` inside
+
+## Comments and Documentation
+
+- **Full sentences**: comments start with a capital letter and end with a period.
+  Ref: [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments#comment-sentences)
+- **Explain why, not what**: the code is self-explanatory for *what* it does; comments
+  should explain *why* a decision was made or why a non-obvious approach was chosen
+- **Use Go doc links**: reference types with bracket syntax: `// implements the [TokenCache] interface`
+- **Document public types thoroughly**: explain the purpose, which fields are optional,
+  and what the zero value means
+- **Don't duplicate godoc**: if a method's doc comment says the same thing as the type's
+  doc comment, remove the redundancy

.agent/rules/testing.md

@@ -0,0 +1,64 @@
+---
+description: "Testing standards and anti-patterns for the Databricks SDK."
+globs: "**/*_test.go"
+alwaysApply: false
+---
+
+# Testing
+
+Use Go's standard `testing` package with `google/go-cmp` for complex comparisons.
+Do NOT introduce `testify` — this SDK minimizes third-party dependencies.
+
+Table-driven tests are preferred:
+
+```go
+for _, tc := range testCases {
+    t.Run(tc.name, func(t *testing.T) {
+        // ...
+        if diff := cmp.Diff(tc.want, got); diff != "" {
+            t.Errorf("mismatch (-want +got):\n%s", diff)
+        }
+    })
+}
+```
+
+- Unit tests: `*_test.go` alongside source files
+- Call `t.Helper()` at the start of test helper functions (correct line numbers in failures)
+- For configurable options, always test three cases: (1) explicit values, (2) nil/unset default, (3) empty value
+- Inject `time.Now` as `func() time.Time` for time-dependent logic — makes tests deterministic
+- Always check errors — never use `_` for error returns in tests
+- Assert on exact expected values, not partial matches (e.g., full header value, not just prefix)
+- Extract repeated test values to shared `const`/`var` to convey intent and avoid silent drift
+- Add explicit timeouts to channel/goroutine-based tests to prevent hanging
+- Use `defer close(ch)` for channel cleanup to handle error paths safely
+
+## Naming and Style
+
+- Use `want` for expected values and `got` for actual values — not `expected`/`actual`
+- Use **named struct fields** in test mock initialization: `&IDToken{Value: tok}` not `&IDToken{tok}`
+- Use existing test utilities rather than creating new one-off mock types
+
+## Test Design Philosophy
+
+- **Pragmatic about test value**: don't write tests that can't catch real regressions.
+  If removing the tested code wouldn't be caught by the test, the test is not useful
+- **Prefer blackbox tests over whitebox tests**: verify observable behavior, not
+  implementation details. When structural constraints make blackbox testing impossible,
+  consider refactoring for testability — but not at the cost of breaking backward compatibility
+- **Test at the right abstraction level**: test behavior through the public interface of
+  a component, not through its internals
+- **Mock at the right level**: mock the nearest interface boundary, not deep internals
+- **Prefer isolated tests by design**: use dependency injection and mocks rather than
+  relying on environment cleanup utilities
+
+## Anti-Patterns (never do these)
+
+- Deleting or skipping flaky tests instead of fixing the root cause
+- Tests depending on execution order or shared mutable state
+- Non-descriptive test names (`TestFoo`, `TestBasic`) — follow the same pattern as Go
+  `Example` functions: `TestFunctionName_description` (e.g., `TestHostType_missingScheme`,
+  `TestConfig_HostType_missingScheme` for a method on a type)
+- `time.Now` in tests — use a mock clock
+- Exporting methods solely for test access — use `cmp.Diff` to compare structs,
+  or write internal (`_test.go` in same package) tests instead
+- Unnecessary concurrency in tests — if goroutines/channels aren't clearly needed, don't use them

.agent/skills/write-pr-description/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: write-pr-description
+description: >
+  Write or improve a GitHub pull request description. Use when the user asks
+  to "write a PR description", "improve the PR description", "update the PR
+  body", or provides a PR URL and asks for a better description.
+  Keywords: PR description, pull request summary, PR body, PR writeup.
+---
+
+# Write PR Description
+
+Generate a structured PR description that explains **why** the change exists,
+not just what files were touched.
+
+## When to use
+
+- The user provides a PR URL and asks to write or improve its description.
+- The user asks to draft a PR description for the current branch.
+- An agent needs to open a PR and wants a high-quality description.
+
+## Workflow
+
+### Phase 1: Gather context
+
+Collect all the information needed to understand the change:
+
+1. **Read the PR metadata** — title, current description, author, branch name.
+2. **Read the full diff** — understand every file changed, every function added
+   or removed, every signature change. Do not skip files.
+3. **Read surrounding code when needed** — if the diff modifies an interface or
+   a struct, read the full file to understand how the change fits into the
+   existing architecture.
+4. **Check for linked issues or docs** — the PR or commit messages may
+   reference issues, design docs, or RFCs that explain motivation.
+
+### Phase 2: Analyze the change
+
+Before writing, answer these questions internally:
+
+- **What was the status quo before this PR?** What limitation, bug, or missing
+  capability existed?
+- **Why is this change needed now?** What concrete problem does it solve? Who
+  benefits?
+- **What are the key design decisions?** Why was this approach chosen over
+  alternatives?
+- **What is the new API surface?** Any new public types, functions, or
+  configuration options?
+- **What are the architectural changes?** How does the internal structure
+  change? What moves where? What gets refactored?
+- **Are there behavioral changes?** If not, say so explicitly — this reassures
+  reviewers.
+
+### Phase 3: Write the description
+
+Use the structure defined in `.github/PULL_REQUEST_TEMPLATE.md` as the
+template. The tone should be direct and technical. Write for a reviewer who is
+familiar with the codebase but has not seen this change before.
+
+**Key principles:**
+
+- **Lead with why, not what.** The diff already shows the what. The description
+  should explain the reasoning that is not visible in the code.
+- **Be specific.** Instead of "improves extensibility", say "allows internal
+  tools to compose their own auth chain from individual credential strategies".
+- **Name things.** Reference actual types, functions, files, and config fields.
+  Use backticks for code references.
+- **State non-changes explicitly.** If the PR is a refactor with no behavioral
+  change, say "No behavioral changes. Existing users are unaffected." This is
+  valuable information for reviewers.
+- **Keep the summary to one or two sentences.** It should be scannable.
+- **Use the motivation section to tell a story.** What was the problem? Why
+  couldn't it be solved before? What does this PR unlock?
+
+### Phase 4: Update the PR
+
+Use the GitHub MCP tools or `gh` CLI to update the PR body with the new
+description. Confirm with the user before pushing if unsure.

.cursor/rules/00-claude-context.mdc

@@ -0,0 +1,12 @@
+---
+description: Always load AGENTS.md context first
+alwaysApply: true
+globs:
+  - "**/*"
+---
+
+Always apply AGENTS.md context before taking actions.
+
+1. If `/AGENTS.md` exists, read and follow it for every task in this workspace.
+2. Read scoped rules from `.agent/rules/` when working on relevant files.
+3. Keep these instructions active even for small or routine requests.

.cursor/rules/api-design.mdc

@@ -0,0 +1 @@
+../../.agent/rules/api-design.md

.cursor/rules/error-handling.mdc

@@ -0,0 +1 @@
+../../.agent/rules/error-handling.md

.cursor/rules/style-guide.mdc

@@ -0,0 +1 @@
+../../.agent/rules/style-guide.md