Skip to content

AGENTS.md

Latest commit

 

History

History
77 lines (70 loc) · 8.26 KB

AGENTS.md

File metadata and controls

77 lines (70 loc) · 8.26 KB
Raw

PIME AI Agent Rules

Welcome to the PIME repository! To maintain high code quality and consistency, all AI agents (Antigravity, Cursor, Windsurf, Aider, etc.) must adhere to the following rules:

1. Initial Context Gathering

  • Read HACKING.txt First: Before proposing architectural changes, adding new features, or modifying IPC logic, you must read the HACKING.txt file at the root of the repository. It contains critical information about the C++ client (TSF) and the Python/Node.js backend server architecture.

2. Modularity, Commits, and Pull Requests

  • CRITICAL - Small, Focused PRs (One Problem at a Time): This is the single most important rule. AI agents often bundle multiple disparate changes into unreviewable, monolithic PRs. You MUST prefer small, highly focused Pull Requests that solve exactly one problem at a time.
    • Single Topic per PR: Never bundle multiple unrelated bug fixes, features, or architectural adjustments into a single PR. If a task or issue involves multiple orthogonal areas, split them into independent, modular PRs. Small PRs ensure fast code review, easy rollback, and clear CI failure isolation.
    • Granular, Incremental Commits: Keep changes strictly scoped. Do not combine unrelated edits into a single commit. When a fix or feature spans multiple modules, break it down into logical, incremental commits where each commit handles an independent step.
    • Strictly Reject Monolithic PRs: Huge, kitchen-sink PRs will be strictly rejected during code review.
  • Isolate Renames and Moves: Keep API renames or file moves/renames in their own dedicated commit/PR. Never mix renames or moves with new feature implementations or bug fixes.
  • Separate Features and Fixes: Never mix bug fixes and new feature implementations. They must always be handled in separate commits and separate Pull Requests.
  • Commit & PR Message Style: Apply the same concise style to both git commit messages and GitHub Pull Requests:
    • Headline / Title: The first line / PR title is a concise headline describing what it does. Include the bug/issue number if available.
    • Blank Line: (For commits) Follow the headline with a blank line.
    • Body (Elaboration): If the headline/title cannot fully describe what it does, elaborate briefly in the body, using concise bullet points if needed. Avoid verbose boilerplate.
    • Rationale (Most Important): Most importantly, explain why the change or fix is needed (if applicable; explain the motivation, context, or root cause).
    • Do NOT literally include labels or section headers like "WHAT:" or "WHY:" in the message.
    • AI Declaration:
      • Commits & Pull Requests (Code): Distinguish the level of human creative contribution for code changes:
        • Human-Architected / Supervised: When a human author provided the design, architecture, API contract, or directed the triage:

          Architecture and design by <Author>. Implementation generated with AI assistance from <Agent> (<Model>).

        • Fully Autonomous: When generated autonomously without human design intervention:

          Fully generated by <Agent> (<Model>) without human intervention.

        • Ambiguous / Undetermined: If the prompt is brief and the agent cannot deduce whether the user considers the architecture theirs, the agent must ask the user to clarify before creating commits or PRs.
      • PR Comments, Discussions & Issues: The "Architecture and design" distinction applies strictly to code. For conversational comments, code reviews, and issue filings, simply append a concise footer declaration (e.g. *(Review comment generated with assistance from Antigravity + Gemini 3.8 Flash)*).

3. Coding Style & Language Guidelines

General Design & Architecture

  • Class Design & SOLID: When adding new classes, prefer following the SOLID principles and favor composition over inheritance.
  • Functions & Modularity: For non-class code, extract smaller helper methods/functions as needed. Prefer smaller, focused functions, and prefer pure functions wherever possible.
  • Readability Over Premature Optimization: Focus on code readability and simplicity, unless a performance gain is obvious. For non-obvious optimizations, always add comments explaining the rationale.
  • API Documentation: Prefer documenting public API usage (classes, methods, functions, and interfaces) with comments or docstrings.

Language-Specific Guidelines

Please stick to the existing coding style for each language in this repository:

  • C++: Follow standard C++ memory management (use smart pointers where applicable). Respect the repository's formatting (check for .clang-format).
  • Rust: Write idiomatic Rust. Always use cargo fmt and check against cargo clippy. Prefer robust error handling with Result over unwrap().
  • Python: For historical reasons, older Python APIs do not follow PEP 8. Keep the legacy naming conventions when interacting with existing code, but stick to PEP 8 in new code where possible. Prefer EAFP (Easier to Ask for Forgiveness than Permission) to write idiomatic, pythonic code rather than defensive checks (unlike C++).
  • Node.js: Follow modern ES6+ syntax and adhere to the existing stylistic patterns in the node/ directory.

4. Common Best Practices

  • Do No Harm: Preserve existing docstrings, comments, and file structures. Do not delete code unless explicitly instructed.
  • No Placeholders: Do not leave // TODO or pass stubs in generated code. Implement the full logic required for the task.
  • Do Not Break the Build: The PIME DLL must support 32-bit (x86), 64-bit (x64), and ARM64 architectures. However, PIMELauncher and the backend servers are deliberately kept x86 to maximize compatibility.
  • OS Compatibility: Minimum supported OS is Windows 10. Do not write backward-incompatible code or use APIs that only work on the latest Windows versions.
  • Comment Languages: In the core framework, use English only. In input method modules, comments in the local language (e.g., zh_TW for a Traditional Chinese IM) are welcomed. Otherwise, default to English.
  • AI Authorship & Copyright in File Headers:
    • New Files:
      • Human-designed with AI implementation: Include human copyright, credit human architecture, and note AI assistance (e.g. PIMETextService/AsyncConnector.cpp): 
        // Copyright (C) 2026 Hong Jen Yee (PCMan) <pcman.tw@gmail.com>
//
// API design and architecture by Hong Jen Yee (PCMan).
// Implementation generated with AI assistance from Google Antigravity (Gemini 3.8 Flash).
      • AI-generated, human-reviewed & integrated: If no prior human design existed, but a human maintainer vetted and accepted the file, attribute the review and specify the project license: 
        // Reviewed and integrated by <Maintainer> <<email>>
// SPDX-License-Identifier: LGPL-2.1-or-later
//
// Generated with AI assistance from Google Antigravity (Gemini 3.8 Flash).
      • Fully autonomous / generated (e.g. tests, lookup tables, scripts): Purely machine-generated code lacks human copyright; do not place a human copyright claim on unauthored code. Release under the project license or public domain: 
        // Generated by Google Antigravity (Gemini 3.8 Flash) without human creative authorship.
// SPDX-License-Identifier: LGPL-2.1-or-later
    • Modifying Existing Files:
      • Never remove, alter, or overwrite existing copyright or license notices from original human authors.
      • Routine fixes (bug fixes, null guards, minor adjustments): Do not modify the file header. Document AI assistance solely in the git commit message.
      • Substantial additions / major rewrites: Keep the original copyright intact and append a short addendum below it acknowledging the addition, the human designer/reviewer, and the AI agent.
  • PR Review Comments & Issues: Any comment, code review, or issue filed with AI assistance must include a footer declaration (e.g. *(Review comment generated with assistance from Antigravity + Gemini 3.8 Flash)*).
  • Unit Testing: Add unit tests as appropriate. While much of the existing codebase is untested, newly written code—especially code generated by AI agents—is strongly encouraged to include unit tests.