Як за 30 хвилин створити вікі проєкту для AI-агентів

Чекліст налаштування поруч із терміналом, де видно дерево теки docs/wiki, і ті самі нотатки у вигляді невеликого графа.

У статті Вікі проєкту: пам'ять, яку AI-агенти вміють читати й писати ми розповіли, що таке наша вікі і навіщо вона потрібна: нова сесія агента читає кілька коротких сторінок і знає, як влаштована система, замість того щоб блукати кодом чи вгадувати. Ця стаття — практична частина. Пройдіть її, і приблизно за 30 хвилин у вашому репозиторії буде робоча вікі.

Коротко: вікі проєкту — це Obsidian-сховище, додане в git-репозиторій, плюс файл правил, який пояснює агенту, як нею користуватися.

Що знадобиться:

  • git-репозиторій з кодом;
  • Claude Code (підійде будь-який агент, що читає файли правил на кшталт CLAUDE.md);
  • Obsidian, безкоштовний, щоб ви й колеги могли зручно читати вікі.

Крок 1. Встановіть Obsidian

Завантажте Obsidian з obsidian.md і встановіть. Obsidian — це редактор Markdown, який працює зі звичайною текою файлів. Теку, яку він відкрив, називають сховищем (vault). Нічого не зберігається в хмарі чи базі даних: ваші нотатки лишаються .md-файлами, які однаково читають git, редактор і агент.

Крок 2. Створіть сховище у репозиторії

Спершу вирішіть, де житиме вікі. Обидва варіанти робочі:

  • Усередині репозиторію коду, наприклад у docs/wiki/. Найпростіше: один репозиторій, а зміна коду та оновлення вікі можуть іти в одному pull request.
  • В окремому репозиторії, склонованому в docs/wiki/ репозиторію коду й доданому в його .gitignore. Зручно, коли вікі часто редагують не розробники або коли одну вікі ділять кілька репозиторіїв коду.

Якщо сумніваєтеся, почніть усередині репозиторію коду. Перенести можна й пізніше.

Створіть теку і підтеки:

mkdir -p docs/wiki/{concepts,features,decisions,conventions,sources}

Тепер відкрийте її в Obsidian. Натисніть іконку профілю сховища внизу ліворуч на бічній панелі (або виконайте Open another vault з палітри команд) і виберіть Manage Vaults.... Поруч з Open folder as vault натисніть Open, виберіть docs/wiki і підтвердіть. (Під час першого запуску Obsidian одразу показує цей самий екран.)

Obsidian створить усередині сховища приховану теку .obsidian/ для своїх налаштувань.

Крок 3. Покладіть її в git

Якщо вікі всередині репозиторію коду, git її вже відстежує. Для окремого репозиторію виконайте git init у docs/wiki/.

Комітьте нотатки й теку .obsidian/, щоб у всіх були однакові налаштування. Але ігноруйте файли розкладки вікон: Obsidian переписує їх щоразу, коли ви відкриваєте нотатку, і вони засмічували б кожен diff. Створіть docs/wiki/.gitignore:

# Розкладка вікон Obsidian, змінюється з кожним кліком
.obsidian/workspace*.json

Крок 4. Навчіть агента формату Obsidian

Markdown в Obsidian має кілька доповнень: [[wikilinks]] між сторінками, callouts і властивості у frontmatter. Репозиторій kepano/obsidian-skills — це набір скілів, які вчать агента цих форматів. Скіл — це короткий файл з інструкціями, який Claude Code підвантажує лише тоді, коли він потрібен.

Встановіть набір просто з Claude Code:

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

Найчастіше вам знадобиться obsidian-markdown. Також у наборі є скіли для Bases (.base), JSON Canvas (.canvas), Obsidian CLI і defuddle, який перетворює вебсторінку на чистий Markdown, щоб зберегти її як джерело.

Крок 5. Запишіть правила для сховища

Скіли вчать формату. Правила вчать змісту: що де лежить і як змінюються сторінки. Збережіть це як docs/wiki/CLAUDE.md і підлаштуйте під свій проєкт. Правила залиште англійською, якщо команда так пише код, або перекладіть — агент зрозуміє обидва варіанти:

# Wiki rules

This folder is the project wiki. Its pages describe how the system works today.
Agents read it before a task and update it after a change. People read it in Obsidian.

