APPdAI

APP docs + AI is a convention for a project's service files, aimed at three audiences: the program user, the developer, and the AI agent.

English | Русский

What It Is

APPdAI defines which service files live in a project, what they are called, who they are written for, and when they are updated.

File	For	Contents
AGENTS.md (+ CLAUDE.md)	developer, AI agent	rules, architecture, map, policies
PLAN.md	developer, AI agent	live plan, research, open decisions
CHANGELOG.md	developer, AI agent	history of meaningful changes after adoption, may start from the current version
PATCHNOTES.md	user	version changes in user language
.about.md	developer, AI agent	memory of a code package/directory
.info.md	user	instructions for user-editable files

Only the root agent file is unconditional. The rest appear when the project needs them: a project written for its own author may end up with just the agent file, .about.md, and a CHANGELOG.md - no patch notes, no .info.md.

The convention does not replace self-documenting code or comments. Code shows the letter of the program: what was implemented and how it works. Service files provide spirit and context: why a package exists, what it is related to, which decisions are settled, and which invariants must not be broken.

Available specifications: SPEC.md.

Specifications

APPdAI specifications are versioned as separate variants (v1, v2, etc.) and remain available at the same time. A new specification does not have to replace an older one: the developer chooses which variant to adopt for a project.

Within a variant, the specification carries a minor revision (v1.0, v1.1, etc.): clarifications and additions after which an already adopted project stays valid. A revision does not change the file name or the raw link, so a project only needs to reference the major version - APPdAI v1.

Currently available:

• APPdAI v1, revision v1.1 - baseline service-file convention.

Who It Is For

• Developers who work with AI agents and want the agent to gather context quickly without reading the whole repository blindly.
• Projects with an operator or user: the program ships as a build, the user reads patch notes and edits configs, CSV files, lists, or other data.

How To Use

At the start of a new project, or when adopting the convention in an existing one, give your AI agent a link to the specification:

We use the APPdAI v1 service-file specification.
Read https://raw.githubusercontent.com/anarmus/APPdAI/main/SPEC.v1.md
and implement it in this project following the "Implementation" section.

Raw links:

• English v1: https://raw.githubusercontent.com/anarmus/APPdAI/main/SPEC.v1.md
• Russian v1: https://raw.githubusercontent.com/anarmus/APPdAI/main/SPEC.v1.ru.md

The agent should first study the project, then clarify only the decisions that are not obvious: versioning, root agent file (AGENTS.md/CLAUDE.md), package description style, whether to keep a CHANGELOG.md, and whether the program has a user who needs PATCHNOTES.md at all.

Why These Names

• AGENTS.md is the open agent-instructions format; CLAUDE.md is used by Claude Code as an import or as the main file in Claude-only projects.
• CHANGELOG.md is change history for the developer and agent.
• PATCHNOTES.md is patch notes for the user/operator, when the program has one.
• .about.md is dev/AI package memory.
• .info.md is user documentation for data files.

License

MIT