AGENTS.md

AGENTS.md

This repository contains overall-facing ClickHouse knowledge base articles. Optimize for correctness, safety, and reviewability. Do not optimize for large rewrites, cosmetic churn, or generic prose improvement.

Start here: read the style guide before writing

Before drafting or substantially rewriting an article, read these. They are short — under 300 lines in total — and they encode the house style that this file only summarizes:

File	What it gives you
.claude/skills/altinity-kb-article-writer/SKILL.md	The authoring workflow, start to finish
.claude/skills/altinity-kb-article-writer/references/kb-style-guide.md	Frontmatter defaults, structure, tone
.claude/skills/altinity-kb-article-writer/references/article-template.md	The baseline article shape, plus a minimal variant
.claude/skills/altinity-kb-article-writer/references/section-map.md	Which section an article belongs in
.claude/skills/altinity-kb-article-writer/references/qa-checklist.md	Self-review before you hand the work back

Claude Code loads this directory as a skill automatically. Codex and other tools do not — read the files directly. Do not rely on inspecting neighbouring articles instead: sampling nearby files tells you the frontmatter shape but not the tone or length norms, which is where drafts most often go wrong.

Mission

When modifying an article, do all of the following:

• preserve useful existing content;
• fix concrete factual, safety, or version-compatibility problems;
• add missing information only when it materially helps operators;
• keep the diff narrow enough that a maintainer can review it quickly.

Do not turn a focused article review into a full rewrite.

Default workflow

1. Read the entire article before proposing any change.
2. Read related issues, PRs, and review comments for the same article.
3. Check upstream ClickHouse documentation and changelog for the version ranges that matter.
4. Search upstream GitHub issues/PRs only for rare or specific edge cases that deserve extra explanation.
5. Produce findings first, then a minimal patch.
6. Do not open a public issue or PR before a human has read the proposal, unless explicitly instructed.

If the article is mostly correct, prefer a precise issue note or a very small patch over a broad rewrite.

Non-negotiable rules

• Prefer point fixes over rewrites.
• Keep existing structure unless the structure itself is broken.
• Do not remove useful operational detail unless it is wrong, obsolete, dangerous, or duplicate.
• Do not replace product documentation. Extend it only where the KB adds operational value.
• Every added paragraph, table, query, or command must answer a concrete operator question.
• Every non-obvious factual claim must have a source.
• Every behavior claim must have explicit version scope.
• Every recipe must be copy-pasteable and tested, or it should stay out of the article.
• Every destructive action must be preceded by an explicit warning.
• No public-facing PR should be generated automatically from an unreviewed draft.

What a good KB edit looks like

A good edit usually does one or more of the following:

• corrects a factual statement;
• adds exact version boundaries;
• adds a tested, high-value recipe;
• adds a warning before a dangerous action;
• clarifies an edge case seen in upstream issues;
• shortens or improves references without changing meaning.

A bad edit usually does one or more of the following:

• rewrites most of the article without necessity;
• replaces specific operational detail with generic prose;
• adds queries that are not tested;
• adds queries that only work on newer versions without saying so;
• introduces claims based on behavior that was later reverted or rolled back;
• adds filler such as obvious prerequisites with no concrete payoff;
• adds monitoring queries that do not provide materially new information;
• adds recovery instructions without clearly stating corruption or duplication risks.

Source hierarchy

Use sources in this order:

1. Upstream ClickHouse documentation.
2. Upstream ClickHouse changelog / release notes.
3. Upstream code or comments when documentation is insufficient.
4. Upstream GitHub issues and PRs for specific rare cases.
5. Existing KB issues/PRs for repository context.

Rules for using sources:

• Use GitHub issues/PRs to explain rare cases, not to redefine normal behavior.
• Treat issue comments as situational evidence unless corroborated.
• If a behavior changed and later changed back, document the exact historical window instead of presenting it as current behavior.
• If you cannot verify a claim, do not promote it into the article.

Versioning rules

Every behavior claim must answer all three questions:

1. Which versions does this apply to?
2. Is this current behavior or historical behavior?
3. Was the behavior later reverted, replaced, or removed?

Version guidance:

• State explicit version ranges whenever compatibility matters.
• If a query relies on columns or functions added later, annotate the minimum supported version or provide a fallback query.
• If compatibility is messy and not worth documenting inline, keep the article on the main supported behavior and move the edge case to a note.
• Never silently mix examples from incompatible versions.

Query and command rules

Only add a query or command if it satisfies all of the following:

• it solves a concrete operator task;
• it has a short explanation of what it detects or helps decide;
• it was tested on a representative ClickHouse version, or compatibility is explicitly documented;
• it does not rely on unsupported assumptions about schema, functions, or output columns.

For every recipe, include enough context to make it usable:

• purpose;
• version scope if needed;
• how to interpret the output;
• safety note if destructive or risky;
• fallback or limitation if known.

Hard constraints for SQL examples

• Do not add a query that uses version-specific columns without noting that fact.
• Do not add a query that uses helper functions unavailable on common target versions.
• Do not add a helper query without explaining what it detects and why a reader would need it.
• Do not add a second query that merely repeats information already shown by a prior query unless it is explicitly framed as monitoring, alerting, or dashboard input.
• Prefer generating statements for review first; execution should be a separate, deliberate step.

Compatibility policy

If a query is useful but not portable:

• add a minimum-version note; or
• provide an alternate query for older versions; or
• omit it from the article and keep it in review notes instead.

Untested queries do not belong in the KB.

Safety rules for destructive operations

