Agent-friendly documentation

"Docs to teach an AI about the project" ends up looking identical to "docs to teach a new teammate". Two audiences, one benefit.

1. CLAUDE.md / AGENT.md — top-level entry

# Warragon

Monorepo — Next.js · Spring · FastAPI · Tauri · PostgreSQL.

## Services
| Name | Path | Stack |
|---|---|---|
| pryzeet | frontend/pryzeet | Next 16 · TypeORM |
| admin   | frontend/admin   | Next 16 · 5 PG pools |

## Docs structure
- docs/RULES.md     — global rules
- docs/shared/*.md  — tech standards (SSOT)
- docs/agent/{svc}/ — Claude instructions per service
- docs/service/{svc}/— product/ops docs

First 10 lines should reveal "what is this and where to find things".

2. RULES.md — global absolute rules

## §1. Package manager
Frontend = pnpm. Python = uv. No npm/yarn/pip/poetry.

## §2. No AI credits in commits
❌ "Co-Authored-By: Claude"

## §4. SQL = SSOT
CREATE IF NOT EXISTS only. No DROP. No permanent ALTER files.

Numbered sections for easy reference.

3. rules.md per service — only what's unique

# codingstairs — absolute rules

Global rules in RULES.md. This file only covers codingstairs specifics.

## §1 SQL location
Schema SSOT: frontend/admin/sql/codingstairs/*.sql

## §8 i18n
next-intl 4.11 · ko default + /en/*

No duplication.

4. features/ folder

docs/agent/codingstairs/features/
├── notes.md
├── edu.md
└── contact.md

For "edit blog" requests, load only features/notes.md to save tokens.

5. Skill / agent prompts

---
name: warragon-codingstairs
description: When working on codingstairs (notes/edu/portfolio CMS).
  Next 16 + next-intl · pg direct · 7 tables.
  TRIGGER — codingstairs, frontend/codingstairs, notes, blog.
---

# Entry docs
1. docs/agent/codingstairs/rules.md
2. docs/agent/codingstairs/shared.md

Auto-loaded on task start; also reads well to humans.

6. Good docs traits

Scannable (h2/h3)
Examples (abstract + one concrete block)
Explicit links (relative, validated)
Up to date (update in same PR)
Short (< 2000 words, split when longer)

7. Bad docs traits

Whole-code quotes
Full field dumps (open the file)
Verbose explanations — three sentences suffice
Too many screenshots — they rot fast

8. Docs folder contract

docs/
├── RULES.md           — global (~30min cadence)
├── shared/*.md        — standards (~quarter)
├── agent/             — AI instructions (~month)
└── service/           — product/ops (~week/day)

Split by update frequency, audience, purpose.

9. Automated validation

grep -rn '\[.*\](.*\.md)' docs/ | while read line; do
  path=$(echo "$line" | sed 's/.*(\(.*\.md\)).*/\1/')
  [ -f "$path" ] || [ -f "docs/$path" ] || echo "BROKEN: $line"
done

Block broken links in CI.

10. CHANGELOG

## 2026-05-06 (56) — notes · courses expansion
- 5 new notes topics
- admin-platform course seeded

Every entry: date (num) — title + context + changes. AI answers "what changed last week?" directly.

11. Gotchas

Writing docs once and forgetting them
Everything stuffed in README → unscrollable
Treating them as formal papers → informal TODO notes are fine
Overusing Mermaid — a text table often works

12. Real scale (warragon)

200+ markdown files
15 Claude skills
9 services each with agent/ + service/

Maintenance overhead is real — but AI finding its own context is the payoff.

Closing

Agent-friendly docs = human-friendly docs that read fast. You don't need to over-document for AI; good docs for people are already good for AI.

philosophy/06-docs-for-agent-and-human
agent-tooling/09-claude-md-pattern