## Folders
- `concepts/`: main ideas and parts of the system (billing, users, permissions).
- `features/`: what a user-facing feature does and how it is built.
- `decisions/`: one decision per page: what we chose, why, what we rejected.
- `conventions/`: how we write code here (naming, tests, errors).
- `sources/`: raw input from people (specs, meeting notes). Read only. Never edit.
- `index.md`: the map, one line per page.
- `hot.md`: changes from the last 7 days, newest first.
- `log.md`: one short entry per wiki update.

## Frontmatter
Every page in the four page folders starts with:

```yaml
---
type: concept | feature | decision | convention
status: draft | active | deprecated
sources: []        # links to sources/ pages this page is based on
updated: YYYY-MM-DD
tags: []
---
```

## Writing pages
- A page states the current design on the main branch. One subject per page.
- Rewrite, don't append. When a change makes a sentence false, rewrite that sentence.
  Never add "Update:" or "Changed in ..." sections. History lives in git and log.md.
- Keep every page under 30 KB. Condense or split a bigger one.
- Link related pages with wikilinks, e.g. `[[concepts/billing]]`. Every page links
  to at least one other page, and every link must resolve.
- When code is removed or renamed, turn its page into a short stub:
  `status: deprecated` and one line, `Superseded by [[new-page]]`.
  Never delete a page: old links must keep working.
- A plan that is not built yet is a decision page marked
  "accepted, not yet implemented". Never describe it as current.
- Don't invent. If the code, the sources and the pages don't answer it, ask.

## index.md, hot.md, log.md
- index.md: one line per page, under ~160 characters:
  `- [[concepts/billing]]: how customers are charged`.
- hot.md: one line per change, newest first. Drop entries older than 7 days.
- log.md: append `## [YYYY-MM-DD] update | <title>`, a one-line summary,
  and links to the pages touched.

## Updating the wiki after a code change
1. Read the diff.
2. Find the pages that describe what changed: index.md, then links, then search.
3. Rewrite the sentences the change made false. Add a page only for a new subject.
4. Update index.md, hot.md and log.md.
5. List the pages you touched.

Claude Code підхоплює CLAUDE.md з підтеки, коли працює з файлами в ній, тож ці правила перед очима агента щоразу, коли він торкається вікі.

Крок 6. Пошліть основні правила до вікі

Агент має читати вікі перед кожною задачею, а не лише тоді, коли її редагує. Додайте це в CLAUDE.md у корені репозиторію коду:

## Project wiki
Before a task, read `docs/wiki/index.md` and `docs/wiki/hot.md`,
then open the pages the task needs and follow their links.
The wiki describes how the system should work. If the task conflicts
with a wiki page, stop and ask which one is right.
While coding, treat the wiki as read-only. To change it, follow `docs/wiki/CLAUDE.md`.

Останній рядок важливий. Якщо агент правитиме вікі посеред задачі з кодом, він схильний описувати те, що код мав би робити. Окремий крок оновлення вікі за реальним diff тримає її чесною.

Крок 7. Намалюйте мапу

index.md агент читає першим, тому тримайте його коротким: по рядку на сторінку, згруповано за теками. Для початку:

# Wiki index

Start here. One line per page. Recent changes: [[hot]].

## Concepts
- [[concepts/billing]]: how customers are charged: plans, invoices, retries
- [[concepts/users]]: accounts, roles and sign-in

## Features
- [[features/checkout]]: the path from cart to paid order

## Decisions
- [[decisions/store-money-in-cents]]: amounts are integers in cents, never floats

## Conventions
- [[conventions/testing]]: what we test and where tests live

Також створіть порожні hot.md і log.md з одним заголовком. А ось як виглядає одна сторінка, concepts/billing.md:

---
type: concept
status: active
sources: ["[[sources/pricing-spec]]"]
updated: 2026-10-23
tags: [billing]
---

# Billing

Billing turns a customer's plan into invoices and payments.

## How it works
- Every customer has one active plan. Plans belong to accounts, see [[concepts/users]].
- On the 1st of each month a scheduled job creates an invoice for every paid account.
- The payment provider charges the saved card. A failed charge is retried
  3 times over 7 days, then the account becomes read-only.
- All amounts are integers in cents, see [[decisions/store-money-in-cents]].

## Where it lives in the code
- `src/billing/invoice-job.ts`: the monthly job
- `src/billing/payments.ts`: calls the payment provider

