context1000: архитектурные артефакты для ИИ

context1000 schema

Использование ИИ (исскуственного интеллекта) для проектирования и разработки софта прочно вошло в ежедневную рутину. В какой-то момент мне стало понятно, что какой бы ни была мощной LLM (языковая модель), полнота и точность предоставленного контекста играют ключевую роль.

Как продуктовый разработчик, работающий в компании, я почти всегда мыслю о разработке в контексте команды. У нас есть и ревью кода, и формальная документация, но когда дело доходит до генерации кода или его проверки с помощью ИИ, я вижу большую пропасть между умными инструментами и существующей базой знаний. Мне нравится фраза «ИИ не знает, что нужно человеку», и, забавно, с другой стороны наблюдать, как люди ждут всё более совершенные и самостоятельные инструменты.

Начнём!

Документация ТОЛЬКО для ИИ

Не для себя. Не для начальника. Не для человека.

Подход следующий: мы пишем и формулируем нашу документацию только для одного адресата — ИИ. Формулировки в нужных местах могут быть более короткими, а где-то, наоборот, более многословными. Цель одна: улучшить качество работы агента ИИ. Мы плюём на вкусовщину слога и субъективные причёсывания — техническая документация — это промпт!

Почему это важно?

Проверяемость

Когда мы пишем исключительно для ИИ, мы получаем готовую систему обратной связи о качестве: если документация написана плохо, то и ответы будут так себе. Это очень сильное преимущество в практических областях, таких как проверка (codereview) и генерация кода.

Повышение мотивации

Если у вас или у вашего коллеги получилось с помощью документации улучшить работу агента — вы можете этим поделиться. Вклад в калибровку, которую могут проверить другие, на мой взгляд, — лучшая мотивация писать документацию!

Строгий формат

На данный момент документация, ориентированная на ИИ, активно развивается:

Memory bank («кто я и что мы делали раньше?») — долговременная, персонализированная память агента. Помогает улучшить взаимодействие между сессиями.
Context portal («что у нас есть по теме?») — структурированный проектный контекст. Сфокусирован на общей межпроектной документации и поиске.

Хорошо, когда знаешь, что писать. Ещё лучше — как структурировать и почему.

Техническое описание обычно содержит факты, отвечающие на вопросы: «что это?», «как это устроено?» и «как с этим работать?». Другими словами, чаще фиксируются детали решения и в меньшей степени — причины.

Моя концепция документации опирается на четыре типа артефактов: Решения, Правила, Гайды и Проекты. Эти типы документов позволяют отразить как причины появления решений, так и финальные правила и инструкции.

Решения (decisions)

Этот тип артефактов считаю необходимым как раз для описания причин. Я ввожу в техническую документацию два известных формата: RFC и ADR.

RFC (Request for Comments)

RFC (proposal или «предложение») создаётся как раз с целью обозначить, какие варианты технического решения у нас имеются. Для команды полезно зафиксировать причины выбора того или иного решения, а для ИИ это может стать хорошим контекстом ограничений.

Markdown-шаблона RFC:

---
name: 0003-rfc-name           # Unique identifier for the RFC
title: RFC Title              # Human-readable title
status: accepted              # accepted, rejected, draft
tags: [tag1, tag2]            # Categorization tags
related:                      # Cross-references to related documents (one or many)
  rfcs: [0001-rfc-name]       # Related RFCs by name
  adrs: [0001-adr-name]       # Related ADRs by name
  rules: [rule-name]          # Related rules by name
  guides: [guide-name]        # Related guides by name
  projects: [project-name]    # Related projects by name
---

## Summary

Who needs it and what changes in one paragraph.

## Context and problem

Current behavior/limitations, scope of impact.

## Proposed solution

- Architectural idea (1-3 bullet points).
- API/contracts (brief, code block if necessary).
- Data/schema/migrations (one-two sentences).

## Alternatives

Why not X and Y (one sentence per alternative).

## Impact

- Performance/cost
- Compatibility/migrations
- Security/privacy

## Implementation plan

Milestones with estimates: M1, M2, M3. Rollback plan in one sentence.

## Success metrics

How we will understand what worked (numbers/threshold/date).

## Risks and open questions

A short list

Пример того, как размещается RFC в файловой структуре документации, находится тут.

ADR (Architectural Decision Records)

ADR порой очень схожи с RFC, но я настаиваю на их использовании как раз для детального разбора уже выбранного в RFC направления. Подробнее об Architectural Decision Records

Простой markdown-шаблон ADR:

---
name: 0003-adr-name           # Unique identifier for the ADR
title: ADR Title              # Human-readable title
status: accepted              # accepted, rejected, draft
tags: [tag1, tag2]            # Categorization tags
related:                      # Cross-references to related documents (one or many)
  rfcs: [0001-rfc-name]       # Related RFCs by name
  adrs: [0001-adr-name]       # Related ADRs by name
  rules: [rule-name]          # Related rules by name
  guides: [guide-name]        # Related guides by name
  projects: [project-name]    # Related projects by name
---

# ADR Title

## Context

What is the issue that we're seeing that is motivating this decision or change?

## Decision

What is the change that we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?

Стоит отметить, что если команда или компания не приняла RFC/ADR или он завис в состоянии черновика, это тоже может быть полезной информацией для ИИ. ADR в файловой структуре моей концепции можно найти по ссылке.

Правила (rules)

