# Guidance for AI agents, bots, and humans contributing to Chronicle Software's OpenHFT projects. LLM-based agents can accelerate development only if they respect our house rules. This file tells you: * how to run and verify the build; * what *not* to comment; * when to open pull requests. ## Language & character-set policy | Requirement | Rationale | |--------------|-----------| | **British English** spelling (`organisation`, `licence`, *not* `organisation`, `license`) except technical US spellings like `synchronized` | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. | | **ASCII-7 only** (code-points 0-127). Avoid smart quotes, non-breaking spaces and accented characters. | ASCII-7 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. | | If a symbol is not available in ASCII-7, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. | ## Javadoc guidelines **Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is noise and slows readers down. | Do | Don't | |----|-------| | State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name"). | | Keep the first sentence short; it becomes the summary line in aggregated docs. | Duplicate parameter names/ types unless more explanation is needed. | | Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide. | Pad comments to reach a line-length target. | | Remove or rewrite autogenerated Javadoc for trivial getters/setters. | Leave stale comments that now contradict the code. | The principle that Javadoc should only explain what is *not* manifest from the signature is well-established in the wider Java community. ## Build & test commands Agents must verify that the project still compiles and all unit tests pass before opening a PR: ```bash # From repo root mvn -q verify ``` ## Commit-message & PR etiquette 1. **Subject line <= 72 chars**, imperative mood: "Fix roll-cycle offset in `ExcerptAppender`". 2. Reference the JIRA/GitHub issue if it exists. 3. In *body*: *root cause -> fix -> measurable impact* (latency, allocation, etc.). Use ASCII bullet points. 4. **Run `mvn verify`** again after rebasing. ## What to ask the reviewers * *Is this AsciiDoc documentation precise enough for a clean-room re-implementation?* * Does the Javadoc explain the code's *why* and *how* that a junior developer would not be expected to work out? * Are the documentation, tests and code updated together so the change is clear? * Does the commit point back to the relevant requirement or decision tag? * Would an example or small diagram help future maintainers? ## Project requirements See the [Decision Log](src/main/docs/decision-log.adoc) for the latest project decisions. See the [Project Requirements](src/main/docs/project-requirements.adoc) for details on project requirements. ## Elevating the Workflow with Real-Time Documentation Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to documentation. Ensure the relevant `.adoc` files are updated when features, requirements, implementation details, or tests change. This tight loop informs the AI accurately and creates immediate clarity for all team members. ### Benefits of Real-Time Documentation * **Confidence in documentation**: Accurate docs prevent miscommunications that derail real-world outcomes. * **Reduced drift**: Real-time updates keep requirements, tests and code aligned. * **Faster feedback**: AI can quickly highlight inconsistencies when everything is in sync. * **Better quality**: Frequent checks align the implementation with the specified behaviour. * **Smoother onboarding**: Up-to-date AsciiDoc clarifies the system for new developers. * **Incremental changes**: AIDE flags newly updated files so you can keep the documentation synchronised. ### Best Practices * **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area should prompt reviews and potential updates in the others. * **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from code/tests back to documentation, which should then be reviewed and finalised. * **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier for humans and AI analysis tools. - **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of all artefacts. ## AI Agent Guidelines When using AI agents to assist with development, please adhere to the following guidelines: * **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ASCII-7 guidelines outlined above. Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present in the code or existing documentation. * **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it provides additional context or clarification. * **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's documentation standards before committing it to the repository. ## Company-Wide Tagging This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use the --xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different. Component-specific decisions live in their xxx-decision-log.adoc files. ### Tag Taxonomy (Nine-Box Framework) To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in addition to the existing ALL prefix, which remains reserved for global decisions across every project. .Adopt a Nine-Box Requirement Taxonomy |Tag | Scope | Typical examples | |----|-------|------------------| |FN |Functional user-visible behaviour | Message routing, business rules | |NF-P |Non-functional - Performance | Latency budgets, throughput targets | |NF-S |Non-functional - Security | Authentication method, TLS version | |NF-O |Non-functional - Operability | Logging, monitoring, health checks | |TEST |Test / QA obligations | Chaos scenarios, benchmarking rigs | |DOC |Documentation obligations | Sequence diagrams, user guides | |OPS |Operational / DevOps concerns | Helm values, deployment checklist | |UX |Operator or end-user experience | CLI ergonomics, dashboard layouts | |RISK |Compliance / risk controls | GDPR retention, audit trail | `ALL-*` stays global, case-exact tags. Pick one primary tag if multiple apply. ### Decision Record Template ```asciidoc === [Identifier] Title of Decision Date:: YYYY-MM-DD Context:: * What is the issue that this decision addresses? * What are the driving forces, constraints, and requirements? Decision Statement:: * What is the change that is being proposed or was decided? Alternatives Considered:: * [Alternative 1 Name/Type]: ** *Description:* Brief description of the alternative. ** *Pros:* ... ** *Cons:* ... * [Alternative 2 Name/Type]: ** *Description:* Brief description of the alternative. ** *Pros:* ... ** *Cons:* ... Rationale for Decision:: * Why was the chosen decision selected? * How does it address the context and outweigh the cons of alternatives? Impact & Consequences:: * What are the positive and negative consequences of this decision? * How does this decision affect the system, developers, users, or operations? - What are the trade-offs made? Notes/Links:: ** (Optional: Links to relevant issues, discussions, documentation, proof-of-concepts) ``` ## Asciidoc formatting guidelines ### List Indentation Do not rely on indentation for list items in AsciiDoc documents. Use the following pattern instead: ```asciidoc section:: Top Level Section * first level ** nested level ``` ### Emphasis and Bold Text In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.