## Related
- [[features/checkout]]: where a plan is first bought

Зверніть увагу, чого на сторінці немає: жодного «додано в березні», жодного списку старих задач. Вона за кілька кілобайтів описує, як білінг працює зараз, а за рештою відсилає посиланнями.

Крок 8. Перший прохід: хай агент створить сторінки

Перші двадцять сторінок не треба писати вручну. Покладіть наявні специфікації чи нотатки в sources/, а потім попросіть агента спершу скласти план, нічого ще не пишучи:

Read docs/wiki/CLAUDE.md. Then explore this repository: the README,
docs/, and the main source folders. Propose 10–20 wiki pages: the main
concepts, the user-facing features, and the conventions you can see.
Show me the list with one line per page. Don't write any pages yet.

Скоротіть чи перейменуйте список, а тоді:

Write the pages we agreed on, following docs/wiki/CLAUDE.md.
Describe only what the code does today. Where you are unsure,
add a "> [!question]" callout instead of guessing. Then fill index.md
and add one log.md entry.

Промпти можна писати й українською — агент зрозуміє. Відкрийте сховище в Obsidian і прочитайте результат. Дайте відповіді на callouts з питаннями й виправте неточності. Окрема увага — рішенням: код показує, що обрали, але майже ніколи не пояснює чому. Найважливіші сторінки рішень напишіть самі або попросіть агента проінтерв'ювати вас про них.

Закомітьте результат, як будь-яку іншу зміну.

Крок 9. Тримайте вікі правдивою після кожної зміни

Неправдива вікі гірша, ніж жодної: агент їй вірить. Тож зробіть одну звичку частиною робочого процесу: щойно зміну переглянули на рев'ю, попросіть агента привести вікі у відповідність до неї.

Read docs/wiki/CLAUDE.md, then the diff of <branch, pull request or commit range>.
Update every wiki page this change made false. Add a page only for a new subject.
Update index.md, hot.md and log.md, then list the pages you touched.

А потім переглядайте diff вікі так само, як код:

git diff -- docs/wiki

Перевірте, що речення переписані, а не дописані; що жодна сторінка не описує код, якого вже немає; і що агент не вигадав якесь «чому». Якщо вікі в репозиторії коду, цей diff іде в той самий pull request, що й зміна. Якщо в окремому — у власний невеликий pull request.

Крок 10 (необов'язковий). Перевірка вікі лінтером

Раз на кілька тижнів просіть агента перевірити стан вікі:

Lint the wiki in docs/wiki. List broken [[links]], pages over 30 KB,
pages with missing frontmatter, pages not listed in index.md, pages
nothing links to, and claims that contradict each other or the code.
Don't fix anything yet.

Механічні перевірки легко оформити скриптом і запускати в CI чи pre-commit хуку. Мінімальна версія на Python для розміру сторінок і битих посилань:

# wiki_lint.py: python3 wiki_lint.py docs/wiki
import re, sys
from pathlib import Path

root = Path(sys.argv[1])
pages = {p.relative_to(root).with_suffix("").as_posix(): p for p in root.rglob("*.md")}
names = {Path(key).name for key in pages}
problems = 0

for key, path in sorted(pages.items()):
    text = path.read_text(encoding="utf-8")
    size = len(text.encode("utf-8"))
    if size > 30_000:
        print(f"{key}: {size // 1000} KB, over the 30 KB limit")
        problems += 1
    prose = re.sub(r"```.*?```|`[^`\n]*`", "", text, flags=re.S)  # пропускаємо код
    for link in re.findall(r"\[\[([^\]|#]+)", prose):
        target = link.strip().removesuffix(".md")
        if Path(target).suffix:  # зображення та інші вкладення
            continue
        if target not in pages and target not in names:
            print(f"{key}: broken link [[{target}]]")
            problems += 1

print(f"{len(pages)} pages, {problems} problems")
sys.exit(1 if problems else 0)

Питання, що потребують судження, як-от суперечності та застарілі твердження, залиште агенту й собі.

От і все

Obsidian-сховище в git, два файли правил, мапа й одна звичка після кожної зміни. Ніщо з цього не прив'язане до конкретного інструмента, і почати можна з малого: навіть двадцять добрих сторінок рятують агента від багатьох здогадок. Якщо хочете зрозуміти, навіщо кожне з правил, прочитайте супровідну статтю.

Усі статті