filefunc

name	filefunc
description	Code structure convention and CLI for LLM-native Go/Python/TypeScript/C#/Java/Rust development. Use when: validating "one file, one concept" rules, tracing func call chains, exploring code context with LLM scoring, verifying annotation-body consistency. Triggers on: filefunc, code structure validation, annotation rules, call chain, func tracing, codebook, one file one func, ff:func, ff:what, ff:type.
license	MIT
metadata	{"author":"park-jun-woo","version":"0.2.0"}

filefunc — One file, one concept. Code structure convention and CLI for LLM-native development

When to Use This Skill

• Validating that a Go/Python/TypeScript/C#/Java/Rust project follows the "one file, one function/type" convention
• Tracing function call chains and understanding impact radius before modifying code
• Finding relevant code context for a given task using LLM-based scoring
• Verifying that //ff:what annotations accurately describe function bodies
• Checking codebook consistency and annotation correctness
• Setting up or maintaining filefunc annotations (//ff:func, //ff:what, //ff:type) in a project

Do NOT Use This Skill

• Algorithm libraries or low-level systems programming projects
• Projects that don't follow the one-file-one-concept convention
• General Go/Python/TypeScript/C#/Java/Rust linting unrelated to structural conventions

Install

go install github.com/park-jun-woo/filefunc@latest

Requires: Go 1.20+ and a C compiler (gcc/clang). C#, Java, and Rust parsing uses tree-sitter via cgo, so the binary must be built with CGO_ENABLED=1 and a C toolchain present. No runtime dependency — grammars are compiled into the binary (no node/python3/dotnet/jdk/cargo needed at runtime).

Commands

Command	Purpose	Example
filefunc validate [root]	Validate code structure rules (P, F, Q, A, C, N)	filefunc validate .
filefunc chain func <name>	Trace call chain for a specific function	filefunc chain func RunValidate --chon 2
filefunc chain feature <name>	Trace call chains for all funcs in a feature	filefunc chain feature validate --meta what
filefunc context <prompt>	LLM 4-stage context search (feature select -> filter -> what -> body)	filefunc context "add new rule"
filefunc llmc [root]	Verify //ff:what matches func body using LLM, generate //ff:checked	filefunc llmc .

Key Flags

Flag	Commands	Description
--chon <1-3>	chain func, chain feature	Chain hop distance (default 1)
--meta <meta,what,why,checked,all>	chain func, chain feature	Include annotation metadata in output
--prompt <text>	chain func, chain feature	User task intent for relevance scoring via reranker
--rate <0.0-1.0>	chain func, chain feature	Relevance score threshold
--format <text|json>	validate	Output format
--lang <go|python|typescript|csharp|java|rust>	all	Language override (auto-detected if omitted)
--codebook <path>	validate	Custom codebook path (default: <root>/codebook.yaml)
--search <filter>	context	Direct annotation filter (e.g. "feature=validate type=rule")

Workflow

Before modifying code, always follow this order:

1. Read codebook.yaml — understand project vocabulary (allowed feature, type, pattern, level values)
2. Run filefunc chain func <target> --chon 2 — identify call relationships and impact radius of the target
3. Read files identified by chain — only read what's necessary
4. Write code — follow filefunc rules (one file, one func/type; annotations at top)
5. Run filefunc validate — confirm zero violations before committing

Key Concepts

Annotations

Every func/type file requires annotations at the top of the file:

//ff:func feature=validate type=rule control=sequence
//ff:what Validates that each file contains exactly one function
//ff:why Early return pattern avoids deep nesting
//ff:checked llm=model hash=bodyhash

• //ff:func / //ff:type — required. Values must exist in codebook.yaml
• //ff:what — required. One-line description of what the func/type does
• //ff:why — optional. Rationale for design decisions
• //ff:checked — auto-generated by filefunc llmc. Never write manually
• Python uses # ff:func, # ff:what, etc. TypeScript, C#, Java, and Rust use // ff:func, // ff:what, etc.

Codebook (codebook.yaml)

Defines the allowed vocabulary for annotations. Two sections:

• required — keys that every annotation must include (feature, type)
• optional — keys used when applicable (pattern, level)

Values not in the codebook cause validate ERROR (rule A2).

Control Flow Annotation

Func files require control= with one of:

Value	Meaning	Depth Limit
sequence	No branching/looping at depth 1. Body max 100 lines	2
selection	switch/match at depth 1. No loops	2
iteration	Loop at depth 1. Requires dimension=	dimension + 1

Validation Order

1. P rules (project level) — single language check
2. C rules (codebook) — codebook.yaml integrity
3. F/Q/A rules (file level) — via toulmin defeats graph

P or C violations block subsequent validation.

Common Errors and Fixes

Error	Cause	Fix
F1: more than one func in file	Multiple functions defined in a single file	Split each function into its own file (filename = func name)
F2: more than one type in file	Multiple types in a single file	One type per file (filename = type name)
A1: missing //ff:func annotation	Func file lacks annotation	Add //ff:func feature=... type=... control=... at file top
A2: unknown codebook value	Annotation uses value not in codebook.yaml	Add the value to codebook.yaml or fix the typo
A3: missing //ff:what	No what annotation	Add //ff:what <description> after //ff:func
A6: annotation not at top of file	Annotations placed after code	Move all //ff: lines before package (Go) or imports (Python)
A9: missing control=	Func file lacks control annotation	Add control=sequence|selection|iteration to //ff:func
Q1: nesting depth exceeded	Too many nested control structures	Extract inner logic into a separate sequence function
Q3: sequence func body > 100 lines	Sequence function too long	Split into smaller functions
P1: mixed languages	.go and .py (or .ts) coexist in project	One language per project
C4: empty description	Required codebook value has no description	Add description in codebook.yaml

Conventions

• Filenames: snake_case
• Go variables/functions: camelCase. Types: PascalCase
• Python variables/functions: snake_case. Classes: PascalCase
• Go methods: receiver_method.go (e.g., server_start.go)
• Constants-only files are exempt from annotations (F5 exception)
• Handle errors immediately with early return (N5)
• gofmt compliance required for Go (N4)

Full Documentation

• Rulebook (SSOT): rulebook.md in project root — complete rule definitions with severity and verification details
• Codebook: codebook.yaml in project root — allowed annotation vocabulary
• CLAUDE.md: project root — AI agent working instructions