{"slug":"lit-code","title":"lit-code","summary":"Shapes every code edit: build-decision gate, language references first, tests before code, input parsed once, typed seams, files under 250 pure LOC, clean lint and types.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-26T18:48:58.341044Z","repo":{"url":"https://github.com/wjgoarxiv/litgravity","stars":167,"forks":13,"license":"MIT","updatedAt":"2026-11-15T15:44:04Z"},"bodyHtml":"<h1>Go Programmer (lit-code, Go reference index)</h1>\n<p>Production Go in 2026. The house style is plain code, strict tooling, and a type layout in which invalid states have no constructor. Start here, then open only the reference file that matches the task at hand.</p>\n<h2>Why the toolchain carries so much weight</h2>\n<p>Go ships a small type system, so a few guarantees that other languages get from the compiler have to come from conventions and linters:</p>\n<ul>\n<li>Sum types are missing. An interface plus a type switch is the closest substitute, and completeness is checked by the <code>exhaustive</code> linter.</li>\n<li>Optional values are expressed with pointers or zero values. A nil interface and an interface that holds a nil pointer behave differently, which is a classic source of surprise.</li>\n<li>Failure is a second return value (<code>(T, error)</code>). The compiler lets a caller drop it silently unless <code>errcheck</code> is on.</li>\n<li>A defined type such as <code>type UserID string</code> blocks accidental assignment between two defined types, yet an untyped string literal converts to it freely.</li>\n</ul>\n<p>The answer is to let tools play the part of the missing compiler checks. Run <code>golangci-lint</code> v2 with the configuration in <code>golangci-strict.md</code> the way a TypeScript project runs <code>tsc --strict</code>. Add <code>nilaway</code> for nil-flow analysis and <code>go test -race</code> for data races. When all of them are green, the code has earned the label \"done\".</p>\n<h2>Five working rules</h2>\n<ol>\n<li><strong>Parse at the boundary.</strong> Input from HTTP, RPC, CLI flags, environment variables and files is converted into domain types through <code>New*(...)</code> constructors with unexported fields. Inside the domain the values are trusted. See <code>data-modeling.md</code>.</li>\n<li><strong>Return <code>(T, error)</code>.</strong> Library code returns errors and leaves <code>panic</code> for programmer bugs found at start-up. Wrap with <code>%w</code>, branch with <code>errors.Is</code> and <code>errors.As</code>, and give callers a typed error when they need to branch. See <code>error-handling.md</code>.</li>\n<li><strong>Sealed interfaces for variants.</strong> An interface with an unexported method closes the set of implementations; a type switch plus <code>exhaustive</code> proves every case is handled. See <code>type-patterns.md</code>.</li>\n<li><strong><code>context.Context</code> goes first.</strong> Every function that does I/O or blocks accepts a <code>ctx</code> as its first parameter, every goroutine has a shutdown path tied to a context, and time comes from an injected clock in domain code. See <code>concurrency.md</code>.</li>\n<li><strong>Generate external contracts.</strong> <code>sqlc</code> produces the database layer, <code>oapi-codegen</code> produces OpenAPI servers and clients, <code>buf</code> with <code>protoc-gen-go</code> and <code>protoc-gen-connect-go</code> produces RPC stubs. Hand-written marshalling for those contracts drifts from the spec. See <code>sqlc-pgx.md</code> and <code>grpc-connect.md</code>.</li>\n</ol>\n<h2>Tooling table</h2>\n<table>\n<thead>\n<tr>\n<th>Concern</th>\n<th>Choose</th>\n<th>Avoid</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Go version</td>\n<td>1.23 or newer (range-over-func, <code>iter</code>, stable <code>log/slog</code>); 1.24 adds the <code>tool</code> directive in <code>go.mod</code></td>\n<td>releases older than 1.22</td>\n</tr>\n<tr>\n<td>Modules</td>\n<td><code>go.mod</code>, plus <code>go.work</code> for a multi-module repository</td>\n<td>GOPATH layouts, <code>dep</code></td>\n</tr>\n<tr>\n<td>Formatting</td>\n<td><code>gofumpt</code> and <code>goimports -local &lt;module&gt;</code></td>\n<td>bare <code>gofmt</code></td>\n</tr>\n<tr>\n<td>Lint</td>\n<td><code>golangci-lint</code> v2 with the bundle in <code>golangci-strict.md</code></td>\n<td>a lone <code>go vet</code></td>\n</tr>\n<tr>\n<td>Nil analysis</td>\n<td><code>nilaway</code> in CI</td>\n<td>hoping</td>\n</tr>\n<tr>\n<td>Extra vet passes</td>\n<td><code>fieldalignment</code>, <code>shadow</code></td>\n<td>skipping them</td>\n</tr>\n<tr>\n<td>Tests</td>\n<td><code>go test -race -shuffle=on -count=1 ./...</code></td>\n<td>cached or race-free runs</td>\n</tr>\n<tr>\n<td>Goroutine leaks</td>\n<td><code>go.uber.org/goleak</code> in <code>TestMain</code></td>\n<td>eyeballing</td>\n</tr>\n<tr>\n<td>Mocks</td>\n<td><code>go.uber.org/mock</code> (<code>mockgen</code>)</td>\n<td>hand-maintained stubs for wide interfaces</td>\n</tr>\n<tr>\n<td>Database</td>\n<td><code>sqlc</code> with <code>jackc/pgx/v5</code></td>\n<td><code>database/sql</code> with an ORM</td>\n</tr>\n<tr>\n<td>HTTP</td>\n<td><code>gin-gonic/gin</code> by default, <code>go-chi/chi</code> for a minimal router, <code>connectrpc.com/connect</code> for RPC</td>\n<td><code>gorilla/mux</code> for new work, <code>fiber</code> (not net/http based)</td>\n</tr>\n<tr>\n<td>RPC</td>\n<td><code>connectrpc.com/connect</code></td>\n<td>raw <code>grpc-go</code> unless a Connect gap forces it</td>\n</tr>\n<tr>\n<td>Validation</td>\n<td><code>go-playground/validator/v10</code> at HTTP edges, <code>protovalidate-go</code> for proto, smart constructors in the domain</td>\n<td>scattered <code>if len(s) == 0</code> chains</td>\n</tr>\n<tr>\n<td>Config</td>\n<td><code>caarlos0/env/v11</code></td>\n<td><code>viper</code> unless file, env and flag layers all matter</td>\n</tr>\n<tr>\n<td>Logging</td>\n<td><code>log/slog</code></td>\n<td>logrus, zap or zerolog for new code</td>\n</tr>\n<tr>\n<td>CLI</td>\n<td><code>spf13/cobra</code></td>\n<td>hand-rolled <code>os.Args</code> parsing past two flags</td>\n</tr>\n<tr>\n<td>TUI</td>\n<td><code>charm.land/bubbletea/v2</code> family (see <code>bubbletea-v2.md</code> for CJK input)</td>\n<td>bubbletea v1 when IME input matters</td>\n</tr>\n</tbody>\n</table>\n<p>One command acts as the completion gate for any change:</p>\n<pre><code>gofumpt -l . | (! grep .) &amp;&amp; \\\n  golangci-lint run ./... &amp;&amp; \\\n  nilaway -include-pkgs \"$(go list -m)\" ./... &amp;&amp; \\\n  go test -race -shuffle=on -count=1 ./...\n</code></pre>\n<p>A failure in any stage means the change is unfinished. <code>scripts/go/check-no-excuse-rules.sh</code> adds the rules that linters cannot see (suppression comments, file length, banned imports); run it after each edit session.</p>\n<h2>Which file to open</h2>\n<table>\n<thead>\n<tr>\n<th>Task</th>\n<th>Open</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>New project, layout, Taskfile, CI</td>\n<td><code>bootstrap.md</code></td>\n</tr>\n<tr>\n<td>Named types, smart constructors, struct tags</td>\n<td><code>data-modeling.md</code>, <code>type-patterns.md</code></td>\n</tr>\n<tr>\n<td>Error design, HTTP error mapping</td>\n<td><code>error-handling.md</code></td>\n</tr>\n<tr>\n<td>Goroutines, channels, <code>errgroup</code>, shutdown</td>\n<td><code>concurrency.md</code></td>\n</tr>\n<tr>\n<td>gin service, middleware, SSE, WebSocket</td>\n<td><code>backend-stack.md</code></td>\n</tr>\n<tr>\n<td>Protobuf, Connect, interceptors, streaming</td>\n<td><code>grpc-connect.md</code></td>\n</tr>\n<tr>\n<td>PostgreSQL, sqlc, pgx pool, goose, testcontainers</td>\n<td><code>sqlc-pgx.md</code></td>\n</tr>\n<tr>\n<td>Command-line tools</td>\n<td><code>cobra-stack.md</code></td>\n</tr>\n<tr>\n<td>Terminal UIs</td>\n<td><code>bubbletea-v2.md</code></td>\n</tr>\n<tr>\n<td>Unit, table, golden, property, integration tests</td>\n<td><code>testing.md</code></td>\n</tr>\n<tr>\n<td>Linter configuration and the suppression policy</td>\n<td><code>golangci-strict.md</code></td>\n</tr>\n<tr>\n<td>Which library for which job</td>\n<td><code>libraries.md</code></td>\n</tr>\n<tr>\n<td>Throwaway scripts with <code>go run</code></td>\n<td><code>one-liners.md</code></td>\n</tr>\n</tbody>\n</table>\n<h2>The 250 line ceiling</h2>\n<p>A <code>.go</code> file whose pure lines (no blanks, no comments) pass 250 has outgrown its purpose. Go favours many small files inside one package, so splitting costs little: give each file one cohesive type with its methods. The usual offender is <code>cmd/server/main.go</code>; reduce it to wiring (<code>signal.NotifyContext</code>, load config, call <code>cmd.Execute</code>) and move everything else into <code>internal/</code>.</p>\n<h2>Existing codebases</h2>\n<p>When a file already breaks these rules, write the new lines in the strict style and leave the surrounding code alone for that change. A branch-wide cleanup belongs to the <code>lit-burnoff</code> skill, which locks behavior with tests first.</p>\n<h2>When this reference applies</h2>\n<p>Load it whenever you create or edit a <code>.go</code> file, <code>go.mod</code>, <code>go.sum</code>, <code>.golangci.yml</code>, <code>Taskfile.yml</code>, or a generator input such as <code>*.proto</code>, the <code>.sql</code> files beside <code>sqlc.yaml</code>, or <code>openapi.yaml</code> beside <code>oapi-codegen.yaml</code>. One-off scripts get the same discipline; the <code>//go:build ignore</code> plus <code>go run</code> pattern in <code>one-liners.md</code> gives them throwaway ergonomics with production hygiene.</p>\n<p>Read the matching reference before writing. Re-read it when a session drifts, and finish with the architecture review pass from the main skill.</p>\n<h2>Verification checklist</h2>\n<ol>\n<li><code>gofumpt -l .</code> prints nothing.</li>\n<li><code>golangci-lint run ./...</code> exits 0 with the strict bundle and no new <code>//nolint</code> lines (each one needs a linter name and a reason).</li>\n<li><code>nilaway</code> reports nothing for the module's packages.</li>\n<li><code>go test -race -shuffle=on -count=1 ./...</code> passes; goleak is wired into <code>TestMain</code> for packages that start goroutines.</li>\n<li><code>go build ./...</code> and <code>go vet ./...</code> succeed on a clean checkout (run <code>git status</code> first so untracked generated files do not hide a missing <code>go generate</code> step).</li>\n<li>Every file stays under 250 pure lines, and <code>cmd/*/main.go</code> stays under 50.</li>\n<li>In headless runs, read the tool versions with <code>go version</code> and <code>golangci-lint version</code> before choosing config syntax; a refused <code>run_command</code> ends the run, so ask for the permission up front.</li>\n</ol>\n<h2>Sources</h2>\n<ul>\n<li>Go release notes: <a href=\"https://go.dev/doc/devel/release\">https://go.dev/doc/devel/release</a></li>\n<li>golangci-lint v2 documentation: <a href=\"https://golangci-lint.run/\">https://golangci-lint.run/</a></li>\n<li>nilaway: <a href=\"https://github.com/uber-go/nilaway\">https://github.com/uber-go/nilaway</a></li>\n<li>Effective Go and Go Code Review Comments: <a href=\"https://go.dev/doc/effective_go\">https://go.dev/doc/effective_go</a></li>\n</ul>\n","files":[{"path":"references/core/agy-surfaces-and-verification.md","sizeBytes":8664,"isText":true},{"path":"references/core/cross-language-stack.md","sizeBytes":8537,"isText":true},{"path":"references/core/file-size-ceiling.md","sizeBytes":7674,"isText":true},{"path":"references/core/language-jump-table.md","sizeBytes":12184,"isText":true},{"path":"references/core/post-write-review.md","sizeBytes":4789,"isText":true},{"path":"references/core/shared-rules.md","sizeBytes":7167,"isText":true},{"path":"references/core/tdd-discipline.md","sizeBytes":7675,"isText":true},{"path":"references/engineering-risk-signals.md","sizeBytes":6432,"isText":true},{"path":"references/go/backend-stack.md","sizeBytes":23138,"isText":true},{"path":"references/go/bootstrap.md","sizeBytes":11562,"isText":true},{"path":"references/go/bubbletea-v2.md","sizeBytes":13593,"isText":true},{"path":"references/go/cobra-stack.md","sizeBytes":14663,"isText":true},{"path":"references/go/concurrency.md","sizeBytes":14026,"isText":true},{"path":"references/go/data-modeling.md","sizeBytes":13137,"isText":true},{"path":"references/go/error-handling.md","sizeBytes":12194,"isText":true},{"path":"references/go/golangci-strict.md","sizeBytes":11956,"isText":true},{"path":"references/go/grpc-connect.md","sizeBytes":15732,"isText":true},{"path":"references/go/libraries.md","sizeBytes":14447,"isText":true},{"path":"references/go/one-liners.md","sizeBytes":8081,"isText":true},{"path":"references/go/README.md","sizeBytes":7857,"isText":true},{"path":"references/go/sqlc-pgx.md","sizeBytes":17792,"isText":true},{"path":"references/go/testing.md","sizeBytes":16375,"isText":true},{"path":"references/go/type-patterns.md","sizeBytes":12708,"isText":true},{"path":"references/observability-contracts.md","sizeBytes":5777,"isText":true},{"path":"references/python/async-anyio.md","sizeBytes":17594,"isText":true},{"path":"references/python/data-modeling.md","sizeBytes":8906,"isText":true},{"path":"references/python/data-processing.md","sizeBytes":6737,"isText":true},{"path":"references/python/error-handling.md","sizeBytes":10355,"isText":true},{"path":"references/python/fastapi-stack.md","sizeBytes":13640,"isText":true},{"path":"references/python/httpx2-optimization.md","sizeBytes":16863,"isText":true},{"path":"references/python/libraries.md","sizeBytes":12348,"isText":true},{"path":"references/python/one-liners.md","sizeBytes":9698,"isText":true},{"path":"references/python/orjson-stack.md","sizeBytes":14399,"isText":true},{"path":"references/python/pydantic-ai.md","sizeBytes":11906,"isText":true},{"path":"references/python/pyproject-strict.md","sizeBytes":11402,"isText":true},{"path":"references/python/README.md","sizeBytes":16156,"isText":true},{"path":"references/python/textual-tui.md","sizeBytes":8557,"isText":true},{"path":"references/python/type-patterns.md","sizeBytes":8089,"isText":true},{"path":"references/rust/async-tokio.md","sizeBytes":11933,"isText":true},{"path":"references/rust/axum-stack.md","sizeBytes":19406,"isText":true},{"path":"references/rust/cargo-strict.md","sizeBytes":10919,"isText":true},{"path":"references/rust/clap-stack.md","sizeBytes":14514,"isText":true},{"path":"references/rust/concurrency.md","sizeBytes":14032,"isText":true},{"path":"references/rust/libraries.md","sizeBytes":17369,"isText":true},{"path":"references/rust/one-liners.md","sizeBytes":8939,"isText":true},{"path":"references/rust/proptest-insta.md","sizeBytes":14415,"isText":true},{"path":"references/rust/README.md","sizeBytes":16183,"isText":true},{"path":"references/rust/type-state.md","sizeBytes":15330,"isText":true},{"path":"references/rust-ub/miri-sanitizers-loom.md","sizeBytes":15977,"isText":true},{"path":"references/rust-ub/README.md","sizeBytes":11559,"isText":true},{"path":"references/rust-ub/ub-taxonomy.md","sizeBytes":15446,"isText":true},{"path":"references/rust/unsafe-discipline.md","sizeBytes":14595,"isText":true},{"path":"references/rust/zero-cost-safety.md","sizeBytes":16745,"isText":true},{"path":"references/typescript/backend-hono.md","sizeBytes":21934,"isText":true},{"path":"references/typescript/bootstrap.md","sizeBytes":7874,"isText":true},{"path":"references/typescript/data-modeling.md","sizeBytes":7374,"isText":true},{"path":"references/typescript/error-handling.md","sizeBytes":7500,"isText":true},{"path":"references/typescript/README.md","sizeBytes":11469,"isText":true},{"path":"references/typescript/tsconfig-strict.md","sizeBytes":7745,"isText":true},{"path":"references/typescript/type-patterns.md","sizeBytes":9352,"isText":true},{"path":"scripts/go/check-no-excuse-rules.sh","sizeBytes":7228,"isText":true},{"path":"scripts/go/new-project.py","sizeBytes":4544,"isText":true},{"path":"scripts/go/templates/AGENTS.md.tmpl","sizeBytes":845,"isText":false},{"path":"scripts/go/templates/ci.yml","sizeBytes":863,"isText":true},{"path":"scripts/go/templates/config.go","sizeBytes":643,"isText":false},{"path":"scripts/go/templates/.editorconfig","sizeBytes":206,"isText":false},{"path":"scripts/go/templates/gitignore","sizeBytes":99,"isText":false},{"path":"scripts/go/templates/.golangci.yml","sizeBytes":1553,"isText":true},{"path":"scripts/go/templates/main.go.tmpl","sizeBytes":329,"isText":false},{"path":"scripts/go/templates/README.md.tmpl","sizeBytes":204,"isText":false},{"path":"scripts/go/templates/run.go","sizeBytes":350,"isText":false},{"path":"scripts/go/templates/Taskfile.yml","sizeBytes":706,"isText":true},{"path":"scripts/python/check-no-excuse-rules.py","sizeBytes":25510,"isText":true},{"path":"scripts/python/new-project.py","sizeBytes":4695,"isText":true},{"path":"scripts/python/new-script.py","sizeBytes":3236,"isText":true},{"path":"scripts/rust/check-no-excuse-rules.py","sizeBytes":10633,"isText":true},{"path":"scripts/rust/check-no-excuse-rules.sh","sizeBytes":6591,"isText":true},{"path":"scripts/rust/new-project.py","sizeBytes":5682,"isText":true},{"path":"scripts/typescript/check-no-excuse-rules.ts","sizeBytes":10146,"isText":true},{"path":"scripts/typescript/new-project.ts","sizeBytes":4313,"isText":true},{"path":"SKILL.md","sizeBytes":23605,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-11-16T00:40:26.860755Z","sha256":"BF57E3618072AC2F664827EEA87BC14AD6408F2218C93F08F1BB6B8D3DA54250","sizeBytes":347761},"review":null,"source":{"repositoryUrl":"https://github.com/wjgoarxiv/litgravity","path":"plugin/skills/lit-code","license":"MIT","commit":"7e56e0b1388e4f082c4ccc760ed3fc099e621844","subtreeSha":"27C7B718422870363E06D910729753482F8693263073F9EA11380BE93C15C8AA","lastSyncedAt":"2026-11-16T00:39:35.262553Z"},"reviewedAt":"2026-11-16T00:46:15.371223Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/wjgoarxiv/litgravity/tree/main/plugin/skills/lit-code"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install wjgoarxiv-litgravity@llmmart"},{"target":"git","command":"git clone https://github.com/wjgoarxiv/litgravity.git"}]}