A simple documentation workflow for AI agents.

For setup instructions, skip to the How to setup SimpleDoc in your repo section.

If you have used AI agents such as Anthropic’s Claude Code, OpenAI’s Codex, etc., you might have noticed their tendency to create markdown files at the repository root:

...
├── API_SPEC.md
├── ARCHITECTURE.md
├── BACKLOG.md
├── CLAUDE.md
├── CODE_REVIEW.md
├── DECISIONS.md
├── ENDPOINTS.md
├── IMPLEMENTATION_PLAN.md
├── NOTES.md
├── QA_CHECKLIST.md
├── SECURITY_PLAN.md
└── src/
└── ...
├── TEST_COVERAGE.md
├── TEST_REPORTS.md
├── TEST_RESULTS.md
...

The default behavior for models as of writing this in December 2025 is to create capitalized Markdown files at the repository root. This is of course very annoying, when you accidentally commit them and they accumulate over time.

The good news is, this problem is 100% solvable, by using a simple instruction in your AGENTS.md file:

**Attention agent!** Before creating ANY documentation, read the docs/HOW_TO_DOC.md file first. It contains guidelines on how to create documentation in this repository.

But what should be in docs/HOW_TO_DOC.md file and why is it a separate file? In my opinion, the instructions for solving this problem are too specific to be included in the AGENTS.md file. It’s generally a good idea to not inject them into every context.

To solve this problem, I developed a lightweight standard over time, for organizing documentation in a codebase. It is framework-agnostic, unopinionated and designed to be human-readable/writable (as well as agents). I was surprised to be not able to find something similar enough online, crystallized the way I wanted it to be. So I created a specification myself, called SimpleDoc.

Basically, it tells the agent to

1. Create documentation files in the docs/ folder, with YYYY-MM-DD prefixes and lowercase filenames, like 2025-12-22-an-awesome-doc.md, so that they will by default be chronologically sorted.
2. Always include YAML frontmatter with author, so that you can identify who created it without checking git history, if you are working in a team.
3. The exception here are timeless and general files like README.md, INSTALLATION.md, AGENTS.md, etc. which can be capitalized. But these are much rarer, so we can just follow the previous rules most of the time.

Here is your call to action to check the spec itself: SimpleDoc.

How to setup SimpleDoc in your repo

Run the the following command in your repo root, just paste it in your terminal and press enter:

bash <<'EOF'
set -euo pipefail

AGENTS_FILE="AGENTS.md"
DOCS_DIR="docs"
DOC_URL="https://raw.githubusercontent.com/osolmaz/SimpleDoc/refs/heads/main/docs/HOW_TO_DOC.md"
DOC_OUT="${DOCS_DIR}/HOW_TO_DOC.md"

LINE="**Attention agent!** Before creating ANY documentation, read the docs/HOW_TO_DOC.md file first. It contains guidelines on how to create documentation in this repository."

if [[ ! -f "${AGENTS_FILE}" ]]; then
echo "Error: ${AGENTS_FILE} not found (run this from repo root)." >&2
exit 1
fi

if ! grep -Fqx "${LINE}" "${AGENTS_FILE}"; then
printf '\n%s\n' "${LINE}" >> "${AGENTS_FILE}"
fi

mkdir -p "${DOCS_DIR}"

RAW_URL="${DOC_URL}"
if [[ "${DOC_URL}" == https://github.com/*/blob/* ]]; then
RAW_URL="${DOC_URL/https:\\/\\/github.com\\//https:\\/\\/raw.githubusercontent.com\\/}"
RAW_URL="${RAW_URL/\\/blob\\//\\/}"
fi

tmp="$(mktemp)"
trap 'rm -f "${tmp}"' EXIT
curl -fsSL "${RAW_URL}" -o "${tmp}"
mv "${tmp}" "${DOC_OUT}"
trap - EXIT
EOF

It basically adds the line above to your AGENTS.md file, downloads HOW_TO_DOC.md from the SimpleDoc repository and saves it to your docs/HOW_TO_DOC.md file. The file itself contains further instructions to setup personal preferences (only once) the next time it decides to document something. Any new documentation after that point should follow the SimpleDoc specification and show up in the docs/ folder with proper timestamps and author information.

If you run into issues with the workflow or have suggestions for improvement, you can email me at [email protected].

Happy documenting!