The Problem

AI coding agents generate code that looks correct but misses language-specific conventions, error-handling patterns, and production concerns. Teams adopting AI-assisted development need a codified knowledge base that teaches agents idiomatic patterns before they write code, rather than reviewing and fixing generated output after the fact.

What This Does

This repository is a collection of 13 Markdown skill documents that train AI agents on production-grade programming practices. The skills/ directory covers Go (golang-best-practices.md, go-advanced-patterns.md), Rust (rust-best-practices.md, rust-advanced-patterns.md), and cross-cutting concerns like api-design-patterns.md, observability-patterns.md, and testing-patterns.md.

The examples/ directory contains two reference implementations: go-api-example/ and rust-api-example/, each with CI workflows, linting configuration, and build tooling. These serve as concrete demonstrations of the patterns described in the skill documents.

How It Is Wired

The repository has no application entry point—it is a knowledge base, not a runnable system. The wiring is organizational rather than executional.

Execution starts with the skill documents in skills/. Each file follows a consistent structure: it names source references (e.g., "100 Go Mistakes and How to Avoid Them," "Rust Style Guide"), then presents patterns with code examples. The README.md indexes all skills and summarizes key topics for each.

The examples/ directory is where actual code lives. examples/go-api-example/ includes a Makefile with build targets, a .golangci.yml for linting, and .github/workflows/ci.yml for automated testing. examples/rust-api-example/ has a Cargo.toml declaring dependencies, .clippy.toml and rustfmt.toml for tooling configuration, and its own CI workflow. Neither example has application source files in the structure—they contain configuration and tooling only.

The CI workflows in both examples are the only automated execution paths. They run on GitHub Actions and would invoke the test suites defined in the respective build files. The dependency graph is minimal: examples/rust-api-example/Cargo.toml declares dependencies but no lockfile exists, meaning builds are not reproducible.

How To Use It

This is a reference repository, not a tool to install. There is no build command, no runtime, and no CLI.

  • Setup: Clone with git clone https://github.com/moses-y/best-practices. No dependencies to install.
  • Configuration: None required. The skill documents are plain Markdown.
  • Running it: Feed the skill documents to an AI coding agent as context or reference material. The examples/ directories can be used as templates for new Go or Rust projects—copy the CI workflows, linting configuration, and Makefile into your own project.

Real-World Use

A team adopting AI-assisted development would load skills/golang-best-practices.md into their agent's context window before code generation tasks. The agent would then apply the documented patterns—left-aligned error handling, context propagation, functional options—when writing new Go services. The examples/go-api-example/ CI workflow provides a template for enforcing these patterns through automated linting and testing.

Code Health & Issues

Static analysis of this repository found:

  • Medium/SDLC - No LICENSE file, leaving usage and redistribution rights unclear - root directory
  • Low/Risk - Dependencies declared without a lockfile, preventing reproducible builds - examples/rust-api-example/Cargo.toml

The repository has tests present and CI configured via GitHub Actions. No Dockerfile, no committed secrets. The examples/ directories are configuration-only; they contain no application source code to test or run.

The Bottom Line

This is a well-organized knowledge base for teams standardizing AI-agent code generation around Go and Rust best practices. The skill documents are substantive and source-cited, and the example configurations are usable templates. The lack of a license and application source code in the examples limits its immediate utility—treat it as reference material, not a starter kit.