Stop ignoring shared agent documents in .gitignore
This commit is contained in:
Jan Doubravský
@@ -0,0 +1,101 @@
|
||||
# AI Agents - Project Rules
|
||||
|
||||
**Document Version:** v6 (independent, incremented on structural changes)
|
||||
|
||||
Language-agnostic rules for AI assistants (Claude Code, Cursor, Copilot, etc.).
|
||||
|
||||
Everything language-specific — package manager, formatter, linter, test framework,
|
||||
logging library, line length, project layout — lives in the matching design document:
|
||||
|
||||
| Project type | Design document |
|
||||
|--------------------|------------------------------|
|
||||
| Python application | `DESIGN_DOCUMENT.md` |
|
||||
| Python library | `DESIGN_DOCUMENT_MODULE.md` |
|
||||
| Rust application | `DESIGN_DOCUMENT.md` |
|
||||
| Rust library | `DESIGN_DOCUMENT_LIB.md` |
|
||||
| Godot | `DESIGN_DOCUMENT_GODOT.md` |
|
||||
|
||||
Where this file and a design document disagree, **the design document wins**.
|
||||
|
||||
## First-time setup
|
||||
|
||||
- **On first read of this file, immediately read all other `.md` files in the project root** (e.g. `PROJECT.md`, `CHANGELOG.md`, `DESIGN_DOCUMENT*.md`) to get full project context before starting any task.
|
||||
|
||||
## Language
|
||||
|
||||
- **Always write all documentation in English**
|
||||
|
||||
## Dependency Management
|
||||
|
||||
- **Always add and remove dependencies through the package manager CLI** — **never edit the manifest** (`pyproject.toml`, `Cargo.toml`, …) by hand
|
||||
- The exact commands are in the design document for the given language
|
||||
|
||||
## Project Structure
|
||||
|
||||
- Source code, tests and detailed documentation each have their own directory — the concrete layout is in the design document
|
||||
- Detailed documentation belongs in `docs/`, never in the project root
|
||||
- The project root holds only the core documents: `README.md`, `AGENTS.md`, `DESIGN_DOCUMENT*.md`, `PROJECT.md`, `CHANGELOG.md`
|
||||
- Entry points follow the language convention; a project may have several
|
||||
- The dependency/build directory (`.venv/`, `target/`, …) is tool-managed — do not copy it, do not generate it by hand
|
||||
|
||||
## Code
|
||||
|
||||
- **Always use static typing** — annotate every parameter and return value
|
||||
- Format and lint with the tools named in the design document
|
||||
- **Nothing is committed without a clean formatter, linter and test run**
|
||||
|
||||
## Testing
|
||||
|
||||
- Use the test framework named in the design document — never a second framework alongside it
|
||||
- Arrange-Act-Assert pattern
|
||||
- Test naming: `test_<action>_<context>`
|
||||
|
||||
## Logging
|
||||
|
||||
- Use the logging library named in the design document — **never `print()` (or its language equivalent) for debugging**
|
||||
- Never log secrets, passwords, tokens, or API keys
|
||||
|
||||
## Environment and Secrets
|
||||
|
||||
- Applications store secrets in `.env` and load them at runtime — **never commit `.env`**
|
||||
- Debug mode is driven by an `ENV_DEBUG=true/false` flag
|
||||
- Libraries do not read `.env` — configuration is passed in by the caller
|
||||
|
||||
## Git
|
||||
|
||||
- `.gitignore` must cover at least: the dependency/build directory, tool caches, and `.env`
|
||||
- **Commit the lock file for applications, do not commit it for libraries**
|
||||
- **Never commit shared documentation** (`AGENTS.md`, `DESIGN_DOCUMENT*.md`) — it comes from the documentation repository, not from the project
|
||||
- `README.md`, `PROJECT.md` and `CHANGELOG.md` **are committed** — they are project-specific
|
||||
|
||||
### Commit messages
|
||||
|
||||
- **Never sign commits with AI authorship** — no `Co-Authored-By: Claude` (or any other assistant), no "Generated with …" line, no tool name or emoji footer. The same applies to pull request descriptions and issue comments.
|
||||
- The commit author is the human running the tool; the message describes the change, nothing else
|
||||
- Single-line verbal style — "Add X", "Fix Y", "Refactor Z" — never a filename-style message
|
||||
- Written in English
|
||||
|
||||
## Versioning
|
||||
|
||||
- Follow semantic versioning (MAJOR.MINOR.PATCH)
|
||||
- **Always ask user before bumping version** — never increase version automatically
|
||||
- **Keep `CHANGELOG.md` updated** — document all significant changes as they are made
|
||||
- Update `CHANGELOG.md` **before** the version bump
|
||||
- The version source of truth is the project manifest (`pyproject.toml`, `Cargo.toml`, `project.godot`)
|
||||
|
||||
## Task Management
|
||||
|
||||
Tasks are **single-line comments in the code**, written with Todo Tree tags:
|
||||
|
||||
| Tag | Meaning |
|
||||
|----------|--------------------------------------------------|
|
||||
| `TODO:` | work still to be done |
|
||||
| `FIXME:` | something broken that must be repaired |
|
||||
| `BUG:` | a known defect, not fixed yet |
|
||||
| `HACK:` | temporary workaround, needs rewriting |
|
||||
| `NOTE:` | important context for whoever reads this next |
|
||||
|
||||
- **No checkboxes and no numbered task lists in documentation** — the code is the task list
|
||||
- `PROJECT.md` carries only cross-cutting tasks that have no single place in the code
|
||||
- If a tag already exists at a location in code, do not repeat it in `PROJECT.md`
|
||||
- **Update documentation** — when completing changes, update the relevant sections of `PROJECT.md` and `CHANGELOG.md`
|
||||
Reference in New Issue
Block a user