Notes on documentation, codebases, and keeping context current.

How to Write a CONTRIBUTING.md: A Guide Humans and Coding Agents Actually Follow

Most CONTRIBUTING.md files are either a code of conduct with a link to the issue tracker or a wall of process nobody reads. A practical guide to writing one that gets a first pull request merged: what goes in it, what to leave out, how it fits next to AGENTS.md, and how to keep it true.

• documentation
• developer-experience
• ai-agents

How to Write a Pull Request Description: A Template Reviewers and Agents Can Both Use

Most pull request descriptions restate the title or the prompt. A practical guide to writing PR descriptions that speed up review and survive in git history: what to include, a copy-paste GitHub template, examples, and how to keep agent-written descriptions honest.

• documentation
• developer-experience
• engineering-management
• +1

Documenting APIs for AI Agents: OpenAPI, llms.txt, and MCP, and When Each One Matters

AI agents now read your API docs before developers do. What OpenAPI, llms.txt, Markdown pages, and an MCP server each give an agent, which one to build first, how to write descriptions an agent can act on, and how to keep all of them in sync with the code.

• documentation
• ai-agents
• mcp
• +1

AGENTS.md and CLAUDE.md in a Monorepo: Where Instruction Files Go and Which One Wins

Coding agents resolve nested instruction files differently: AGENTS.md uses the closest file, Claude Code stacks every CLAUDE.md from the root down. How to lay out instruction files in a monorepo, what goes at each level, and how to stop them contradicting each other.

• ai-agents
• claude-code
• developer-experience
• +1

llms.txt Explained: How to Write, Validate, and Keep One Accurate

llms.txt is a small Markdown file that tells AI agents which pages on your site matter. What the v2 spec requires, a worked example, the mistakes validators catch, how to serve it, and why the file quietly goes stale.

• documentation
• ai-agents
• developer-tools

Docs as Code on GitHub: A Workflow That Keeps Docs in the Pull Request

Docs as code means writing documentation with the same tools and review process as code. A practical GitHub workflow: repo layout, the CI checks worth running, a docs-required gate, and the gap none of them close — docs that are reviewed but no longer true.

• documentation
• developer-tools
• developer-experience
• +1

Reviewing AI-Generated Pull Requests: What Changes When the Author Is an Agent

Agents write code faster than teams can review it, and agent PRs fail differently than human ones. A practical guide to reviewing AI-generated pull requests: the failure modes worth your attention, a review order that catches them, and how to move the work earlier so less of it lands on a human.

• ai-agents
• developer-tools
• engineering-management
• +1

Context Engineering for Coding Agents: A Field Guide

Coding agents fail on context, not capability. A practical guide to context engineering for a real repository: the four layers, a token budget you can reason about, how to diagnose which layer is failing, and how to keep it from going stale.

• ai-agents
• developer-tools
• documentation
• +1

Claude Skills vs. MCP Servers: How to Give a Coding Agent Repository Context

Skills, MCP servers, and CLAUDE.md all load context into a coding agent, but they are not interchangeable. A decision guide to picking the right one - static procedure vs. live data - without bloating the context window or shipping stale answers.

• claude-code
• mcp
• ai-agents
• +1

AGENTS.md Explained: How to Write One File Every Coding Agent Can Read

AGENTS.md is the open standard for giving AI coding agents project context. Learn what it is, how it differs from CLAUDE.md and .cursorrules, and how to write one with a free generator.

• ai-agents
• claude-code
• developer-tools
• +1

MoxieDocs vs DeepDocs: Which Fits Lean Startup Teams Better?

Struggling to keep docs up-to-date with a tiny team? Compare MoxieDocs and DeepDocs to see which AI docs generator saves your engineers time without sacrificing clarity—so you can ship faster.

GitHub Documentation: 7 Tips for Better README Files

Your README is the first impression for contributors and users. Discover 7 actionable tips to make it clear, engaging, and functional—boosting adoption and collaboration on your project.

What Is an Architecture Decision Record? A Complete Guide

An Architecture Decision Record (ADR) clarifies key technical choices for engineering teams. Learn how to document decisions that shape your system’s future—without endless meetings.

Introducing Free: See Moxie Docs Work on Your Own Repo, No Card Required

Moxie Docs now has a permanent Free plan: connect one repository, no credit card required ever, and see real generated docs, search, and live MCP context on your own code.

• product
• announcement
• developer-experience
• +1

8 MCP Documentation Servers to Speed Up Setup

Discover 8 MCP documentation servers that streamline setup for developers, AI tool builders, and technical teams. Improve efficiency with targeted solutions for coding assistants.

Documentation Debt: How to Measure It, Track It, and Pay It Down

Documentation debt compounds like tech debt but almost nobody tracks it. Learn where it comes from, how to score it, and how to set up a ratchet that keeps docs from rotting again.

• documentation
• developer-experience
• engineering-management

7 AI Code Conventions That Keep Models and Teams Aligned

Discover essential AI code conventions that ensure models and development teams stay aligned, improving efficiency and consistency across AI projects. Practical strategies for engineering leaders and teams adopting AI.

MCP Security Risks Explained: Tool Poisoning, Confused Deputies, and the Lethal Trifecta

MCP servers introduce a new attack surface: tool poisoning, rug pulls, confused deputy, and the lethal trifecta. What is real, and how to mitigate it.

• mcp
• ai-agents
• security
• +1

Building an Enhanced MCP Feedback Loop for Coding Agents

Learn how to build an enhanced MCP feedback loop for coding agents. Practical guide to integrating automated testing, linting, and self-correction via MCP servers.

• mcp
• ai-agents
• developer-tools

Best ADR Tools: Managing Architecture Decision Records

Explore the best ADR tools to manage Architecture Decision Records. Compare ADR-Tools CLI, Log4brains, and Moxie Docs, and get a free Markdown ADR template.

• architecture
• documentation
• developer-tools

How to Write the Perfect CLAUDE.md File for Claude Code

Claude Code relies on a CLAUDE.md file for instructions on build, test, and style conventions. Learn how to write, structure, and maintain a perfect CLAUDE.md that keeps your AI agent on track.

• claude-code
• ai-agents
• developer-tools
• +1

Answer Engine Optimization for Developer Docs: How to Get Cited by AI Assistants

Developers now ask AI assistants before they read your docs. Learn how answer engine optimization (AEO) works for documentation: llms.txt, answer-first writing, stable URLs, and why accuracy is the real ranking factor.

• documentation
• ai-agents
• industry-trends

Mermaid Diagrams for Developers: Examples, Syntax, and a Free Live Editor

Learn Mermaid diagram syntax with live flowchart, sequence, ER, class, and state examples. Paste into a free browser Mermaid live editor for instant preview, shareable links, and SVG/PNG export.

• mermaid
• documentation
• developer-tools
• +1

8 Top AI Documentation Tools for Engineering Teams in 2026

Discover the top 8 AI documentation tools for engineering teams in 2026. Compare features, pricing, and ease of use for managers evaluating platforms.

• industry-trends
• documentation

How We Dogfood a Continuous Documentation Workflow to Keep Code, Docs, and AI in Sync

Inside Moxie Docs' own continuous documentation workflow: how we keep code, docs, and AI agent context in sync automatically, and the setup that speeds onboarding.

• documentation
• developer-experience
• engineering-management

Stop Writing Novels in Your Wiki: A Minimal Internal Developer Documentation Template That Survives Change

Why wiki pages rot in fast codebases and how a lightweight, git-backed internal developer documentation template keeps docs accurate without busywork.

• documentation
• developer-experience
• engineering-management