Правила — это утверждения, опирающиеся на решения. Они содержат предложения в повелительном наклонении: что нужно делать и чего не нужно. Создавая правила, следует всегда ссылаться на RFC/ADR и другие типы документов. Этот тип артефактов очень естественен для ИИ и уже активно применяется в таких инструментах, как Cursor в виде правил (rules).

Пример:

---
name: unit-test-frameworks        # Unique identifier for the rule
title: Unit tests framework       # Human-readable title
tags: [tag1, tag2]                # Categorization tags
related:                          # Cross-references to related documents (one or many)
  rfcs: []                        # Related RFCs by name
  adrs: []                        # Related ADRs by name
  rules: []                       # Related rules by name
  guides: []                      # Related guides by name
  projects: []                    # Related projects by name
---

#  Unit tests framework

For all new projects and when updating existing ones:

1. use Vitest as the primary testing framework
2. migrate from Jest to Vitest when possible

Гайды (guides)

Гайды, ссылаясь на правила и решения, описывают детали реализации и использования. Этот формат не так просто довести до шаблона и, скорее всего, от проекта к проекту будет своим. В контексте программных систем этот тип документов может описывать инструкции по использованию модулей и других абстрактных сущностей.

Например, вы решили создать свой набор средств разработки (SDK). В гайдах мы можем разместить документацию для разработчика: как установить, использовать и поддерживать его. Кроме того, мы можем пойти дальше и описывать, как строить целые модули или системы при помощи вашего SDK. Первые кандидаты для этого раздела — файлы README. Что ещё может входить в гайды: описание стека, архитектуры, подходов к разработке, соглашений о кодировании, структурирования проекта и т. д.

Пример содержимого гайда (не является шаблоном):

---
name: auth-quickstart
title: Auth SDK Guide (Short)
status: active
version: 1.0.0
tags: [sdk, auth]
related:
  rfcs: [0001-auth-rfc]
  adrs: [0002-auth-adr]
  rules: [use-oauth2, no-plaintext-secrets]
  guides: []
  projects: [payments]
---

# Auth SDK Guide (Short)

> **Purpose:** Help services obtain and use access tokens via the Auth SDK.  
> **Audience:** Service developers. **Outcome:** A working call authenticated with a bearer token.

## Quick Start

**Requirements**

- Node.js ≥ 20
- `AUTH_BASE_URL`, `AUTH_CLIENT_ID`, `AUTH_CLIENT_SECRET`

**Install**

<code>
npm i @acme/auth-sdk
</code>

**Minimal example**

<code>
import { AuthClient } from "@acme/auth-sdk";

const auth = new AuthClient({
  baseUrl: process.env.AUTH_BASE_URL!,
  clientId: process.env.AUTH_CLIENT_ID!,
  clientSecret: process.env.AUTH_CLIENT_SECRET!,
  timeoutMs: 5000,
  retries: 3
});

const token = await auth.getToken({ scope: "payments:write" });
client.setBearerToken(token.access_token);
</code>

## Configuration

| Key              | Default | Range     | Notes                    |
|------------------|---------|-----------|--------------------------|
| `TIMEOUT_MS`     | 5000    | 1000–15000| HTTP client timeout (ms) |
| `RETRY_ATTEMPTS` | 3       | 0–5       | Exponential backoff      |

## Constraints

- Based on **RFC 0001** and **ADR 0002**.  
- Do not log secrets; mask sensitive fields.  
- Token TTL ≤ 60 minutes; cache in-process only.  
- Rate limit: ≤ 10 RPS per client.

Проекты (projects)

context1000 projects

Раздел Projects (как и папка) содержит документацию по конкретным проектам. Важно отметить, что проекты повторяют ровно такую же структуру, описанную выше: decisions, rules, guides. В заголовке md/mdx-файлов вы можете ссылаться на глобальные артефакты, а также на документы других проектов. Основным отличием является наличие файла project.md в каждой папке проекта.

context1000

context1000 — формат документирования программных систем, разработанный для интеграции с инструментами искусственного интеллекта. Ключевыми артефактами являются ADR и RFC, дополненные формализованными связями между документами.

Данный проект является примером реализации контекстного портала (context portal) и состоит из двух частей:

Формат документирования (@context1000/docs)
Простой RAG (Retrieval Augmented Generation) для данного формата и возможность использовать его локально.

@context1000/docs

В репозитории @context1000/docs вы сможете найти описание концепции и простой шаблон в формате markdown. Если вам нужен готовый портал документации со структурой context1000 — используйте готовые шаблоны (docusaurus, mintlify).

context1000 (RAG)

RAG является отличным способом организации контекстного портала. Он позволяет конвертировать контент документации в формате context1000 в векторную базу данных для организации полнотекстового поиска агентом. Для предоставления доступа агенту используется MCP (Model Context Protocol).

В моей реализации MCP содержит следующие инструменты (tools):

check_project_rules — проверка проектных правил; предусматривает ранний запуск агентом.
search_guides — поиск по гайдам (инструкциям).
search_decisions — поиск по решениям (ADR, RFC).
search_documentation — общий поиск по всем документам; является резервным вариантом.

Заключение

Людям не нужна документация — им нужны ответы.

Две важные идеи:

документация ТОЛЬКО для ИИ — придумывайте более эффективные методы верификации документации.
архитектурные артефакты — давно известные форматы помогают минимизировать шум в содержимом документации.

В данной статье не рассматривались технические детали реализации RAG+MCP для context1000 — вы можете найти весь исходный код в репозитории.