rinkaku: Instructions file for Claude Code

CLAUDE.md

Project-specific instructions for working on rinkaku.

Project overview

rinkaku (輪郭, "outline") is a CLI that condenses large PR diffs — especially LLM-generated ones — into just the signatures of changed symbols and their dependencies, so reviewers and LLMs can grasp the API surface of a change without reading every implementation line.

• Input: a unified diff via stdin (gh pr diff 123 | rinkaku), or rinkaku --base main (runs git diff internally).
• Core: tree-sitter parses changed files, finds the definitions containing changed lines, and slices out their signatures.
• Dependency expansion: 1-hop references via tree-sitter tags queries (v1). LSP-based resolvers (pyright, gopls, etc.) are pluggable later via a Resolver trait.
• Built-in languages: Rust, Go, Python, TypeScript, and HCL (Terraform), each implemented as a LanguageSupport trait impl (grammar crate + tags query + signature-slicing rule), making language support additive.
• Output: Markdown or JSON, designed to be fed to LLMs.

Design rationale for the choices above is recorded in docs/adr/.

Architecture principles

• Flat module structure: start simple, split into submodules only when a group of files sharing a responsibility grows large enough to warrant it. Do not pre-create deep module hierarchies.
• Core logic is pure: no IO, no wall clock, no environment variable reads inside rinkaku-core's domain logic. Diff input, file reads, process invocations (git, future LSP servers) belong at the boundary (main.rs and future adapter modules), passed in as arguments or via ports.
• Ports as traits, defined on the consumer side: LanguageSupport (tree-sitter grammar + tags query + signature slicing per language) and Resolver (dependency resolution strategy) are traits defined where they are consumed, not where they are implemented. Keep them small (1-3 methods).
• Composition root in main.rs: dependency wiring (which LanguageSupport impls are registered, which Resolver is used) is assembled by hand in main.rs. No DI framework, no global state, no init()-time wiring.
• Do not introduce a shared/common abstraction (e.g. a generic repository layer over language support or resolvers) speculatively — only after a concrete second use case demands it, and after discussing it in an ADR.