輕量級註解規範，強化人機協作程式碼開發

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

To see all available qualifiers, see our documentation.

A simplified yet effective way to collaborate on code with your favorite AI

License

Uh oh!

There was an error while loading. Please reload this page.

ovidiuiliescu/AiComments

Folders and files

Latest commit

History

Repository files navigation

AI Comments

A lightweight comment convention for better human–AI collaboration in codebases.

Status: Concept / draft convention (tooling can come later)

Table of Contents

What are AI Comments?

AI Comments are designed to sit alongside regular comments.

Notice the difference: regular comments use /* ... /, while AI Comments use /[ ... ]*/ (with brackets).

AI Comments are regular code comments written in a recognizable wrapper format:

The wrapper makes them easy to spot for humans and easy for agents/tools to detect.
Used consistently, AI Comments keep high-signal intent, constraints, and invariants close to the code—reducing back-and-forth and helping humans and AI agents iterate faster with less drift.

Why?

The Convention

Canonical form

The <payload> is plain text. Optionally, the first character can be a control prefix that gives the comment special meaning.

If a prefix is used, write it followed by a space (for example: /[ > Do this ]/, /[ ~ Must always hold ]/).

Meaning of prefixes

Notes:

Examples

The snippets below use simple pseudo-code so the idea stays language-neutral.

1) Rule / invariant (~)

Use ~ for rules the code must follow. Agents should flag when the implementation drifts from the rule.

Violation (should be flagged):

Fixed (rule satisfied):

2) Rationale / constraint context (?)

Use ? to capture crucial extra context: why the code is written this way, and what constraints both humans and agents must respect.

3) Instruction (>) becomes completed (:)

Use > to ask an agent to make a specific change. After the agent completes it, it should flip > to : and ask whether you want the completed comment removed.

Before (agent instruction):

After (agent executed it):

4) Intent (no prefix)

Use an un-prefixed AI Comment for high-signal intent: what the code does and what shape of behavior callers should rely on.

5) Agent-generated AI Comments

AI Comments can also be added by an agent when asked (for example: “add AI Comments that document the invariants and constraints here”).

Before (no AI Comments):

After (agent adds AI Comments):

6) Regular comments and AI Comments together

Regular comments can be detailed and human-friendly; AI Comments should be short, structured, and high-signal.

Notice the difference: the regular comment uses /* ... /, while the AI Comment uses /[ ... ]/ (with brackets).
In practice: humans read the long-form explanation; agents prioritize the compact /[ ? ... ]*/ constraint when making changes.

Where can AI Comments appear?

Anywhere a normal comment can appear:

Equivalents for other languages

The canonical wrapper is:

Conceptually, an AI Comment is “a normal comment containing a bracketed payload”: the host language’s comment delimiter plus a [ … ] wrapper around the payload.

If the host language supports line comments, a line form like //[ <payload> ] (or the closest equivalent) is also acceptable; agents/tools should treat these as equivalent wrappers.

Common equivalents:

Recommended detection patterns (for tooling/agents):

The wrapper may vary by language; the prefix semantics stay the same.

Writing good AI Comments

Wording examples

Good ~ rules are concrete and checkable:

Bad ~ rules are vague and hard to verify:

Good ? rationales capture constraints and trade-offs:

Search & Maintenance

You can get a quick “map” of AI Comments with simple text search (no custom tooling required):

Useful focused searches:

Review hygiene:

Try It Out

The easiest way to get a feel for the concept is to play with the two sample apps in samples/:

To make your agent behave consistently across both samples, copy AICOMMENTS_FOR_AGENTS.md into each sample repo (or otherwise provide it to your agent as repo instructions).

Then try a few prompts with your favorite AI coding agent:

For AI Agents

If you want to use AI Comments in your own projects, you can download/copy AICOMMENTS_FOR_AGENTS.md into your repo and point your AI coding agent at it.

FAQ

Is this a tool/library?
Not yet. It’s a convention that tooling and agents can adopt.

Does this replace normal comments?
No—use it for high-signal intent, invariants, and agent actions.

What if agents ignore it?
Humans still get readable intent. The convention becomes more valuable as tooling improves.

License

MIT — see LICENSE.

About

A simplified yet effective way to collaborate on code with your favorite AI

Resources

License

Uh oh!

There was an error while loading. Please reload this page.

Stars

Watchers

Forks

Releases

Packages

  0

Footer

Footer navigation