A simple standard for disclosing how AI is used in a project.
"AI is encouraged. Just be transparent about how it's used." --Confucius
AIUSE.md is a lightweight, markdown-based convention for transparency in AI usage.
It defines:
- How to declare AI usage policy and contribution guidelines
- Where to store supporting logs (chat transcripts) for disclosure of AI usage
- How to keep humans accountable and fight low quality AI slop
- Add
AIUSE.mdto your project root to define your AI policy [templates] - Add
/aiuse/folders to store AI interaction logs [format] - Optionally override
AIUSE.mdin subfolders if different rules apply
It is not possible to reliably classify whether AI usage is "fair" or "slop" in an automated way. These judgments are inherently subjective. Instead of enforcing rules, this standard promotes transparent disclosure.
Contributors are expected to share the raw AI interactions that influenced their work. This may include chats, prompts, or tool usage logs. Reviewers can then inspect this data and form their own judgment if the AI usage is "fair" based on their own criteria.
The format is designed to be human-readable and easy to review in Git.
This file defines the project's AI usage policy and contribution guidelines.
The primary file should be placed in the project root. If different parts of the project require different rules, AIUSE.md can be overridden in subfolders. There is no strict format for this file. You are encouraged to use the following templates:
This project allows and encourages the use of AI tools. Contributors are expected to disclose
how AI was used according to the spec: https://aiuse.md
If AI tools were used (chats, prompts, agents, etc.), add logs of the interaction under
`/aiuse/` subfolders in the relevant part of the project.
Automatic log exporters for popular AI tools: https://aiuse.md#exportersThis project prohibits any use of AI tools for creating or editing content. All contributions
must be created entirely by a human.
This includes, but is not limited to:
- Chat-based AI systems (e.g. ChatGPT, Claude, Gemini)
- Code generation tools (e.g. GitHub Copilot, Cursor)
- AI writing assistants or paraphrasing tools
- Image, audio, or video generation tools
- Autonomous agents or workflows that produce or modify contentHuman-readable records of interactions with AI tools used to create or modify content.
Logs should be stored under /aiuse/ subfolders in the relevant part of the project, typically alongside the content they were used to create or modify.
Example:
aiuse/
2026-04/
2026-04-28--feature-design--k3f9.md
2026-04-28--feature-design--k3f9--image.jpg
- Each file represents a single AI interaction session
- Filenames follow:
YYYY-MM-DD--topic--rand.md- topic: allowed chars
[a-z0-9-], no consecutive dashes--, max 40 chars - rand: short random string to avoid collisions, allowed chars
[a-z0-9], usually 4 chars
- topic: allowed chars
- Attachments follow:
YYYY-MM-DD--topic--rand--filename.ext- Attachments are optional (images, videos, PDFs, etc.)
- Referenced in the log using
<attachment:filename.ext>tags - filename.ext: allowed chars
[a-z0-9-], no consecutive dashes--, max 40 chars
Example:
### User
Hello, I want to design the checkout feature.
### Assistant
You can approach this by ...
### User
My Stripe API key is <redacted>, will it be protected against abuse?
### Assistant
Yes, since the API key is placed on the server side, users won't have access to it.- Supported roles:
- User: prompts entered by the user
- Assistant: replies generated by the AI assistant
- System: initial instructions or hidden setup (rare)
- Tool: when the assistant runs an external tool (e.g. CLI commands, APIs)
- Replies should remain concise for readability
- Replies appear in chronological order and are not nested
- Replies over 4000 chars should be shortened with
<truncated>or replaced with<attachment> - Replies unrelated to the disclosed interaction topic may be omitted
- Special tags:
<redacted>: removes sensitive information (e.g. secrets, PII)<truncated>: indicates content that was shortened to respect length limits<attachment:filename.ext>: references an external file (e.g. images, videos, PDFs)<changes>: summarizes multi-file modifications by agents
-
Replies should be plain text when possible
-
If a reply contains structured markdown (e.g. headings, lists, tables), it should be wrapped in a
```markdownblock:### User Create bullet points for my presentation ### Assistant ```markdown # Presentation ## Slide 1 * Bullet a * Bullet b * Bullet c ```
-
Code should always be wrapped in
```codeblocks with the appropriate language:### User How do I reverse an ascii string in javascript? ### Assistant ```js function reverse(s) { return s.split("").reverse().join(""); } ```
-
<redacted>: removes sensitive information (e.g. secrets, PII)### User My Stripe API key is <redacted>, will it be protected against abuse?
-
<truncated>: indicates content that was shortened to respect length limits### User What is the full text of Harry Potter? ### Assistant Mr. and Mrs. Dursley, of number four, Privet Drive, were proud to say that they were perfectly normal, thank you very much. They were the last people you'd expect to be involved in anything strange or mysterious, because they just didn't hold with such nonsense.<truncated>
-
<attachment:filename.ext>: references an external file (e.g. images, videos, PDFs)### User Remove the background from this image <attachment:input.jpg> ### Assistant <attachment:output.png>
If the session file was named
2026-04-28--logo-design--a2xz.md, the adjacent attachment files should be named:2026-04-28--logo-design--a2xz--input.jpg2026-04-28--logo-design--a2xz--output.png
Including the adjacent attachment files is optional, if the files are not included, omit the filename:
### User Remove the background from this image <attachment> ### Assistant <attachment>
-
<changes>: summarizes multi-file modifications by agents### User Implement the new authentication flow ### Assistant <changes> - modified: src/auth.ts - modified: src/api/login.ts - created: src/utils/token.ts - deleted: src/old/auth_old.ts </changes>
If the number of changes exceeds 20 files, provide a summary instead of listing individual files:
### User Implement the new authentication flow ### Assistant <changes> - modified: 34 files - created: 2 files - deleted: 7 files </changes>
-
The
Toolrole is used when the assistant runs an external tool (e.g. CLI commands, APIs) -
The input command should be wrapped in a
```codeblock:### User Are the tests passing? ### Assistant Running the test suite ### Tool ```bash npm run test ```
-
Command output is optional and should be wrapped in a consecutive
```textblock:### User Are the tests passing? ### Assistant Running the test suite ### Tool ```bash npm run test ``` ```text > project@1.0.0 test > jest PASS src/utils.test.ts FAIL src/api.test.ts * GET /api/user › should return 200 Expected: 200 Received: 500 Tests: 1 failed, 5 passed ```
-
Input or output over 4000 chars should be shortened with
<truncated>or replaced with<attachment>
Logs can be created manually, but using an automatic exporter is recommended.
Exporters are available for popular AI tools:
If you'd like to contribute to this spec please open a PR in https://github.com/aiusemd/spec
AIUSE.md was created by Tal Kol