Destructive operations require extra care. This includes SQL commands such as DROP DETACHED, filesystem deletion, and recovery/attach flows that can duplicate or corrupt data when misused.

Rules:

• Put a warning block immediately before destructive or potentially destructive commands.
• State the concrete risk: data loss, duplication, replica divergence, or unsafe cleanup.
• Tell the reader to review generated commands before executing them.
• Prefer documented SQL workflows over ad-hoc filesystem deletion when the product supports them.
• If filesystem operations are still needed, present them as last-resort steps and explain why.
• Do not describe a risky recovery path as "safe" or "recovered" unless the preconditions are explicit.

Use this Hugo warning pattern:

{{% alert title="Warning" color="warning" %}}
Review generated commands carefully before executing them. Destructive actions can cause data loss, duplication, or replica inconsistency if used incorrectly. Ensure you have a valid backup and understand why each target object is safe to remove or attach.
{{% /alert %}}

Article-writing rules

• Keep the original article voice and purpose.
• Prefer dense, operational wording over "better sounding" prose.
• Remove empty words.
• Do not add text that only restates the obvious.
• If you add a prerequisite, explain the exact failure mode it prevents.
• Use tables only when they compress real information.
• Keep appendix/reference links readable; avoid dumping long raw URLs into the body when a shorter reference style works.

Length budget

KB articles are short by design. Across the 250 articles in content/en, the median is about 430 words and 90% are under 1100.

• Target: under 1000 words.
• Over 1500 words needs a clear reason. Only 13 of 250 articles are that long.
• One closing ## Related resources section. Do not also add a separate references list.

Check before you finish:

wc -w content/en/<section>/<file>.md

If an article runs long, the cause is usually explanation that belongs in a commit message or a PR description rather than in the KB: mechanism write-ups, source-code walkthroughs, stack traces, or evidence tables justifying a claim. State the operational rule and the version it applies to; leave out the derivation. A reader needs to know what to do and when it breaks, not why the internals behave that way.

Specific guidlines from other reviews (human add here)

These are repository-specific lessons and should guide similar edits:

• Do not turn a useful but imperfect article into a prettier, less useful rewrite.
• Do not add "problems" just because the prompt asked to find them; only report real defects.
• Do not add historical behavior as present-day guidance without exact version boundaries.
• Do not add queries that depend on later-added fields or functions unless the article is version-scoped.
• Do not add a query unless you can explain exactly what it detects.
• Do not add asynchronous-metric queries as if they add new investigative detail when they only repeat inventory information; they are valid mainly for dashboards and alerting.
• Do not include obvious prerequisites unless the article explains their concrete operational impact.
• Do not present ATTACH / recovery recipes in a way that could lead to duplicate data without a strong warning and explicit preconditions.
• Do not merge or publish a draft that the human owner has not read.
• Never remove ® from ClickHouse® unless it is technically impossible in the target format or an established repository convention explicitly omits it.

Output format for article reviews

When asked to review or modify an article, return work in this order:

1. Findings

A compact list or table with:

• section / heading;
• exact problem;
• why it matters;
• source;
• proposed minimal fix.

2. Patch plan

Describe the smallest useful set of edits.

3. Patch

Provide a ready-to-apply Markdown diff or replacement blocks.

4. Validation notes

State explicitly:

• versions checked;
• sources used;
• queries tested;
• any assumptions not fully verified.

5. Risk notes

Call out anything destructive, compatibility-sensitive, or potentially misleading.

Decision rules: issue vs patch vs no change

Choose the lightest valid outcome.

• No change: the article is already correct enough and proposed edits are cosmetic.
• Issue / review notes: there are factual questions or useful ideas, but they are not fully validated.
• Small patch: the change is narrow, source-backed, and tested.
• Larger patch: only when the article has real structural problems and the rewrite is justified with a reviewable rationale.

Default to smaller.

Review questions

The checklist below catches mechanical problems. These questions catch the ones that matter more. Answer them against the actual draft, not from memory, before handing work back.

Does the reader need this?

• Is it simple enough, but not simpler?
• Does this detail change what the user should do?
• Can this be explained with a simple example instead of implementation internals?
• Is there anything here the reader simply doesn't need to know?

Mechanism write-ups, source-code walkthroughs, and evidence tables almost always fail these. Being able to explain why the internals behave a certain way is not a reason to put it in the article. Put it in the pull request instead, where a reviewer wants it.

Is it true?

• How do you know this example actually works? Name the version and environment you ran it on. "It should work" is not an answer.
• Is every example copy-pasteable and tested? If you reformatted a tested example, it is no longer tested — run it again.

Is it enough?

• Does it solve the user's problem end-to-end?

This last question is the counterweight, and it carries as much weight as the other six combined. Everything above pushes toward cutting; only this one pushes toward keeping. Applied without it, the questions will happily strip an article down past useful. A warning that looks like an internals digression but changes what an operator configures is not a digression — it is the article. Cut derivations, not decisions.

Final checklist

Before finishing, verify all of the following:

• The full article was read.
• Related repo discussion was read.
• Version-sensitive claims are scoped.
• Historical behavior is labeled as historical.
• Added queries were tested or explicitly version-gated.
• Every query has a reason to exist.
• Destructive actions have warnings.
• Useful existing detail was not accidentally removed.
• The diff is reviewable.
• A human can verify each important claim quickly.
• The style guide was read before drafting.
• The article is within the length budget, or the reason it is not is stated.
• The review questions above were answered against the draft.

If any item above fails, reduce scope or stop at findings instead of forcing a patch.