From 35fedbd57d6fddf619f02cceb3ac9fd23b614f7b Mon Sep 17 00:00:00 2001 From: "Toast (gastown)" Date: Sat, 16 May 2026 19:11:06 +0000 Subject: [PATCH 1/8] feat: add Russian language support to Astro configuration --- astro.config.mjs | 372 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 251 insertions(+), 121 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index 8439519..d1f225a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -4,7 +4,238 @@ import starlight from "@astrojs/starlight"; import catppuccin from "@catppuccin/starlight"; import sitemap from "@astrojs/sitemap"; -// https://astro.build/config +const enSidebar = [ + { + label: "Introduction", + items: [ + { + label: "What is Agentic Engineering?", + slug: "introduction/what-is-agentic-engineering", + }, + { + label: "How Agents Work", + slug: "introduction/how-agents-work", + }, + { + label: "Working with Agents", + slug: "introduction/working-with-agents", + }, + { + label: "Trends & Patterns", + slug: "introduction/trends-patterns", + }, + ], + }, + { + label: "For Engineers", + items: [ + { label: "Getting Started", slug: "engineers/getting-started" }, + { + label: "Task Decomposition", + slug: "engineers/task-decomposition", + }, + { label: "Best Practices", slug: "engineers/best-practices" }, + ], + }, + { + label: "For Team Leads", + items: [ + { + label: "Adopting Agentic Tools", + slug: "team-leads/adopting-agentic-tools", + }, + { + label: "Measuring Impact", + slug: "team-leads/measuring-impact", + }, + { + label: "Quality Assurance", + slug: "team-leads/quality-assurance", + }, + { + label: "The 1-Pizza Team", + slug: "team-leads/1-pizza-teams", + }, + ], + }, + { + label: "For Executives", + items: [ + { label: "Strategic Vision", slug: "executives/strategic-vision" }, + { label: "ROI Frameworks", slug: "executives/roi-frameworks" }, + { + label: "Adoption Playbook", + slug: "executives/adoption-playbook", + }, + { + label: "Security & Compliance", + slug: "executives/security-compliance", + }, + { + label: "AI-Native Economics", + slug: "executives/ai-native-economics", + }, + ], + }, + { + label: "Use Cases by Phase", + items: [ + { + label: "Planning & Design", + slug: "use-cases/planning-design", + }, + { label: "Implementation", slug: "use-cases/implementation" }, + { + label: "Deployment & Operations", + slug: "use-cases/deployment-operations", + }, + { + label: "Quality & Documentation", + slug: "use-cases/quality-documentation", + }, + ], + }, + { + label: "Governance & Risk", + items: [ + { label: "Security Review", slug: "governance/security-review" }, + { label: "Accountability", slug: "governance/accountability" }, + { label: "Quality Gates", slug: "governance/quality-gates" }, + ], + }, + { + label: "Appendices", + items: [ + { label: "Glossary", slug: "appendices/glossary" }, + { label: "Recommended Reading", slug: "appendices/reading-list" }, + { label: "Prompt Templates", slug: "appendices/prompt-templates" }, + ], + }, + { + label: "Community", + items: [ + { label: "Join the Community", slug: "community" }, + { label: "Contributing", slug: "community/contributing" }, + ], + }, +]; + +const ruSidebar = [ + { + label: "Введение", + items: [ + { + label: "Что такое агентная инженерия?", + slug: "introduction/what-is-agentic-engineering", + }, + { + label: "Как работают агенты", + slug: "introduction/how-agents-work", + }, + { + label: "Работа с агентами", + slug: "introduction/working-with-agents", + }, + { + label: "Тенденции и закономерности", + slug: "introduction/trends-patterns", + }, + ], + }, + { + label: "Для инженеров", + items: [ + { label: "Начало работы", slug: "engineers/getting-started" }, + { + label: "Декомпозиция задач", + slug: "engineers/task-decomposition", + }, + { label: "Лучшие практики", slug: "engineers/best-practices" }, + ], + }, + { + label: "Для тимлидов", + items: [ + { + label: "Внедрение агентных инструментов", + slug: "team-leads/adopting-agentic-tools", + }, + { + label: "Измерение влияния", + slug: "team-leads/measuring-impact", + }, + { + label: "Обеспечение качества", + slug: "team-leads/quality-assurance", + }, + { + label: "Команда из одной пиццы", + slug: "team-leads/1-pizza-teams", + }, + ], + }, + { + label: "Для руководителей", + items: [ + { label: "Стратегическая visión", slug: "executives/strategic-vision" }, + { label: "Фреймворки ROI", slug: "executives/roi-frameworks" }, + { + label: "Плейбук внедрения", + slug: "executives/adoption-playbook", + }, + { + label: "Безопасность и соблюдение норм", + slug: "executives/security-compliance", + }, + { + label: "Искусственный интеллект в нативной экономике", + slug: "executives/ai-native-economics", + }, + ], + }, + { + label: "Прецеденты использования по этапам", + items: [ + { + label: "Планирование и дизайн", + slug: "use-cases/planning-design", + }, + { label: "Реализация", slug: "use-cases/implementation" }, + { + label: "Развертывание и эксплуатация", + slug: "use-cases/deployment-operations", + }, + { + label: "Качество и документация", + slug: "use-cases/quality-documentation", + }, + ], + }, + { + label: "Управление и риски", + items: [ + { label: "Проверка безопасности", slug: "governance/security-review" }, + { label: "Ответственность", slug: "governance/accountability" }, + { label: "Качество контрольных точек", slug: "governance/quality-gates" }, + ], + }, + { + label: "Приложения", + items: [ + { label: "Глоссарий", slug: "appendices/glossary" }, + { label: "Рекомендуемая литература", slug: "appendices/reading-list" }, + { label: "Шаблоны запросов", slug: "appendices/prompt-templates" }, + ], + }, + { + label: "Сообщество", + items: [ + { label: "Присоединиться к сообществу", slug: "community" }, + { label: "Вклад в проект", slug: "community/contributing" }, + ], + }, +]; + export default defineConfig({ site: "https://path.kilo.ai", integrations: [ @@ -18,10 +249,6 @@ export default defineConfig({ }, }, ], - title: "Agentic Engineering", - editLink: { - baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/", - }, components: { Footer: "./src/components/Footer.astro", Header: "./src/components/Header.astro", @@ -38,121 +265,6 @@ export default defineConfig({ href: "https://github.com/Kilo-Org/agentic-path", }, ], - sidebar: [ - { - label: "Introduction", - items: [ - { - label: "What is Agentic Engineering?", - slug: "introduction/what-is-agentic-engineering", - }, - { - label: "How Agents Work", - slug: "introduction/how-agents-work", - }, - { - label: "Working with Agents", - slug: "introduction/working-with-agents", - }, - { - label: "Trends & Patterns", - slug: "introduction/trends-patterns", - }, - ], - }, - { - label: "For Engineers", - items: [ - { label: "Getting Started", slug: "engineers/getting-started" }, - { - label: "Task Decomposition", - slug: "engineers/task-decomposition", - }, - { label: "Best Practices", slug: "engineers/best-practices" }, - ], - }, - { - label: "For Team Leads", - items: [ - { - label: "Adopting Agentic Tools", - slug: "team-leads/adopting-agentic-tools", - }, - { - label: "Measuring Impact", - slug: "team-leads/measuring-impact", - }, - { - label: "Quality Assurance", - slug: "team-leads/quality-assurance", - }, - { - label: "The 1-Pizza Team", - slug: "team-leads/1-pizza-teams", - }, - ], - }, - { - label: "For Executives", - items: [ - { label: "Strategic Vision", slug: "executives/strategic-vision" }, - { label: "ROI Frameworks", slug: "executives/roi-frameworks" }, - { - label: "Adoption Playbook", - slug: "executives/adoption-playbook", - }, - { - label: "Security & Compliance", - slug: "executives/security-compliance", - }, - { - label: "AI-Native Economics", - slug: "executives/ai-native-economics", - }, - ], - }, - { - label: "Use Cases by Phase", - items: [ - { - label: "Planning & Design", - slug: "use-cases/planning-design", - }, - { label: "Implementation", slug: "use-cases/implementation" }, - { - label: "Deployment & Operations", - slug: "use-cases/deployment-operations", - }, - { - label: "Quality & Documentation", - slug: "use-cases/quality-documentation", - }, - ], - }, - { - label: "Governance & Risk", - items: [ - { label: "Security Review", slug: "governance/security-review" }, - { label: "Accountability", slug: "governance/accountability" }, - { label: "Quality Gates", slug: "governance/quality-gates" }, - ], - }, - { - label: "Appendices", - items: [ - { label: "Glossary", slug: "appendices/glossary" }, - { label: "Recommended Reading", slug: "appendices/reading-list" }, - { label: "Prompt Templates", slug: "appendices/prompt-templates" }, - ], - }, - { - label: "Community", - items: [ - { label: "Join the Community", slug: "community" }, - { label: "Contributing", slug: "community/contributing" }, - ], - }, - ], customCss: ["./src/styles/custom.css"], plugins: [ catppuccin({ @@ -160,7 +272,25 @@ export default defineConfig({ light: { flavor: "latte", accent: "peach" }, }), ], + locales: { + en: { + label: "English", + title: "Agentic Engineering", + editLink: { + baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/", + }, + sidebar: enSidebar, + }, + ru: { + label: "Русский", + title: "Агентная инженерия", + editLink: { + baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/ru/", + }, + sidebar: ruSidebar, + }, + }, }), sitemap(), ], -}); +}); \ No newline at end of file From 6b6e1037be90306fbfbbc7654492e3b285884447 Mon Sep 17 00:00:00 2001 From: "kilo-code-bot[bot]" <240665456+kilo-code-bot[bot]@users.noreply.github.com> Date: Sat, 16 May 2026 19:20:48 +0000 Subject: [PATCH 2/8] feat: add Russian language support to Astro configuration (#2) Co-authored-by: Toast (gastown) --- astro.config.mjs | 372 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 251 insertions(+), 121 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index 8439519..d1f225a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -4,7 +4,238 @@ import starlight from "@astrojs/starlight"; import catppuccin from "@catppuccin/starlight"; import sitemap from "@astrojs/sitemap"; -// https://astro.build/config +const enSidebar = [ + { + label: "Introduction", + items: [ + { + label: "What is Agentic Engineering?", + slug: "introduction/what-is-agentic-engineering", + }, + { + label: "How Agents Work", + slug: "introduction/how-agents-work", + }, + { + label: "Working with Agents", + slug: "introduction/working-with-agents", + }, + { + label: "Trends & Patterns", + slug: "introduction/trends-patterns", + }, + ], + }, + { + label: "For Engineers", + items: [ + { label: "Getting Started", slug: "engineers/getting-started" }, + { + label: "Task Decomposition", + slug: "engineers/task-decomposition", + }, + { label: "Best Practices", slug: "engineers/best-practices" }, + ], + }, + { + label: "For Team Leads", + items: [ + { + label: "Adopting Agentic Tools", + slug: "team-leads/adopting-agentic-tools", + }, + { + label: "Measuring Impact", + slug: "team-leads/measuring-impact", + }, + { + label: "Quality Assurance", + slug: "team-leads/quality-assurance", + }, + { + label: "The 1-Pizza Team", + slug: "team-leads/1-pizza-teams", + }, + ], + }, + { + label: "For Executives", + items: [ + { label: "Strategic Vision", slug: "executives/strategic-vision" }, + { label: "ROI Frameworks", slug: "executives/roi-frameworks" }, + { + label: "Adoption Playbook", + slug: "executives/adoption-playbook", + }, + { + label: "Security & Compliance", + slug: "executives/security-compliance", + }, + { + label: "AI-Native Economics", + slug: "executives/ai-native-economics", + }, + ], + }, + { + label: "Use Cases by Phase", + items: [ + { + label: "Planning & Design", + slug: "use-cases/planning-design", + }, + { label: "Implementation", slug: "use-cases/implementation" }, + { + label: "Deployment & Operations", + slug: "use-cases/deployment-operations", + }, + { + label: "Quality & Documentation", + slug: "use-cases/quality-documentation", + }, + ], + }, + { + label: "Governance & Risk", + items: [ + { label: "Security Review", slug: "governance/security-review" }, + { label: "Accountability", slug: "governance/accountability" }, + { label: "Quality Gates", slug: "governance/quality-gates" }, + ], + }, + { + label: "Appendices", + items: [ + { label: "Glossary", slug: "appendices/glossary" }, + { label: "Recommended Reading", slug: "appendices/reading-list" }, + { label: "Prompt Templates", slug: "appendices/prompt-templates" }, + ], + }, + { + label: "Community", + items: [ + { label: "Join the Community", slug: "community" }, + { label: "Contributing", slug: "community/contributing" }, + ], + }, +]; + +const ruSidebar = [ + { + label: "Введение", + items: [ + { + label: "Что такое агентная инженерия?", + slug: "introduction/what-is-agentic-engineering", + }, + { + label: "Как работают агенты", + slug: "introduction/how-agents-work", + }, + { + label: "Работа с агентами", + slug: "introduction/working-with-agents", + }, + { + label: "Тенденции и закономерности", + slug: "introduction/trends-patterns", + }, + ], + }, + { + label: "Для инженеров", + items: [ + { label: "Начало работы", slug: "engineers/getting-started" }, + { + label: "Декомпозиция задач", + slug: "engineers/task-decomposition", + }, + { label: "Лучшие практики", slug: "engineers/best-practices" }, + ], + }, + { + label: "Для тимлидов", + items: [ + { + label: "Внедрение агентных инструментов", + slug: "team-leads/adopting-agentic-tools", + }, + { + label: "Измерение влияния", + slug: "team-leads/measuring-impact", + }, + { + label: "Обеспечение качества", + slug: "team-leads/quality-assurance", + }, + { + label: "Команда из одной пиццы", + slug: "team-leads/1-pizza-teams", + }, + ], + }, + { + label: "Для руководителей", + items: [ + { label: "Стратегическая visión", slug: "executives/strategic-vision" }, + { label: "Фреймворки ROI", slug: "executives/roi-frameworks" }, + { + label: "Плейбук внедрения", + slug: "executives/adoption-playbook", + }, + { + label: "Безопасность и соблюдение норм", + slug: "executives/security-compliance", + }, + { + label: "Искусственный интеллект в нативной экономике", + slug: "executives/ai-native-economics", + }, + ], + }, + { + label: "Прецеденты использования по этапам", + items: [ + { + label: "Планирование и дизайн", + slug: "use-cases/planning-design", + }, + { label: "Реализация", slug: "use-cases/implementation" }, + { + label: "Развертывание и эксплуатация", + slug: "use-cases/deployment-operations", + }, + { + label: "Качество и документация", + slug: "use-cases/quality-documentation", + }, + ], + }, + { + label: "Управление и риски", + items: [ + { label: "Проверка безопасности", slug: "governance/security-review" }, + { label: "Ответственность", slug: "governance/accountability" }, + { label: "Качество контрольных точек", slug: "governance/quality-gates" }, + ], + }, + { + label: "Приложения", + items: [ + { label: "Глоссарий", slug: "appendices/glossary" }, + { label: "Рекомендуемая литература", slug: "appendices/reading-list" }, + { label: "Шаблоны запросов", slug: "appendices/prompt-templates" }, + ], + }, + { + label: "Сообщество", + items: [ + { label: "Присоединиться к сообществу", slug: "community" }, + { label: "Вклад в проект", slug: "community/contributing" }, + ], + }, +]; + export default defineConfig({ site: "https://path.kilo.ai", integrations: [ @@ -18,10 +249,6 @@ export default defineConfig({ }, }, ], - title: "Agentic Engineering", - editLink: { - baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/", - }, components: { Footer: "./src/components/Footer.astro", Header: "./src/components/Header.astro", @@ -38,121 +265,6 @@ export default defineConfig({ href: "https://github.com/Kilo-Org/agentic-path", }, ], - sidebar: [ - { - label: "Introduction", - items: [ - { - label: "What is Agentic Engineering?", - slug: "introduction/what-is-agentic-engineering", - }, - { - label: "How Agents Work", - slug: "introduction/how-agents-work", - }, - { - label: "Working with Agents", - slug: "introduction/working-with-agents", - }, - { - label: "Trends & Patterns", - slug: "introduction/trends-patterns", - }, - ], - }, - { - label: "For Engineers", - items: [ - { label: "Getting Started", slug: "engineers/getting-started" }, - { - label: "Task Decomposition", - slug: "engineers/task-decomposition", - }, - { label: "Best Practices", slug: "engineers/best-practices" }, - ], - }, - { - label: "For Team Leads", - items: [ - { - label: "Adopting Agentic Tools", - slug: "team-leads/adopting-agentic-tools", - }, - { - label: "Measuring Impact", - slug: "team-leads/measuring-impact", - }, - { - label: "Quality Assurance", - slug: "team-leads/quality-assurance", - }, - { - label: "The 1-Pizza Team", - slug: "team-leads/1-pizza-teams", - }, - ], - }, - { - label: "For Executives", - items: [ - { label: "Strategic Vision", slug: "executives/strategic-vision" }, - { label: "ROI Frameworks", slug: "executives/roi-frameworks" }, - { - label: "Adoption Playbook", - slug: "executives/adoption-playbook", - }, - { - label: "Security & Compliance", - slug: "executives/security-compliance", - }, - { - label: "AI-Native Economics", - slug: "executives/ai-native-economics", - }, - ], - }, - { - label: "Use Cases by Phase", - items: [ - { - label: "Planning & Design", - slug: "use-cases/planning-design", - }, - { label: "Implementation", slug: "use-cases/implementation" }, - { - label: "Deployment & Operations", - slug: "use-cases/deployment-operations", - }, - { - label: "Quality & Documentation", - slug: "use-cases/quality-documentation", - }, - ], - }, - { - label: "Governance & Risk", - items: [ - { label: "Security Review", slug: "governance/security-review" }, - { label: "Accountability", slug: "governance/accountability" }, - { label: "Quality Gates", slug: "governance/quality-gates" }, - ], - }, - { - label: "Appendices", - items: [ - { label: "Glossary", slug: "appendices/glossary" }, - { label: "Recommended Reading", slug: "appendices/reading-list" }, - { label: "Prompt Templates", slug: "appendices/prompt-templates" }, - ], - }, - { - label: "Community", - items: [ - { label: "Join the Community", slug: "community" }, - { label: "Contributing", slug: "community/contributing" }, - ], - }, - ], customCss: ["./src/styles/custom.css"], plugins: [ catppuccin({ @@ -160,7 +272,25 @@ export default defineConfig({ light: { flavor: "latte", accent: "peach" }, }), ], + locales: { + en: { + label: "English", + title: "Agentic Engineering", + editLink: { + baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/", + }, + sidebar: enSidebar, + }, + ru: { + label: "Русский", + title: "Агентная инженерия", + editLink: { + baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/ru/", + }, + sidebar: ruSidebar, + }, + }, }), sitemap(), ], -}); +}); \ No newline at end of file From ece12482b5db6d6373aa430ebaabbfdbdfe7063e Mon Sep 17 00:00:00 2001 From: "Toast (gastown)" Date: Sat, 16 May 2026 20:08:21 +0000 Subject: [PATCH 3/8] Add Russian language support to Astro Starlight configuration - Configure root locale for English (served at /) - Add Russian locale (served at /ru/) - Add translated sidebar labels using translations property - Create Russian homepage (index.mdx) with translated content - Create Russian content directory structure with placeholder files - Add Russian UI translations for Starlight components (i18n/ru.json) - Configure edit links for both locales --- astro.config.mjs | 199 +++----- src/content/docs/ru/appendices/glossary.md | 143 ++++++ .../docs/ru/appendices/prompt-templates.md | 331 +++++++++++++ .../docs/ru/appendices/reading-list.md | 138 ++++++ src/content/docs/ru/community/contributing.md | 162 ++++++ src/content/docs/ru/community/index.md | 119 +++++ .../docs/ru/engineers/best-practices.md | 235 +++++++++ .../docs/ru/engineers/getting-started.md | 108 ++++ .../docs/ru/engineers/task-decomposition.md | 154 ++++++ .../docs/ru/executives/adoption-playbook.md | 149 ++++++ .../docs/ru/executives/ai-native-economics.md | 130 +++++ .../docs/ru/executives/roi-frameworks.md | 143 ++++++ .../docs/ru/executives/security-compliance.md | 145 ++++++ .../docs/ru/executives/strategic-vision.md | 138 ++++++ .../docs/ru/executives/toy-tool-cycle.md | 104 ++++ .../docs/ru/governance/accountability.md | 128 +++++ .../docs/ru/governance/quality-gates.md | 111 +++++ .../docs/ru/governance/security-review.md | 127 +++++ src/content/docs/ru/index.mdx | 124 +++++ .../docs/ru/introduction/how-agents-work.md | 97 ++++ .../docs/ru/introduction/patterns/openclaw.md | 166 +++++++ .../patterns/outcome-engineering.md | 192 +++++++ .../ru/introduction/patterns/ralph-wiggum.md | 219 ++++++++ .../docs/ru/introduction/patterns/rpi.md | 467 ++++++++++++++++++ .../patterns/spec-driven-development.md | 381 ++++++++++++++ .../docs/ru/introduction/trends-patterns.md | 275 +++++++++++ .../what-is-agentic-engineering.md | 95 ++++ .../ru/introduction/working-with-agents.md | 65 +++ .../docs/ru/team-leads/1-pizza-teams.md | 90 ++++ .../ru/team-leads/adopting-agentic-tools.md | 137 +++++ .../docs/ru/team-leads/measuring-impact.md | 149 ++++++ .../docs/ru/team-leads/quality-assurance.md | 137 +++++ .../ru/use-cases/deployment-operations.md | 137 +++++ .../docs/ru/use-cases/implementation.md | 81 +++ .../docs/ru/use-cases/planning-design.md | 85 ++++ .../ru/use-cases/quality-documentation.md | 127 +++++ src/content/i18n/ru.json | 30 ++ 37 files changed, 5685 insertions(+), 133 deletions(-) create mode 100644 src/content/docs/ru/appendices/glossary.md create mode 100644 src/content/docs/ru/appendices/prompt-templates.md create mode 100644 src/content/docs/ru/appendices/reading-list.md create mode 100644 src/content/docs/ru/community/contributing.md create mode 100644 src/content/docs/ru/community/index.md create mode 100644 src/content/docs/ru/engineers/best-practices.md create mode 100644 src/content/docs/ru/engineers/getting-started.md create mode 100644 src/content/docs/ru/engineers/task-decomposition.md create mode 100644 src/content/docs/ru/executives/adoption-playbook.md create mode 100644 src/content/docs/ru/executives/ai-native-economics.md create mode 100644 src/content/docs/ru/executives/roi-frameworks.md create mode 100644 src/content/docs/ru/executives/security-compliance.md create mode 100644 src/content/docs/ru/executives/strategic-vision.md create mode 100644 src/content/docs/ru/executives/toy-tool-cycle.md create mode 100644 src/content/docs/ru/governance/accountability.md create mode 100644 src/content/docs/ru/governance/quality-gates.md create mode 100644 src/content/docs/ru/governance/security-review.md create mode 100644 src/content/docs/ru/index.mdx create mode 100644 src/content/docs/ru/introduction/how-agents-work.md create mode 100644 src/content/docs/ru/introduction/patterns/openclaw.md create mode 100644 src/content/docs/ru/introduction/patterns/outcome-engineering.md create mode 100644 src/content/docs/ru/introduction/patterns/ralph-wiggum.md create mode 100644 src/content/docs/ru/introduction/patterns/rpi.md create mode 100644 src/content/docs/ru/introduction/patterns/spec-driven-development.md create mode 100644 src/content/docs/ru/introduction/trends-patterns.md create mode 100644 src/content/docs/ru/introduction/what-is-agentic-engineering.md create mode 100644 src/content/docs/ru/introduction/working-with-agents.md create mode 100644 src/content/docs/ru/team-leads/1-pizza-teams.md create mode 100644 src/content/docs/ru/team-leads/adopting-agentic-tools.md create mode 100644 src/content/docs/ru/team-leads/measuring-impact.md create mode 100644 src/content/docs/ru/team-leads/quality-assurance.md create mode 100644 src/content/docs/ru/use-cases/deployment-operations.md create mode 100644 src/content/docs/ru/use-cases/implementation.md create mode 100644 src/content/docs/ru/use-cases/planning-design.md create mode 100644 src/content/docs/ru/use-cases/quality-documentation.md create mode 100644 src/content/i18n/ru.json diff --git a/astro.config.mjs b/astro.config.mjs index d1f225a..8d0e05b 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -4,242 +4,178 @@ import starlight from "@astrojs/starlight"; import catppuccin from "@catppuccin/starlight"; import sitemap from "@astrojs/sitemap"; -const enSidebar = [ +const sidebar = [ { label: "Introduction", + translations: { ru: "Введение" }, items: [ { label: "What is Agentic Engineering?", + translations: { ru: "Что такое агентная инженерия?" }, slug: "introduction/what-is-agentic-engineering", }, { label: "How Agents Work", + translations: { ru: "Как работают агенты" }, slug: "introduction/how-agents-work", }, { label: "Working with Agents", + translations: { ru: "Работа с агентами" }, slug: "introduction/working-with-agents", }, { label: "Trends & Patterns", + translations: { ru: "Тенденции и закономерности" }, slug: "introduction/trends-patterns", }, ], }, { label: "For Engineers", + translations: { ru: "Для инженеров" }, items: [ - { label: "Getting Started", slug: "engineers/getting-started" }, + { label: "Getting Started", translations: { ru: "Начало работы" }, slug: "engineers/getting-started" }, { label: "Task Decomposition", + translations: { ru: "Декомпозиция задач" }, slug: "engineers/task-decomposition", }, - { label: "Best Practices", slug: "engineers/best-practices" }, + { label: "Best Practices", translations: { ru: "Лучшие практики" }, slug: "engineers/best-practices" }, ], }, { label: "For Team Leads", + translations: { ru: "Для тимлидов" }, items: [ { label: "Adopting Agentic Tools", + translations: { ru: "Внедрение агентных инструментов" }, slug: "team-leads/adopting-agentic-tools", }, { label: "Measuring Impact", + translations: { ru: "Измерение влияния" }, slug: "team-leads/measuring-impact", }, { label: "Quality Assurance", + translations: { ru: "Обеспечение качества" }, slug: "team-leads/quality-assurance", }, { label: "The 1-Pizza Team", + translations: { ru: "Команда из одной пиццы" }, slug: "team-leads/1-pizza-teams", }, ], }, { label: "For Executives", + translations: { ru: "Для руководителей" }, items: [ - { label: "Strategic Vision", slug: "executives/strategic-vision" }, - { label: "ROI Frameworks", slug: "executives/roi-frameworks" }, + { + label: "Strategic Vision", + translations: { ru: "Стратегическое видение" }, + slug: "executives/strategic-vision", + }, + { label: "ROI Frameworks", translations: { ru: "Фреймворки ROI" }, slug: "executives/roi-frameworks" }, { label: "Adoption Playbook", + translations: { ru: "Плейбук внедрения" }, slug: "executives/adoption-playbook", }, { label: "Security & Compliance", + translations: { ru: "Безопасность и соблюдение норм" }, slug: "executives/security-compliance", }, { label: "AI-Native Economics", + translations: { ru: "Искусственный интеллект в нативной экономике" }, slug: "executives/ai-native-economics", }, ], }, { label: "Use Cases by Phase", + translations: { ru: "Прецеденты использования по этапам" }, items: [ { label: "Planning & Design", + translations: { ru: "Планирование и дизайн" }, slug: "use-cases/planning-design", }, - { label: "Implementation", slug: "use-cases/implementation" }, + { + label: "Implementation", + translations: { ru: "Реализация" }, + slug: "use-cases/implementation", + }, { label: "Deployment & Operations", + translations: { ru: "Развертывание и эксплуатация" }, slug: "use-cases/deployment-operations", }, { label: "Quality & Documentation", + translations: { ru: "Качество и документация" }, slug: "use-cases/quality-documentation", }, ], }, { label: "Governance & Risk", + translations: { ru: "Управление и риски" }, items: [ - { label: "Security Review", slug: "governance/security-review" }, - { label: "Accountability", slug: "governance/accountability" }, - { label: "Quality Gates", slug: "governance/quality-gates" }, - ], - }, - { - label: "Appendices", - items: [ - { label: "Glossary", slug: "appendices/glossary" }, - { label: "Recommended Reading", slug: "appendices/reading-list" }, - { label: "Prompt Templates", slug: "appendices/prompt-templates" }, - ], - }, - { - label: "Community", - items: [ - { label: "Join the Community", slug: "community" }, - { label: "Contributing", slug: "community/contributing" }, - ], - }, -]; - -const ruSidebar = [ - { - label: "Введение", - items: [ - { - label: "Что такое агентная инженерия?", - slug: "introduction/what-is-agentic-engineering", - }, - { - label: "Как работают агенты", - slug: "introduction/how-agents-work", - }, - { - label: "Работа с агентами", - slug: "introduction/working-with-agents", - }, - { - label: "Тенденции и закономерности", - slug: "introduction/trends-patterns", - }, - ], - }, - { - label: "Для инженеров", - items: [ - { label: "Начало работы", slug: "engineers/getting-started" }, - { - label: "Декомпозиция задач", - slug: "engineers/task-decomposition", - }, - { label: "Лучшие практики", slug: "engineers/best-practices" }, - ], - }, - { - label: "Для тимлидов", - items: [ - { - label: "Внедрение агентных инструментов", - slug: "team-leads/adopting-agentic-tools", - }, { - label: "Измерение влияния", - slug: "team-leads/measuring-impact", + label: "Security Review", + translations: { ru: "Проверка безопасности" }, + slug: "governance/security-review", }, { - label: "Обеспечение качества", - slug: "team-leads/quality-assurance", + label: "Accountability", + translations: { ru: "Ответственность" }, + slug: "governance/accountability", }, { - label: "Команда из одной пиццы", - slug: "team-leads/1-pizza-teams", + label: "Quality Gates", + translations: { ru: "Качество контрольных точек" }, + slug: "governance/quality-gates", }, ], }, { - label: "Для руководителей", + label: "Appendices", + translations: { ru: "Приложения" }, items: [ - { label: "Стратегическая visión", slug: "executives/strategic-vision" }, - { label: "Фреймворки ROI", slug: "executives/roi-frameworks" }, - { - label: "Плейбук внедрения", - slug: "executives/adoption-playbook", - }, - { - label: "Безопасность и соблюдение норм", - slug: "executives/security-compliance", - }, - { - label: "Искусственный интеллект в нативной экономике", - slug: "executives/ai-native-economics", - }, + { label: "Glossary", translations: { ru: "Глоссарий" }, slug: "appendices/glossary" }, + { label: "Recommended Reading", translations: { ru: "Рекомендуемая литература" }, slug: "appendices/reading-list" }, + { label: "Prompt Templates", translations: { ru: "Шаблоны запросов" }, slug: "appendices/prompt-templates" }, ], }, { - label: "Прецеденты использования по этапам", + label: "Community", + translations: { ru: "Сообщество" }, items: [ { - label: "Планирование и дизайн", - slug: "use-cases/planning-design", + label: "Join the Community", + translations: { ru: "Присоединиться к сообществу" }, + slug: "community", }, - { label: "Реализация", slug: "use-cases/implementation" }, { - label: "Развертывание и эксплуатация", - slug: "use-cases/deployment-operations", - }, - { - label: "Качество и документация", - slug: "use-cases/quality-documentation", + label: "Contributing", + translations: { ru: "Вклад в проект" }, + slug: "community/contributing", }, ], }, - { - label: "Управление и риски", - items: [ - { label: "Проверка безопасности", slug: "governance/security-review" }, - { label: "Ответственность", slug: "governance/accountability" }, - { label: "Качество контрольных точек", slug: "governance/quality-gates" }, - ], - }, - { - label: "Приложения", - items: [ - { label: "Глоссарий", slug: "appendices/glossary" }, - { label: "Рекомендуемая литература", slug: "appendices/reading-list" }, - { label: "Шаблоны запросов", slug: "appendices/prompt-templates" }, - ], - }, - { - label: "Сообщество", - items: [ - { label: "Присоединиться к сообществу", slug: "community" }, - { label: "Вклад в проект", slug: "community/contributing" }, - ], - }, ]; export default defineConfig({ site: "https://path.kilo.ai", integrations: [ starlight({ + title: "Agentic Engineering", head: [ { tag: "script", @@ -272,22 +208,19 @@ export default defineConfig({ light: { flavor: "latte", accent: "peach" }, }), ], + sidebar, + editLink: { + baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/src/content/docs/", + }, + defaultLocale: "root", locales: { - en: { + root: { label: "English", - title: "Agentic Engineering", - editLink: { - baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/", - }, - sidebar: enSidebar, + lang: "en", }, ru: { label: "Русский", - title: "Агентная инженерия", - editLink: { - baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/ru/", - }, - sidebar: ruSidebar, + lang: "ru", }, }, }), diff --git a/src/content/docs/ru/appendices/glossary.md b/src/content/docs/ru/appendices/glossary.md new file mode 100644 index 0000000..6468cee --- /dev/null +++ b/src/content/docs/ru/appendices/glossary.md @@ -0,0 +1,143 @@ +--- +title: Glossary +description: Key terms in agentic engineering +sidebar: + order: 1 +--- + +A reference for terminology used throughout this guide and in the broader agentic engineering ecosystem. + +## A + +**Agent** +An AI system capable of taking actions in an environment. Unlike chatbots that only generate text, agents can read/write files, execute commands, and interact with systems. + +**Agentic engineering** +The discipline of building software primarily by orchestrating AI agents rather than writing code directly. + +**Agentic workflow** +A development process where AI agents handle significant portions of implementation, with human oversight and direction. + +**Autonomy** +The degree to which an agent operates independently. Higher autonomy means less human intervention required. + +**Acceptance rate** +The percentage of agent-generated suggestions accepted without modification. + +## C + +**Chain-of-thought (CoT)** +A prompting technique where the model shows its reasoning step-by-step, often improving accuracy. + +**Context engineering** +The discipline of providing AI agents with the right information at the right time. Goes beyond prompt engineering to encompass the entire system of what an agent knows when making decisions—including system instructions, codebase knowledge, conversation history, tool outputs, and external documentation. + +**Context window** +The maximum amount of text (measured in tokens) that a model can process at once. + +**Copilot** +A category of AI coding assistants that provide suggestions and completions within development environments. Originally a GitHub product name, now often used generically. + +## D + +**Decomposition** +Breaking a complex task into smaller, agent-manageable pieces. + +**Drift** +When an agent gradually moves away from the original task objective during multi-step execution. + +## F + +**Few-shot prompting** +Including examples in a prompt to demonstrate the desired output format or behavior. + +**Fine-tuning** +Training a model on specific data to specialize its behavior for particular tasks or domains. + +## G + +**Guardrails** +Rules or checks that prevent agents from taking harmful or unauthorized actions. + +## H + +**Hallucination** +When a model generates plausible-sounding but incorrect information, such as non-existent APIs or functions. + +**Human-in-the-loop (HITL)** +A design pattern where humans review and approve agent actions at key points. + +## I + +**Inference** +The process of generating output from a model. Running inference = asking the model to respond. + +**Iteration count** +The number of prompt-response cycles needed to complete a task. + +## L + +**Large Language Model (LLM)** +The neural network (like GPT-4, Claude, Gemini) that powers most AI agents. Trained on massive text corpora. + +**Looping** +When an agent gets stuck repeating the same failed approach. + +## M + +**Multi-agent system** +Multiple specialized agents collaborating to complete complex tasks. + +## O + +**Outcome Engineering (o16g)** +A development philosophy that reorients work around outcomes rather than code. Core tenets: manage to cost (tokens) instead of capacity (engineer-hours), measure success by verified impact rather than lines written, and treat the backlog as a relic of human limitation. See the [o16g Manifesto](https://o16g.com/). + +## P + +**Prompt** +The input given to an agent or model, including instructions, context, and constraints. + +**Prompt engineering** +The practice of crafting effective prompts to get desired outputs from AI models. + +## R + +**ReAct (Reason + Act)** +A pattern where agents alternate between reasoning about what to do and taking actions. Foundation of most agentic systems. + +**RAG (Retrieval Augmented Generation)** +A technique where relevant information is retrieved and added to prompts to improve response accuracy. + +## S + +**Scaffolding** +Providing structure, examples, or constraints to guide agent behavior. + +**System prompt** +Background instructions that set an agent's behavior, usually hidden from users. + +## T + +**Task decomposition** +Breaking a large task into smaller, independently completable subtasks. + +**Token** +A chunk of text processed by a model. Roughly 4 characters in English. Models process tokens, not characters. + +**Tool use** +An agent's ability to invoke external functions: reading files, running commands, accessing APIs. + +## V + +**Validation** +The process of verifying that agent output is correct, secure, and meets requirements. + +## Z + +**Zero-shot** +Prompting a model without providing examples of desired output. + +--- + +_This glossary will be expanded as terminology evolves._ diff --git a/src/content/docs/ru/appendices/prompt-templates.md b/src/content/docs/ru/appendices/prompt-templates.md new file mode 100644 index 0000000..a3f2ecc --- /dev/null +++ b/src/content/docs/ru/appendices/prompt-templates.md @@ -0,0 +1,331 @@ +--- +title: Prompt Templates by Use Case +description: Ready-to-use prompt structures for common tasks +sidebar: + order: 4 +--- + +Copy and adapt these templates for your specific needs. Each template includes the key components that make prompts effective. + +## Implementation prompts + +### New feature + +``` +Implement [feature name]. + +## Requirements +- [Functional requirement 1] +- [Functional requirement 2] +- [Non-functional requirement] + +## Technical context +- Language/Framework: [specify] +- Relevant files: [list files] +- Pattern to follow: [reference file or describe] + +## Constraints +- Don't modify: [files/functions to preserve] +- Must maintain: [backward compatibility requirements] +- Performance requirement: [if any] + +## Acceptance criteria +- [ ] [Criterion 1] +- [ ] [Criterion 2] +- [ ] [Criterion 3] +``` + +### API endpoint + +``` +Create an API endpoint for [purpose]. + +## Endpoint specification +- Method: [GET/POST/PUT/DELETE] +- Path: [/api/v1/...] +- Authentication: [required/optional/none] + +## Request +- Body: [describe structure or provide example] +- Parameters: [query params, path params] +- Headers: [required headers] + +## Response +- Success (200): [describe/example] +- Error cases: [list with status codes] + +## Implementation details +- Handler location: [file path] +- Service to use: [service name] +- Follow pattern in: [example file] +``` + +### Database migration + +``` +Create a database migration to [purpose]. + +## Changes needed +- [Change 1: add table/column/index] +- [Change 2] +- [Change 3] + +## Schema details +[Describe tables, columns, types, constraints] + +## Considerations +- Existing data: [how to handle] +- Reversibility: [rollback requirements] +- Performance: [large table considerations] + +## Migration framework: [Prisma/Knex/etc.] +``` + +## Bug fix prompts + +### With known cause + +``` +Fix bug: [one-line description] + +## Reproduction +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Current behavior +[What happens now] + +## Expected behavior +[What should happen] + +## Root cause +[Your analysis of why this happens] + +## Constraints +- Minimize changes +- Don't modify [protected areas] +- Add regression test +``` + +### Investigation needed + +``` +Debug issue: [symptom description] + +## Context +- When it occurs: [conditions] +- Error message: [if any] +- Relevant logs: [paste relevant logs] +- Recent changes: [what changed recently] + +## What I've tried +- [Attempt 1 and result] +- [Attempt 2 and result] + +## Questions +- What could cause this? +- How can I verify the root cause? +- What's the safest fix? +``` + +## Testing prompts + +### Unit tests + +``` +Write unit tests for [function/class name] in [file]. + +## Test framework: [Jest/pytest/etc.] + +## Coverage requirements +- Normal operation cases +- Edge cases: + - Empty/null inputs + - Boundary values + - [Domain-specific edges] +- Error conditions: + - [Error case 1] + - [Error case 2] + +## Style +- Follow patterns in [example test file] +- Use [describe/it or test naming convention] +- Mock [specify what to mock] +``` + +### Integration tests + +``` +Write integration tests for [component/feature]. + +## Test scope +- Test the interaction between [component A] and [component B] +- Use [real/mocked] [database/external service] + +## Scenarios +1. [Happy path scenario] +2. [Error scenario] +3. [Edge case scenario] + +## Setup requirements +- [Prerequisites] +- [Test data needed] + +## Framework: [specify] +``` + +## Refactoring prompts + +### Extract function/class + +``` +Refactor: Extract [description] into [function/class]. + +## Current code location: [file:lines] + +## Desired outcome +- New [function/class] name: [name] +- New location: [file] +- Parameters: [what it should accept] +- Return value: [what it should return] + +## Constraints +- Keep existing behavior unchanged +- Update all callers +- Maintain backward compatibility +``` + +### Pattern migration + +``` +Refactor [file/module] from [old pattern] to [new pattern]. + +## Current state +[Describe or show current implementation] + +## Target state +[Describe or show example of new pattern] + +## Migration rules +- [Rule 1] +- [Rule 2] +- [Rule 3] + +## Files affected: [list] + +## Constraints +- All tests must pass after change +- Don't change public interfaces +``` + +## Documentation prompts + +### Function/class documentation + +``` +Document [function/class name] in [file]. + +## Documentation format: [JSDoc/docstrings/etc.] + +## Include +- Purpose/description +- Parameters (name, type, description) +- Return value (type, description) +- Exceptions/errors thrown +- Usage example + +## Style +- Follow conventions in [example file] +- [Additional style requirements] +``` + +### README generation + +``` +Create/update README for [project/module]. + +## Sections needed +- Overview/description +- Installation +- Quick start +- Configuration +- API reference (summary) +- Contributing +- License + +## Target audience: [developers/users/both] + +## Existing documentation: [what exists already] +``` + +## Code review prompts + +### Pre-commit review + +``` +Review this code before I commit it. + +## Code +[paste code] + +## Context +- Purpose: [what this code does] +- Part of: [larger feature/PR] + +## Specific concerns +- [Area 1 I'm uncertain about] +- [Area 2 I want feedback on] + +## Check for +- Bugs and logic errors +- Security issues +- Performance concerns +- Code style +- Edge cases +``` + +### Architecture review + +``` +Review this proposed architecture. + +## Proposal +[Describe or diagram the proposed architecture] + +## Problem being solved +[What this architecture addresses] + +## Constraints +- [Technical constraints] +- [Business constraints] +- [Timeline] + +## Questions +- Does this approach make sense? +- What am I missing? +- What alternatives should I consider? +- What are the risks? +``` + +## Tips for using templates + +1. **Fill in specifics** - Replace all bracketed placeholders +2. **Provide context** - More context = better output +3. **Be explicit about constraints** - What NOT to do is as important as what to do +4. **Include examples** - Show patterns to follow when possible +5. **Iterate** - First response rarely perfect; refine with follow-ups + +## Resources + +### Essential + +- [Prompt Engineering Specialization – Vanderbilt University](https://www.coursera.org/specializations/prompt-engineering) - Comprehensive course on using LLMs as a "mind exoskeleton" + +### Deep dives + +- [Understanding Prompt Engineering – DataCamp](https://www.datacamp.com/courses/understanding-prompt-engineering) - Beginner course on prompt engineering fundamentals + +--- + +**Have a useful template?** [Share it with the community](/community/contributing/)—your prompt might save someone hours of trial and error. diff --git a/src/content/docs/ru/appendices/reading-list.md b/src/content/docs/ru/appendices/reading-list.md new file mode 100644 index 0000000..372fdc4 --- /dev/null +++ b/src/content/docs/ru/appendices/reading-list.md @@ -0,0 +1,138 @@ +--- +title: Recommended Reading +description: Books, papers, and resources for deeper learning +sidebar: + order: 2 +--- + +Curated resources for going deeper on agentic engineering topics. This list will be updated as the field evolves. + +## Books + +### Foundations + +_Foundational books on AI, machine learning systems, and data architecture._ + +- [Artificial Intelligence: A Modern Approach (4th ed.)](https://aima.cs.berkeley.edu/) – Stuart Russell & Peter Norvig (2020). The authoritative AI textbook covering intelligent agent principles, search algorithms, reasoning, and machine learning fundamentals. +- [Software Engineering at Google](https://abseil.io/resources/swe-book) – Titus Winters, Tom Manshreck & Hyrum Wright (2020). Practical engineering practices for sustaining large codebases—highly relevant for teams adopting AI-assisted workflows. +- [The Pragmatic Programmer (20th Anniversary Edition)](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/) – Andrew Hunt & David Thomas (2019). Timeless advice on writing clean, flexible code that remains vital even as AI tools enter the mix. +- [Designing Machine Learning Systems](https://huyenchip.com/books/) – Chip Huyen (2022). Holistic guide to building reliable ML-powered applications, from data processing to deployment and monitoring. +- [AI Engineering](https://huyenchip.com/books/) – Chip Huyen (2025). Practical framework for building applications with foundation models, bridging traditional engineering and modern AI development. +- [Designing Data-Intensive Applications](https://martin.kleppmann.com/2017/03/27/designing-data-intensive-applications.html) – Martin Kleppmann (2017). Deep dive into reliable, scalable systems—crucial architectural knowledge before layering on AI features. + +### Manifestos and philosophy + +_Frameworks for thinking about AI-assisted development at a higher level._ + +- [The o16g Manifesto](https://o16g.com/) – Cory Ondrejka (2025). "Outcome Engineering" — 16 principles for reorienting development around outcomes rather than code. Argues for managing to cost (tokens) instead of capacity (engineer-hours), measuring success by verified impact, and treating the backlog as a relic of human limitation. From the CTO of Onebrief, co-creator of Second Life, and former engineering leader at Google and Meta. + +### Context engineering + +_The emerging discipline of providing agents with the right information at the right time._ + +- [Context Engineering for AI Agents – Tobi Lutke](https://x.com/tolobi/status/1935533391175041359) - Shopify CEO on why context engineering is the new skill +- [Context Engineering – Andrej Karpathy](https://x.com/karpathy/status/1937902205765607626) - "Prompt engineering is dead, context engineering is king" +- [AGENTS.md](https://agents.md/) - Open format for persistent agent context, used by 60k+ open-source projects + +### Prompt engineering + +_Guides to effective prompting and AI interaction._ + +- [Google Cloud Prompt Engineering Guide](https://cloud.google.com/discover/what-is-prompt-engineering) – Comprehensive official guide covering prompt format, examples, multi-turn interactions, and best practices. +- [DAIR Prompt Engineering Guide](https://www.promptingguide.ai/) – Mostafa Samir et al. Extensive open-source guide aggregating the latest techniques, from basic design to advanced strategies like multi-step reasoning and tool use. +- [Learn Prompting](https://learnprompting.org/docs/introduction) – Sander Schulhoff et al. (2024). Free course covering fundamentals to advanced techniques, used by 3M+ users including Fortune 500 teams. +- [The Ultimate Guide to Prompt Engineering](https://www.lakera.ai/blog/prompt-engineering-guide) – Lakera (2025). Modern best practices with focus on real-world usage and security, including defense against prompt injections. +- **Prompt Engineering for Generative AI** – James Phoenix & Mike Taylor (2023). Practical book on principles and patterns across domains—NLP, image generation, and code generation. +- **Prompt Engineering for LLMs** – John Berryman & Albert Ziegler (2024). Advanced strategies from GitHub Copilot developers covering token management, few-shot prompting, and workflow patterns. + +### Software engineering + +_Classic and modern software engineering texts relevant to AI-assisted development._ + +- [Clean Code](https://gerlacdt.github.io/blog/posts/clean_code/) – Robert C. Martin (2008). Classic manual on maintainable code—crucial for recognizing and refactoring AI-generated code into well-structured designs. +- [Refactoring (2nd ed.)](https://martinfowler.com/tags/refactoring.html) – Martin Fowler (2018). Seminal guide to systematically restructuring code, invaluable for continuously improving AI-written code. +- [Accelerate](https://itrevolution.com/product/accelerate/) – Nicole Forsgren, Jez Humble & Gene Kim (2018). Data-driven research on high-performing teams, introducing DORA metrics—essential baseline when integrating AI into workflows. +- [Agentic AI Engineering](https://mitpressbookstore.mit.edu/book/9798989357789) – Yi Zhou (2025). Forward-looking guide reframing software engineering for AI agents, covering the Agentic Stack and maturity models for scaling agents to production. +- **The LLM Engineering Handbook** – Paul Iusztin & Maxime Labonne (2024). Operations guide covering prompt engineering, fine-tuning, RAG, and patterns for putting LLMs into production. +- [A Philosophy of Software Design (2nd ed.)](https://web.stanford.edu/~ouster/cgi-bin/book.php) – John Ousterhout (2021). Concise essays on managing complexity—lessons that complement AI tools by helping developers shape architecture and keep complexity under control. + +## Research papers + +### Key papers on agents + +_Academic papers defining agentic systems and patterns._ + +- [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629) – Yao et al. (2022). Introduced the paradigm of interleaving reasoning traces with actions, enabling LLMs to gather information and adjust plans mid-stream. Foundation for many agent frameworks. +- [HuggingGPT: Solving AI Tasks with ChatGPT and its Friends](https://arxiv.org/abs/2303.17580) – Shen et al. (2023). LLM-powered controller that orchestrates specialized models for complex multi-modal tasks, using natural language as the glue between tools. +- [Toolformer: Language Models Can Teach Themselves to Use Tools](https://arxiv.org/abs/2302.04761) – Schick et al. (2023). Meta AI's method for LLMs to self-train on API usage, learning when and how to call external tools strategically. +- [Generative Agents: Interactive Simulacra of Human Behavior](https://arxiv.org/abs/2304.03442) – Park et al. (2023). Architecture for believable simulated agents with long-term memory and planning, demonstrating human-like behavior over extended periods. +- [Voyager: An Open-Ended Embodied Agent with Large Language Models](https://arxiv.org/abs/2305.16291) – Wang et al. (2023). First LLM-driven lifelong learning agent in Minecraft, continuously exploring and accumulating skills without human intervention. +- [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) – Shinn et al. (2023). Framework enabling agents to learn from mistakes through self-reflection in natural language, without formal fine-tuning. + +### Language models for code + +_Research on code generation, understanding, and synthesis._ + +- [StarCoder: may the source be with you!](https://arxiv.org/abs/2305.06161) - Open-source Code LLM with 8K context and infilling capabilities + +### Human-AI collaboration + +_Studies on how humans and AI systems work together effectively._ + +- [Experimental Evidence on the Productivity Effects of Generative AI](https://www.science.org/doi/10.1126/science.adh2586) – Noy & Zhang (2023, Science). Landmark study showing ChatGPT users completed tasks ~40% faster with 18% higher quality—lower-skilled participants benefited most. +- [The Productivity Effects of Generative AI: Evidence from GitHub Copilot](https://mit-genai.pubpub.org/pub/v5iixksv/release/2) – Cui et al. (2024). Field experiment at Microsoft/Accenture showing 12–22% more PRs completed per week with Copilot access. +- [When Humans and AI Work Best Together](https://mitsloan.mit.edu/ideas-made-to-matter/when-humans-and-ai-work-best-together-and-when-each-better-alone) – MIT Sloan (2025). Meta-analysis finding collaboration shines when humans are individually better than AI—success requires calibrating when to trust AI. +- [Coding on Copilot: Data Suggests Downward Pressure on Code Quality](https://www.gitclear.com/coding_on_copilot_data_shows_ais_downward_pressure_on_code_quality) – GitClear (2023). Analysis of 153M lines showing code churn doubled with AI use—teams need practices to keep quality in check. +- [GitHub Copilot: Asset or Liability?](https://www.sciencedirect.com/science/article/abs/pii/S0164121223001292) – Moradi Dakhel et al. (2023). Copilot valuable for experts who can vet output, but potential liability for novices who accept faulty suggestions. + +## Online resources + +### Blogs and newsletters + +_Regular sources of insight on AI and development._ + +- [2025: The year in LLMs – Simon Willison](https://simonwillison.net/2025/Dec/31/the-year-in-llms/) - Comprehensive annual review of LLM developments + +### Podcasts + +_Audio content covering agentic development._ + +- [The RPI workflow - Build Wiz AI Show (Podcast)](https://open.spotify.com/episode/1OdIYj0SZzhyzFGGoVuELP) - Audio discussion on advanced AI coding + +### Video content + +_Tutorials, talks, and demonstrations._ + +- [The Complete AI Coding Course (2025)](https://www.udemy.com/course/the-complete-ai-coding-course-2025-cursor-ai-v0-vercel/) - Hands-on course covering Cursor and Claude Code + +### Communities + +_Places to connect with others working in this space._ + +- [Kilo Code Discord](https://kilo.love/discord) - Our community for discussing agentic engineering +- [GitHub Discussions](https://github.com/Kilo-Org/agentic-path/discussions) - Longer-form conversations about this guide + +--- + +## Contributing resources + +Know a great resource we should include? This list grows through community contributions. + +**How to add a resource:** + +1. [Open a PR](/community/contributing/) with your addition +2. Include a brief description of why it's valuable +3. Place it in the appropriate section + +We're especially looking for: + +- Books and papers that shaped your understanding +- Tutorials that actually helped you get started +- Communities where you've found good discussions +- Case studies from real implementations + +[Join the conversation on Discord](https://kilo.love/discord) if you want to discuss what should be included. + +--- + +_This list is actively maintained by the community. Your recommendations help others learn faster._ diff --git a/src/content/docs/ru/community/contributing.md b/src/content/docs/ru/community/contributing.md new file mode 100644 index 0000000..edd1a15 --- /dev/null +++ b/src/content/docs/ru/community/contributing.md @@ -0,0 +1,162 @@ +--- +title: Contributing +description: How to contribute to Agentic Engineering for Humans—we want your help +sidebar: + order: 1 +--- + +This guide exists because people share what they've learned. Every contribution makes it better for the next person figuring out how to work with AI agents. + +## Why contribute? + +The field moves fast. What worked six months ago might be outdated. What you learned last week might help someone tomorrow. + +**Your experience matters.** Whether you've been using AI tools for years or just started, you have perspective we don't. Different tools, different languages, different team sizes, different industries—all of it adds value. + +## Ways to contribute + +### Quick wins (no issue needed) + +- **Fix typos or broken links** — Just open a PR +- **Add a resource** — Found a great article or video? Add it to the relevant page +- **Clarify confusing sections** — If something tripped you up, improve it +- **Update outdated info** — Tools change constantly + +### Bigger contributions (open an issue first) + +- **New pages or sections** — Have expertise we haven't covered? Let's talk +- **Case studies** — Real-world stories of what worked (or didn't) +- **Translations** — Help make this accessible to more people +- **Tooling improvements** — Better search, navigation, accessibility + +## Getting started + +### 1. Find something to work on + +Check [open issues](https://github.com/Kilo-Org/agentic-path/issues) or look for pages that could use improvement. Not sure where to start? Ask in [Discord](https://kilo.love/discord). + +When you find something you want to work on, comment on the issue to let others know you're tackling it. + +### 2. Set up locally + +```bash +# Fork and clone +git clone https://github.com/YOUR-USERNAME/agentic-path.git +cd agentic-path + +# Install dependencies +bun install + +# Start dev server +bun dev +``` + +The site runs at `http://localhost:4321`. + +### 3. Make your changes + +Create a branch, make your edits, preview locally. + +### 4. Open a PR + +Push your branch and open a pull request. Include: + +- What you changed +- Why you changed it +- Any context reviewers need + +## Writing guidelines + +Match the existing tone: + +- **Direct and practical** — Get to the point +- **Second person** — "You" not "the developer" +- **Short paragraphs** — 3-5 sentences max +- **Real examples** — Show, don't just tell +- **No fluff** — Every sentence should earn its place + +### What we want + +- Real-world experience over theory +- Practical examples people can use +- Honest assessments (including limitations) +- Clear, scannable structure + +### What we don't want + +- Marketing speak or product pitches +- Unverified "10x productivity" claims +- AI-generated filler content +- Duplicate coverage of existing topics + +## Page structure + +Every page needs frontmatter: + +```yaml +--- +title: Your Page Title +description: A one-sentence description for SEO and previews +sidebar: + order: 1 # Position in sidebar (optional) +--- +``` + +Use clear headings, short paragraphs, and include a Resources section at the bottom for further reading. + +## Review process + +1. **Automated checks** — Build must pass +2. **Human review** — Usually within a week +3. **Feedback** — We might suggest changes +4. **Merge** — Once approved, we'll merge it + +We check for: + +- Accuracy of information +- Match with existing style +- Value for readers +- No broken links or build errors + +## Community + +### Be excellent to each other + +- Assume good intent +- Respectful disagreement is welcome +- Help newcomers feel welcome +- Remember there's a human on the other end + +### When giving feedback + +- Be constructive, not just critical +- Suggest improvements +- Acknowledge what works well + +### When receiving feedback + +- Don't take it personally +- Ask clarifying questions +- It's okay to disagree—discuss it + +## Recognition + +Your contributions are recognized through: + +- Git history (permanent record) +- GitHub contributors page +- Release notes for significant contributions + +## Questions? + +- **Quick questions** — [Discord](https://kilo.love/discord) +- **Longer discussions** — [GitHub Discussions](https://github.com/Kilo-Org/agentic-path/discussions) +- **Bug reports** — [GitHub Issues](https://github.com/Kilo-Org/agentic-path/issues) + +## License + +By contributing, you agree that your contributions will be licensed under the MIT License. + +--- + +Thanks for helping build this. Every improvement helps someone work better with AI agents. diff --git a/src/content/docs/ru/community/index.md b/src/content/docs/ru/community/index.md new file mode 100644 index 0000000..8d67c2b --- /dev/null +++ b/src/content/docs/ru/community/index.md @@ -0,0 +1,119 @@ +--- +title: Join the Community +description: Connect with others learning agentic engineering—we're all figuring this out together +sidebar: + order: 0 +--- + +Agentic engineering is new territory. Nobody has all the answers. The best way to learn is together. + +## Why community matters + +AI tools change weekly. What worked last month might be obsolete. What you discovered yesterday might help someone today. + +**This isn't just documentation—it's a conversation.** We're building shared knowledge about a field that's still being invented. + +## Where to connect + +### Discord + +**[Join our Discord →](https://kilo.love/discord)** + +The fastest way to get help and share what you're learning: + +- Ask questions (no question is too basic) +- Share wins and failures +- Discuss new tools and techniques +- Get feedback on your approach + +### GitHub Discussions + +**[Browse discussions →](https://github.com/Kilo-Org/agentic-path/discussions)** + +For longer-form conversations: + +- Propose new content or features +- Debate best practices +- Share detailed case studies +- Discuss the future of agentic engineering + +### GitHub Issues + +**[View issues →](https://github.com/Kilo-Org/agentic-path/issues)** + +For specific improvements: + +- Report bugs or broken links +- Request new topics +- Track work in progress + +## How to participate + +### Share your experience + +The most valuable contributions are real stories: + +- What worked when you tried a new approach? +- What failed spectacularly? +- What do you wish you'd known earlier? +- What's different about your context (language, team size, industry)? + +### Ask questions + +Seriously. Your questions help everyone: + +- They reveal gaps in the documentation +- They surface common confusion points +- They often lead to better explanations + +### Help others + +When you figure something out, share it: + +- Answer questions in Discord +- Add resources to relevant pages +- Write up your experience as a case study + +## Community guidelines + +### Be excellent to each other + +- Assume good intent +- Respectful disagreement is welcome +- Personal attacks are not +- Help newcomers feel welcome + +### Share honestly + +- Admit when you don't know +- Include failures, not just successes +- Cite sources when sharing others' work +- No marketing or self-promotion + +### Stay practical + +- Focus on what actually works +- Share specific examples +- Avoid hype and buzzwords +- Question claims that sound too good + +## What we're building together + +This guide is open source. Every page can be improved. Every section can be expanded. + +**Your experience is the content.** We're not writing theory—we're documenting what works in practice. That requires input from people doing the work. + +See [Contributing](/community/contributing/) to get started. + +## Recognition + +We recognize contributors through: + +- Git history (your commits are permanent) +- GitHub contributors page +- Shoutouts for significant contributions +- Community spotlights in Discord + +## Questions? + +Not sure where to start? Drop into [Discord](https://kilo.love/discord) and say hi. We're friendly. diff --git a/src/content/docs/ru/engineers/best-practices.md b/src/content/docs/ru/engineers/best-practices.md new file mode 100644 index 0000000..b20225e --- /dev/null +++ b/src/content/docs/ru/engineers/best-practices.md @@ -0,0 +1,235 @@ +--- +title: Best Practices +description: Context engineering, common failure modes, and building AI-compatible codebases +sidebar: + order: 3 +--- + +The difference between agents that reliably ship code and agents that spin their wheels? Context. Learning to engineer context—and structure your code to help agents succeed—makes agentic development predictable. + +## Context engineering + +Context engineering is the discipline of providing AI agents with the right information at the right time. It's not just prompt engineering—it's the entire system of what an agent knows when it makes decisions. + +Think of it this way: an agent's context window is its entire working memory. Everything it can "see" at once—your instructions, the code, conversation history, tool outputs—shapes every decision it makes. Engineer that context poorly, and even the smartest model produces garbage. + +### Why context matters more than prompts + +A perfect prompt with bad context fails. A mediocre prompt with excellent context often succeeds. + +**Context includes:** + +- **System instructions** — The agent's baseline behavior and constraints +- **Codebase knowledge** — Files, patterns, conventions the agent can reference +- **Conversation history** — What's been discussed and decided +- **Tool outputs** — Results from file reads, command execution, searches +- **External documentation** — API docs, specs, requirements + +**Prompts are just one piece.** The agent's entire context window determines output quality. + +### The context engineering workflow + +**1. Curate what goes in** + +Not everything belongs in context. More isn't better—it's often worse. Irrelevant context dilutes signal and wastes tokens. + +Ask: What does the agent _need_ to complete this task? Include that. Exclude everything else. + +**2. Structure for retrieval** + +Agents scan context looking for relevant information. Make it findable: + +- Use clear headings and sections +- Put critical constraints early +- Group related information together +- Use consistent formatting + +**3. Manage context lifecycle** + +Context windows fill up. When they do, older content gets truncated—the agent literally forgets it. + +- Start fresh conversations for new tasks +- Summarize long discussions before continuing +- Re-state critical constraints when context is getting full +- Use tools like AGENTS.md to persist important context across sessions + +### Practical context techniques + +**Include relevant code, not all code.** If you're modifying a function, include that function and its direct dependencies. Don't dump the entire codebase. + +**Provide examples of desired output.** Show the agent what good looks like. A single example often beats paragraphs of description. + +**State constraints explicitly.** "Don't modify the public API" is context. "Follow the error handling pattern in auth.ts" is context. Make implicit knowledge explicit. + +**Use documentation as context.** When working with unfamiliar APIs, paste relevant docs into the conversation. The agent can't hallucinate what's right in front of it. + +**Leverage persistent context files.** AGENTS.md, README files, and similar documents provide context that persists across sessions. Keep them current. + +### Context anti-patterns + +**Kitchen sink context** — Dumping everything "just in case." Dilutes signal, wastes tokens, confuses the agent. + +**Stale context** — Outdated documentation or code that contradicts current state. Leads to hallucinations and wrong assumptions. + +**Implicit context** — Assuming the agent knows things you haven't told it. Your mental model isn't in the context window. + +**Context fragmentation** — Spreading related information across many messages. Group related context together. + +## Failure modes to watch + +Agents fail in predictable ways. Learning these patterns helps you catch problems early. + +### Hallucinations + +Agents use APIs, methods, or parameters that don't exist. Code looks right but fails at runtime. + +**Triggers:** Less popular libraries, recently changed APIs, domain-specific tools. + +**Catch it:** Be suspicious of unfamiliar method names. Verify imports exist. Run the code—don't just read it. + +**Prevent it:** Include relevant docs in your context. Use well-known patterns. Ask the agent to explain its reasoning. + +### Drift + +The agent starts solving your problem but gradually shifts to a different, easier problem. + +**Triggers:** Long prompts with multiple objectives. Ambiguous requirements. + +**Catch it:** Re-read the original requirement after each iteration. Ask: "Does this still address my actual problem?" + +**Prevent it:** Break into smaller, focused pieces. State success criteria explicitly. + +### Looping + +The agent tries the same failing approach repeatedly with minor variations. + +**Triggers:** Errors the agent doesn't understand. Tasks beyond capability. Missing context. + +**Catch it:** Track iterations—if you're past 3-4, something's wrong. + +**Prevent it:** Provide error context. Break out manually and try a different approach. + +### Overconfidence + +The agent declares success when code doesn't work, or claims certainty about incorrect information. + +**Catch it:** Never trust self-assessment. Run the code yourself. Write tests for actual requirements. + +**Prevent it:** Ask how it verified correctness. Request specific edge case tests. + +### Context overflow + +Early context gets "forgotten" as conversations grow. Agent contradicts earlier decisions or ignores constraints. + +**Triggers:** Long conversations. Large codebases in context. Complex multi-step tasks. + +**Catch it:** Watch for inconsistencies. Notice when agent asks for info you already provided. + +**Prevent it:** Keep conversations focused and short. Start fresh for new tasks. Re-state critical context. + +### Plausible nonsense + +Code looks sophisticated but fundamentally misunderstands the problem or domain. + +**Catch it:** Trace logic mentally—does it make sense? Get domain expert review. + +**Prevent it:** Provide domain context explicitly. Include examples of correct solutions. + +## Building AI-compatible code + +The same patterns that help new developers help agents: clear structure, explicit types, good documentation, consistent patterns. + +### Structure + +**Keep files focused.** One concept per file. Agents request specific files—make those requests useful. + +**Use descriptive names.** `UserAuthenticationService.ts` beats `uas.ts`. Agents infer purpose from names. + +**Flatten when possible.** Deep nesting forces agents to understand hierarchy. + +**Keep functions short.** Under 50 lines. Single responsibility. Clear inputs and outputs. + +### Types and contracts + +**Use types generously.** TypeScript, Python type hints. Types are machine-readable documentation. + +```typescript +// Harder for agents +function process(data) { + /* what's data? */ +} + +// Easier for agents +function processOrder(order: Order): ProcessedResult { + /* clear context */ +} +``` + +**Define interfaces at boundaries.** Explicit interfaces prevent integration bugs. + +**Avoid any/unknown.** More type information enables better inference. + +### Documentation + +**Document the "why," not the "what."** Agents read what code does. They can't read your mind. + +```typescript +// Less useful +// This function calculates the discount +function calculateDiscount(order: Order): number; + +// More useful +// Business rule: Premium customers get 10% off orders over $100 +// This discount stacks with promotional codes +function calculateDiscount(order: Order): number; +``` + +**Keep READMEs current.** Agents often start by reading them. Outdated docs mislead. + +**Document non-obvious constraints.** Rate limits, known limitations, things that "just work that way." + +### Testing + +**Write tests as specification.** Tests tell agents what code should do. + +**Keep tests fast.** Agents run tests frequently. Slow tests break feedback loops. + +**Test edge cases explicitly.** Tests covering edges tell agents about edges they might miss. + +**Use descriptive names.** `test_user_creation_fails_with_duplicate_email` beats `test_user_3`. + +### Patterns to avoid + +- **Magic and metaprogramming** — Dynamic method generation, heavy reflection confuse agents +- **Implicit dependencies** — Service locators, ambient context hide needed information +- **Circular dependencies** — Confuse agents about what depends on what +- **Inconsistent patterns** — If you do the same thing three ways, agents won't know which to follow + +## Incremental improvement + +You don't need to rewrite everything. As you touch code: + +- Improve the file you're modifying +- Add types where you add code +- Write a test when you fix a bug +- Update docs when you discover they're wrong + +Over time, the codebase becomes more agent-friendly—and more human-friendly. + +## Resources + +### Context engineering + +- [Context Engineering for AI Agents – Tobi Lutke](https://x.com/tolobi/status/1935533391175041359) - Shopify CEO on why context engineering is the new skill +- [Context Engineering – Andrej Karpathy](https://x.com/karpathy/status/1937902205765607626) - "Prompt engineering is dead, context engineering is king" +- [AGENTS.md](https://agents.md/) - Open format for persistent agent context, used by 60k+ open-source projects + +### Failure modes and recovery + +- ["I shipped code I don't understand" – Jake Nations, Netflix](https://www.youtube.com/watch?v=eIoohUmYpGI) - The "Infinite Software Crisis" and how to avoid it +- [Agent Readiness – Eno Reyes, Factory AI](https://www.youtube.com/watch?v=ShuJ_CN6zr4) - Eight categories for agent-ready codebases + +### Deep dives + +- [No Vibes Allowed – Dex Horthy, HumanLayer](https://www.youtube.com/watch?v=rmvDxxNubIg) - Making agents work in 300k LOC codebases +- [RepoCoder: Repository-Level Code Completion](https://arxiv.org/abs/2303.12570) - Framework for leveraging repository context diff --git a/src/content/docs/ru/engineers/getting-started.md b/src/content/docs/ru/engineers/getting-started.md new file mode 100644 index 0000000..126fefc --- /dev/null +++ b/src/content/docs/ru/engineers/getting-started.md @@ -0,0 +1,108 @@ +--- +title: Getting Started with Agentic Tools +description: Your first steps into AI-assisted development and when to delegate +sidebar: + order: 1 +--- + +Pick one tool and learn it well before trying everything. + +## Choose your first tool + +**New to AI coding?** Start with GitHub Copilot or similar. Low risk, immediate value. + +**Ready for more autonomy?** Try a task-level agent like Cursor, Cline, or Kilo Code for multi-file changes. + +**Exploring?** Most tools have free tiers. Try a few, commit to one for deep learning. + +## Your first session + +Start small—don't generate your whole project. + +**Good first tasks:** + +- Generate a single function from a clear description +- Write tests for existing code +- Add documentation to confusing code +- Refactor a small, messy piece + +**Watch how it works:** Notice what context it uses, how it handles ambiguity, where it makes mistakes. + +## Build prompting intuition + +**Be explicit:** Instead of "fix this bug," try "The function `calculateTotal` returns NaN when items array is empty. Add a check that returns 0." + +**Provide context:** "This is a React component using TypeScript. Follow the pattern in other components in this folder." + +**Set constraints:** "Don't modify the public API. Keep backward compatibility." + +## When to delegate + +Not every task should go to an agent. Ask yourself: + +1. **How clear is the task?** Vague tasks fail. Clear tasks succeed. +2. **How much context is needed?** Deep domain knowledge is risky to delegate. +3. **What's the blast radius?** Mistakes in critical paths cost more to fix. +4. **How long would I take?** If it's 5 minutes manually, prompting might not be worth it. + +### Good candidates + +| Task type | Why it works | +| ------------------------------------ | -------------------------------------------------- | +| **Boilerplate** (CRUD, DTOs, config) | Repetitive, well-defined, low-risk | +| **Tests** | Self-validating—you know immediately if they work | +| **Documentation** | Easy to verify accuracy | +| **Mechanical refactoring** | Renaming, extracting functions, syntax conversions | +| **Bug fixes with clear repro** | "When X happens, Y occurs, but should be Z" | + +### Keep for yourself + +- **Architectural decisions** — Agents don't understand your system's history or future +- **Security-sensitive code** — Cost of subtle errors is too high +- **Performance-critical paths** — Agents optimize for correctness, not speed +- **Novel algorithms** — Agents pattern-match; new problems need human creativity +- **Ambiguous requirements** — Clarify before delegating + +### The gray zone + +For tasks that don't fit cleanly: **start with the agent, prepare to take over.** Get initial structure from the agent, then refine manually. + +## Build habits + +**Week 1:** Boilerplate and tests only +**Week 2:** Add documentation and refactoring +**Week 3:** Feature implementation with clear specs +**Week 4:** Complex, multi-step tasks + +## Know when to stop + +Signs you should code it yourself: + +- You've reprompted 3+ times without progress +- The task requires deep context the agent doesn't have +- You could finish manually in the time spent prompting + +There's no shame in manual coding. The goal is productivity, not agent usage. + +## Resources + +### Essential + +- [Research → Plan → Implement Framework](https://www.alexkurkin.com/guides/claude-code-framework) - Systematic approach to AI-assisted development +- [AGENTS.md](https://agents.md/) - Open format for guiding agents, used by 60k+ projects +- [The Minimum Every Developer Must Know About AI Models](https://blog.kilo.ai/p/minimum-every-developer-must-know-about-ai-models) - Baseline knowledge to avoid breaking things + +### Deep dives + +- [AI Engineering at Jane Street – John Crepezzi](https://www.youtube.com/watch?v=0ML7ZLMdcl4) - Building custom AI tools for specialized languages +- [What is Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) - The standard for AI integrations +- [Code research projects with async coding agents](https://simonwillison.net/2025/Nov/6/async-code-research/) - Practical pattern for asynchronous agent research + +### Courses + +- [Prompt Engineering Specialization – Vanderbilt University](https://www.coursera.org/specializations/prompt-engineering) - Comprehensive prompt engineering course +- [Understanding Prompt Engineering – DataCamp](https://www.datacamp.com/courses/understanding-prompt-engineering) - Beginner prompt engineering fundamentals + +--- + +**Found a resource that helped you get started?** [Add it to this page](/community/contributing/)—your recommendation might be exactly what someone else needs. diff --git a/src/content/docs/ru/engineers/task-decomposition.md b/src/content/docs/ru/engineers/task-decomposition.md new file mode 100644 index 0000000..ee59aea --- /dev/null +++ b/src/content/docs/ru/engineers/task-decomposition.md @@ -0,0 +1,154 @@ +--- +title: Working with Agents +description: Task decomposition and validating output +sidebar: + order: 2 +--- + +The biggest mistake new agentic engineers make: asking for too much at once. + +## Why decomposition matters + +Agents work best with bounded, clear tasks. When you ask for too much: + +- Context overflows and early details get lost +- Errors compound as later steps build on earlier mistakes +- Recovery from failures wastes everything before + +Small tasks mean faster feedback, easier debugging, better results. + +## The three-part rule + +Before prompting, ask: Can I describe this in three parts? + +1. **What** — The specific outcome I want +2. **Where** — Which files/functions to touch +3. **Constraints** — What not to change + +If you can't articulate all three, the task is probably too big. + +## Decomposition strategies + +### Vertical slicing + +Cut by feature path, not technical layer. + +**Instead of:** + +- "Create the database schema" +- "Build the API endpoints" +- "Create the frontend forms" + +**Try:** + +- "Create user creation flow: schema, endpoint, and basic form" +- "Add user editing: update endpoint and form" +- "Add user deletion: endpoint with confirmation" + +Each slice is complete and testable. + +### Dependency ordering + +When tasks have dependencies, make them explicit: + +1. Define the data model types (no external deps) +2. Build the storage layer (depends on types) +3. Create the API (depends on storage) +4. Build the UI (depends on API) + +Each step should work in isolation before moving on. + +## Sizing tasks + +**Too small:** "Add a semicolon to line 47" — faster to do yourself + +**Too big:** "Build the authentication system" — too many decisions + +**Just right:** "Create a login form that posts to /api/auth/login and stores the token in localStorage" — clear scope, testable result + +## The prompt template + +``` +Task: [What you want done] + +Context: +- [Relevant background] +- [Related files or patterns to follow] + +Constraints: +- [What not to change] +- [Patterns to follow] + +Success criteria: +- [How you'll know it's done] +``` + +## Validating output + +Agent output looks plausible. That's the danger. Treat agent code like code from a talented junior: probably works for the happy path, might miss edge cases, may not follow your conventions. + +### Validation checklist + +**1. Does it solve the problem?** +Read the code—don't just run it. Does it address the actual requirement, not just the prompt? + +**2. Check the edges:** + +- Empty inputs +- Null/undefined values +- Boundary conditions (off-by-one, max values) +- Error cases +- Concurrent access + +**3. Look for hallucinations:** + +- API methods that don't exist +- Parameters that don't work as assumed +- Functions called with wrong signatures + +If something's unfamiliar, verify it exists. + +**4. Security review:** + +- Input validation present? +- No SQL/command injection? +- Auth/authorization checked? +- Sensitive data not logged? +- No hardcoded secrets? + +**5. Style and conventions:** + +- Follows existing patterns? +- Names clear and consistent? +- Error messages helpful? + +### When to reject + +**Reject when:** + +- Approach is fundamentally wrong (even if it works) +- Too much refactoring needed to meet standards +- Security issues requiring redesign + +**Accept with modifications when:** + +- Logic sound but style needs adjustment +- Minor edge case handling needed + +**Accept as-is when:** + +- Meets requirements, handles edges, follows conventions, passes security check + +## Resources + +### Essential + +- [Embracing the parallel coding agent lifestyle](https://simonwillison.net/2025/Oct/5/parallel-coding-agents/) - Running multiple agents simultaneously +- [Spec-Driven Development – Al Harris, Amazon Kiro](https://www.youtube.com/watch?v=HY_JyxAZsiE) - How specs enable reproducible AI delivery +- [Your job is to deliver code you have proven to work](https://simonwillison.net/2025/Dec/18/code-proven-to-work/) - Why testing AI code is non-negotiable + +### Deep dives + +- [Spec Kit](https://github.com/github/spec-kit) - GitHub's framework for spec-driven development +- ["I shipped code I don't understand" – Jake Nations, Netflix](https://www.youtube.com/watch?v=eIoohUmYpGI) - Three-phase methodology to avoid "vibecoding to disaster" +- [No Vibes Allowed – Dex Horthy, HumanLayer](https://www.youtube.com/watch?v=rmvDxxNubIg) - Frequent intentional compaction for large codebases diff --git a/src/content/docs/ru/executives/adoption-playbook.md b/src/content/docs/ru/executives/adoption-playbook.md new file mode 100644 index 0000000..f523ac2 --- /dev/null +++ b/src/content/docs/ru/executives/adoption-playbook.md @@ -0,0 +1,149 @@ +--- +title: Overcoming Adoption Blockers +description: Common resistance patterns and how to address them +sidebar: + order: 3 +--- + +Adoption doesn't fail because of technology. It fails because of people, process, and organizational friction. Here are the common blockers and how to address them. + +## Resistance patterns + +### "It's going to take my job" + +**The concern:** Engineers fear obsolescence. + +**The reality:** Tools change what engineers do, not whether engineers are needed. But the fear is real and affects adoption. + +**What to do:** + +- Be honest: roles will evolve, not disappear +- Reframe: these tools amplify your value +- Invest in upskilling so engineers feel empowered, not threatened +- Avoid automation-replacement language + +### "The output quality isn't good enough" + +**The concern:** Code quality will suffer. Technical debt will accumulate. + +**The reality:** Valid concern. AI output needs review. But quality depends on usage, not just tools. + +**What to do:** + +- Establish review standards for AI-generated code +- Start with low-risk applications +- Track quality metrics to show actual impact (positive or negative) +- Empower teams to reject agents where they don't help + +### "It's too slow / disrupts my flow" + +**The concern:** Context switching to an agent breaks concentration. + +**The reality:** For some developers and some tasks, this is true. Workflow fit matters. + +**What to do:** + +- Don't mandate universal usage +- Let developers find their own integration points +- Recognize that optimal usage varies by person +- Share techniques that minimize disruption + +### "Security and IP risk is too high" + +**The concern:** Sending code to external APIs exposes proprietary information. + +**The reality:** This is a legitimate concern for some organizations and some code. + +**What to do:** + +- Understand exactly what data flows where +- Use enterprise plans with appropriate data handling +- Consider self-hosted or local models for sensitive work +- Define clear policies about what can/cannot be shared + +### "We don't have time to learn new tools" + +**The concern:** Learning curve is a distraction from real work. + +**The reality:** There's always "real work." But capability investments compound. + +**What to do:** + +- Acknowledge the short-term cost +- Start with volunteers, not mandates +- Build in dedicated learning time +- Show early wins to build momentum + +## Process mismatches + +### Change control resistance + +**The problem:** Existing change processes weren't designed for AI-assisted development. + +**Solution:** Adapt processes rather than abandoning them. Define how AI code fits existing controls. + +### Toolchain integration + +**The problem:** AI tools don't integrate cleanly with existing IDE, CI/CD, review systems. + +**Solution:** Accept some friction initially. Prioritize integration investments based on pain. + +### Metrics disruption + +**The problem:** Existing metrics (lines of code, commit frequency) become misleading. + +**Solution:** Update metrics to reflect outcomes, not activity. Accept a metrics gap during transition. + +## Undefined success criteria + +**The problem:** No one agrees on what "successful adoption" means. + +**What happens:** Different stakeholders judge success differently. Same data, different conclusions. + +**Solution:** Define success criteria before rolling out: + +- What adoption rate do we expect at 3/6/12 months? +- What productivity indicators would show value? +- How will we measure quality impact? +- What developer satisfaction target matters? + +## The adoption playbook + +### Phase 1: Enable (Months 1-2) + +- **Make tools available** to volunteers +- **Provide basic training** (2-4 hours) +- **Gather feedback** actively +- **No pressure, no mandates** + +### Phase 2: Learn (Months 2-4) + +- **Expand access** based on demand +- **Identify internal champions** +- **Document what works** in your context +- **Address concerns** as they surface + +### Phase 3: Integrate (Months 4-8) + +- **Update processes** to accommodate AI workflows +- **Train more deeply** on advanced techniques +- **Measure outcomes** against baseline +- **Scale support** resources + +### Phase 4: Optimize (Ongoing) + +- **Refine practices** based on experience +- **Track evolving tools** and capabilities +- **Share learnings** across teams +- **Plan next integration level** + +## Resources + +### Essential + +- [Stop Peanut Buttering AI Onto Your Organization](https://blog.kilo.ai/p/stop-peanut-buttering-ai) - Why surface-level adoption fails + +### Videos + +- [Leadership in AI Assisted Engineering – Justin Reock, DX](https://www.youtube.com/watch?v=PmZDupFP3UM) - Leading AI-enabled engineering organizations +- [Moving away from Agile – Martin Harrysson, McKinsey](https://www.youtube.com/watch?v=SZStlIhyTCY) - Why operating model changes are required diff --git a/src/content/docs/ru/executives/ai-native-economics.md b/src/content/docs/ru/executives/ai-native-economics.md new file mode 100644 index 0000000..9c9f4e8 --- /dev/null +++ b/src/content/docs/ru/executives/ai-native-economics.md @@ -0,0 +1,130 @@ +--- +title: "The Economics of the AI-Native Organization" +description: Why the correlation between headcount and output is breaking—and what it means for competition +sidebar: + order: 6 +--- + +The startup playbook is being rewritten. Companies like Cursor hit $100M ARR in 21 months with 20 people. Midjourney reached $200M ARR with 10 employees. Bolt went from zero to $20M ARR in two months with a team of 15. + +These aren't outliers anymore. They're signals of a structural shift in how companies scale. + +## The old equation is breaking + +For decades, the formula was simple: more output requires more people. Engineering capacity scaled linearly with headcount. If you needed to ship twice as much, you hired roughly twice as many engineers. + +AI breaks this relationship. A [Harvard and Wharton study at P&G](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5188231) demonstrated that individuals using AI tools performed as well as entire teams without AI. The multiplier effect isn't marginal—it's transformational. + +[Anthropic's internal research](https://www.anthropic.com/research/how-ai-is-transforming-work-at-anthropic) shows their engineers using Claude in 60% of their work, achieving a 50% productivity boost—a 2-3x increase from the previous year. And critically, 27% of their AI-assisted work consists of tasks that wouldn't have been done otherwise. + +That last point is the one executives should circle. AI isn't just making existing work faster. It's enabling new work that was previously cost-prohibitive. + +## The competitive math + +Consider two companies competing in the same market: + +**Company A (Traditional):** 50 engineers, each shipping roughly the same output as last year. Total engineering cost: $10M annually. Output: X. + +**Company B (AI-Native):** 15 engineers, each managing AI agent workflows and producing 3x individual output. Total engineering cost: $3M annually. Output: ~X (or higher). + +Company B has a 70% cost advantage while matching or exceeding output. They can undercut on price, invest more in product, or simply grow faster with less capital. + +This isn't theoretical. [The VC Corner tracks](https://www.thevccorner.com/p/the-billion-dollar-startup-formula) AI-native companies reaching significant revenue with tiny teams: + +- **Cursor (Anysphere):** $100M ARR, 20 people +- **Midjourney:** $200M ARR, 10 people +- **ElevenLabs:** $100M ARR, 50 people +- **Bolt (StackBlitz):** $20M ARR in 2 months, 15 people +- **Mercor:** $50M ARR, 30 people + +Sam Altman [predicts](https://x.com/tsarnick/status/1754318725971583238) multiple one-person unicorns will emerge. Solo founders now account for 35% of the 2024 startup class according to Carta. + +## The cost structure shift + +Traditional org design assumes certain functions require certain headcounts. AI-native companies challenge every assumption: + +| Function | Traditional Approach | AI-Native Approach | +|----------|---------------------|-------------------| +| Customer Support | Team of 10 handling tickets | 2 people + AI handling 80% of routine queries | +| QA/Testing | Dedicated QA team | Engineers using AI for automated test generation | +| Documentation | Technical writers | AI-assisted docs generated from code | +| Code Review | Multiple reviewers per PR | AI pre-review + single human reviewer | +| Onboarding | Weeks of ramp-up time | AI-assisted codebase understanding | + +Each of these represents headcount that AI-native competitors simply don't need. + +## Growth without proportional hiring + +The [World Economic Forum notes](https://www.weforum.org/stories/2025/04/how-founders-are-shaping-the-future-of-entrepreneurship-with-ai/) that AI-native startups "accelerate time to market and revenue, reduce the need for scaling teams." This creates a fundamentally different growth curve. + +Traditional scaling: Revenue grows → hire more people → capacity increases → revenue grows further. The constraint is hiring speed and management overhead. + +AI-native scaling: Revenue grows → existing team uses more AI leverage → capacity increases without proportional hiring → revenue grows faster. The constraint is how quickly your team learns to use AI effectively. + +Companies that figure out AI-native workflows first compound their advantages. Those that don't face competitors who move faster with less capital. + +## The "wouldn't have been done" category + +Anthropic's finding about 27% of AI-assisted work being new work deserves executive attention. This includes: + +- **Exploratory work** that was previously too expensive to justify +- **Nice-to-have tooling** that improves quality of life but wasn't prioritized +- **Fixing technical debt** that kept getting pushed to "someday" +- **Broader testing coverage** that seemed impractical + +This is capability expansion, not just efficiency. Organizations using AI for cost reduction alone are missing the bigger opportunity: doing things that were previously impossible at your scale. + +## What this means for incumbents + +If you're running a traditional organization competing against AI-native startups, the math is not in your favor. They can: + +- **Iterate faster** with smaller teams and less coordination overhead +- **Spend less on engineering** while matching your output +- **Experiment more aggressively** because the cost of trying things is lower +- **Attract talent** who want leverage over headcount + +The response isn't to panic-hire AI tools. It's to fundamentally restructure how work flows through your organization. + +## Strategic questions for the C-suite + +**What's your human-agent ratio?** Microsoft's WorkLab [calls this](https://www.microsoft.com/en-us/worklab/ai-at-work-how-human-agent-teams-will-reshape-your-workforce) a new metric every leader will need. How much of your output comes from direct human work vs. AI-assisted work? Are you measuring it? + +**Are you measuring agents as resources?** If you track headcount carefully but have no visibility into AI tool usage and impact, you're flying blind on a major input to your capacity. + +**Where are you overstaffed for the AI era?** Functions that existed because "we need humans for this" may no longer require the same headcount. Which teams could shrink while maintaining output? + +**What work aren't you doing that you could?** The 27% finding suggests AI enables new categories of work. What would your organization build if the cost of trying things dropped by 70%? + +**How fast are your competitors moving?** The risk isn't just that you're slower. It's that AI-native competitors are compounding advantages while you optimize incrementally. + +## The uncomfortable conversation + +AI-native economics suggest many organizations are carrying more headcount than they need for their output levels. This doesn't mean immediate layoffs—it means strategic reallocation. + +The choice isn't "cut people" vs. "keep people." It's: +- **Option A:** Same headcount, same output, competitors pull ahead +- **Option B:** Same headcount, dramatically more output, competitive parity +- **Option C:** Leaner headcount, same output, reinvest savings in growth + +Option B is the opportunity. But it requires genuine transformation in how your organization works, not just adopting new tools. + +## The window is closing + +AI-native startups are already competing for your customers and your talent. The productivity advantages they're demonstrating aren't theoretical—they're showing up in revenue numbers and growth rates. + +The question for executives isn't whether to adopt AI. It's whether you're restructuring fast enough to compete with organizations that were built AI-native from day one. + +## Resources + +### Essential reading + +- [The Billion-Dollar Startup Formula](https://www.thevccorner.com/p/the-billion-dollar-startup-formula) - Why small AI teams are beating giants +- [How human-agent teams will reshape your workforce](https://www.microsoft.com/en-us/worklab/ai-at-work-how-human-agent-teams-will-reshape-your-workforce) - Microsoft on the human-agent ratio +- [How AI Is Transforming Work at Anthropic](https://www.anthropic.com/research/how-ai-is-transforming-work-at-anthropic) - Internal research on productivity gains +- [The Cybernetic Teammate (Harvard/Wharton)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5188231) - Field study on AI team performance + +### Deep dives + +- [Building AI Startups in 2026](https://www.unifiedaihub.com/blog/building-ai-startups-in-2026-lessons-from-founders-navigating-competitive-ai-landscape) - Lessons from founders navigating the AI landscape +- [Tiny Teams in Tech](https://tinyteams.xyz/) - Tracking small teams achieving outsized results +- [AI means smaller teams](https://insideainews.com/2024/04/24/artificial-intelligence-means-smaller-teams-doing-more-with-less-makes-the-small-autonomous-teams-structure-even-more-important/) - Why small autonomous teams become more important diff --git a/src/content/docs/ru/executives/roi-frameworks.md b/src/content/docs/ru/executives/roi-frameworks.md new file mode 100644 index 0000000..2919915 --- /dev/null +++ b/src/content/docs/ru/executives/roi-frameworks.md @@ -0,0 +1,143 @@ +--- +title: ROI Frameworks and Realistic Expectations +description: Understanding what returns are actually achievable +sidebar: + order: 2 +--- + +The marketing says 10x. The reality is more nuanced. Here's how to think about returns—and set expectations that survive contact with reality. + +## The productivity claim landscape + +Vendors claim: + +- "10x developer productivity" +- "Replace half your engineering team" +- "Ship in days what used to take months" + +Research shows: + +- 10-30% improvement in task completion time +- Higher satisfaction among developers +- Significant variation by task type and individual + +The gap between claims and evidence is worth understanding. + +## Where gains actually come from + +### Direct productivity + +**Time savings on specific tasks:** + +- Boilerplate generation: 50-80% faster +- Test writing: 30-50% faster +- Documentation: 40-60% faster +- Bug fixes with clear repro: 20-40% faster + +**Complex implementation:** Minimal measurable improvement, sometimes negative (time spent prompting > time saved). + +### Indirect benefits + +**Capability expansion:** Engineers tackle tasks they wouldn't have attempted. + +**Onboarding acceleration:** New hires reach productivity faster with agent assistance. + +**Knowledge democratization:** Junior developers access expertise embedded in AI training. + +**Developer satisfaction:** People often prefer agent-assisted work (though not universally). + +### What doesn't change + +**Architecture decisions:** Still human. +**Complex debugging:** Often slower with agents. +**Domain expertise:** Can't be delegated. +**Integration work:** High-context, agent-hostile. + +## Building an ROI model + +### Costs + +**Tool costs:** + +- Per-seat licensing +- API usage (for custom solutions) +- Infrastructure for self-hosted options + +**Adoption costs:** + +- Training time +- Process change management +- Initial productivity dip + +**Oversight costs:** + +- Additional code review time +- Security review requirements +- Quality assurance expansion + +### Benefits + +**Time savings:** + +- Engineer hours × improvement % × adoption rate +- Be conservative: assume 15-20% improvement on applicable tasks + +**Quality improvements:** + +- Reduced bugs? (Data unclear—may go either direction) +- Better documentation? (Usually yes) +- Higher test coverage? (Usually yes, if prioritized) + +**Capability gains:** + +- New projects possible with existing headcount +- Faster exploration and prototyping +- Competitive responsiveness + +### The honest math + +For a 50-person engineering team: + +- Tool cost: ~$500-2000/seat/year = $25k-100k annually +- Adoption investment: 20-40 hours/person = $200-400k one-time equivalent +- Realistic productivity gain: 15% on 60% of work = 9% overall +- Value of 9% on $10M engineering spend = $900k + +Payback period: 3-12 months depending on assumptions. + +Not transformational. But clearly positive. + +## Setting expectations + +### What to tell the board + +"We expect 10-30% productivity improvement on applicable tasks, translating to single-digit overall efficiency gains. More importantly, we're building capability for a future where these tools are essential." + +### What to tell engineering + +"Start using these tools where they help. Don't force it where they don't. We're investing in learning, not mandating universal adoption." + +### What to tell yourself + +"This is a capability investment, not a cost-cutting exercise. The real value emerges over 2-3 years as the technology improves and our skills compound." + +### The o16g reframe + +The [Outcome Engineering manifesto](https://o16g.com/) suggests an alternative mental model: stop measuring engineer-hours entirely. If an outcome is worth the compute cost, build it. The traditional backlog exists because human bandwidth was the constraint—with agents, that constraint lifts. Stack rank by expected value per token, not by available engineer-hours. + +## Warning signs in ROI projections + +Be skeptical of projections that: + +- Assume universal adoption +- Use vendor productivity claims without adjustment +- Ignore adoption costs +- Assume immediate full benefit without learning curve +- Don't account for tasks where agents don't help + +## Resources + +### Essential + +- [Stop Looking for AI Coding Spending Caps](https://blog.kilo.ai/p/stop-looking-for-ai-coding-spending) - Why spending caps are counter-productive +- [Does AI Actually Boost Developer Productivity? – Stanford](https://www.youtube.com/watch?v=tbDDYKRFjhk) - Data-driven productivity analysis from 100k developers diff --git a/src/content/docs/ru/executives/security-compliance.md b/src/content/docs/ru/executives/security-compliance.md new file mode 100644 index 0000000..a3e3305 --- /dev/null +++ b/src/content/docs/ru/executives/security-compliance.md @@ -0,0 +1,145 @@ +--- +title: Security, IP, and Compliance +description: Managing risk in AI-assisted development +sidebar: + order: 5 +--- + +AI tools introduce new risk vectors. Understanding and managing them is essential for responsible adoption. + +## Data flow risks + +### What data goes where? + +When developers use AI tools, code and context flow to external services: + +**Prompts include:** + +- Code snippets (sometimes entire files) +- Error messages and stack traces +- File names and structure +- Comments (which may contain sensitive info) + +**Know your data flow:** + +- What leaves your network? +- Where is it processed? +- Is it stored? For how long? +- Is it used for model training? + +### Mitigation strategies + +**Enterprise agreements:** Most vendors offer enterprise plans with data handling guarantees. Review them carefully. + +**Data classification:** Define what can/cannot be shared with external AI services. + +**Local models:** For highly sensitive work, consider local or self-hosted models. + +**Code filtering:** Some tools allow excluding sensitive paths/patterns. + +## Intellectual property considerations + +### The training data question + +AI models were trained on public code. This raises questions: + +**License contamination:** Could AI-generated code introduce license obligations? + +**Copyright status:** Who owns AI-generated code? + +**Patent implications:** Could AI output infringe patents? + +**Current legal status:** Uncertain and evolving. Courts are still deciding. + +### Practical approach + +**Document AI usage:** Know where AI was involved in your codebase. + +**Review for obvious copying:** Reject output that looks like verbatim reproduction. + +**Legal consultation:** For high-stakes situations, involve legal counsel. + +**Watch the legal landscape:** Precedents are being set now. + +### Your proprietary code + +**The concern:** Code you share with AI tools could influence model training, potentially benefiting competitors. + +**Mitigations:** + +- Enterprise agreements with training opt-out +- Self-hosted models for sensitive code +- Limiting what context is shared + +## Compliance requirements + +### Regulated industries + +Healthcare, finance, government, and other regulated sectors have specific requirements: + +**Data residency:** Where can code/data be processed? + +**Audit trails:** Can you demonstrate what AI was used for? + +**Access controls:** Who can use AI tools? On what data? + +**Incident response:** What if AI exposes sensitive data? + +### Compliance checklist + +- [ ] Data handling agreements reviewed with legal +- [ ] Data residency requirements checked +- [ ] Audit logging in place for AI tool usage +- [ ] Access controls appropriate for data sensitivity +- [ ] Incident response plan updated for AI scenarios +- [ ] Employee training on AI data handling + +## Security of AI-generated code + +### New attack vectors + +AI-generated code can introduce vulnerabilities: + +**Insecure patterns:** Models may generate code with known vulnerabilities. + +**Dependency confusion:** Agents may suggest packages that don't exist (or malicious ones that do). + +**Logic vulnerabilities:** Subtle security bugs in plausible-looking code. + +### Mitigation + +**Security scanning:** Run SAST/DAST on all code, regardless of origin. + +**Dependency verification:** Verify all packages suggested by AI exist and are legitimate. + +**Human review for security-sensitive code:** Don't let AI generate auth, encryption, or input validation unreviewed. + +**Penetration testing:** Include AI-generated code in security assessments. + +## Governance structures + +### Policy requirements + +At minimum, define: + +**Usage policy:** Who can use what tools, on what code. + +**Data handling policy:** What can be shared with external AI. + +**Review requirements:** How is AI code reviewed and approved. + +**Incident handling:** What to do if AI causes a security issue. + +### Accountability + +**Clear ownership:** Humans own the code they commit, regardless of AI involvement. + +**Audit capability:** Be able to identify AI involvement in code if needed. + +**No blame-shifting:** "The AI did it" is not an excuse. + +## Resources + +### Essential + +- [Government Agents – Mark Myshatyn, Los Alamos](https://www.youtube.com/watch?v=TnSGx36Ly0Q) - AI agents in high-security regulated environments diff --git a/src/content/docs/ru/executives/strategic-vision.md b/src/content/docs/ru/executives/strategic-vision.md new file mode 100644 index 0000000..ebdec6b --- /dev/null +++ b/src/content/docs/ru/executives/strategic-vision.md @@ -0,0 +1,138 @@ +--- +title: Strategic Vision for AI Integration +description: Thinking beyond tools to end-to-end transformation +sidebar: + order: 1 +--- + +AI coding tools are just the beginning. The strategic question isn't whether to adopt, but how deeply to integrate AI across your entire software development lifecycle. + +## Beyond point solutions + +Most organizations start with individual tools: a copilot here, a chatbot there. This is natural but limited. + +The end-game is different: AI woven through every phase of development, from requirements to production monitoring. Organizations that get there first will have structural advantages. + +## The integration spectrum + +The [o16g Manifesto](https://o16g.com/) argues for a fundamental reframe: with AI removing human bandwidth constraints, we should manage to *cost* (tokens) instead of *capacity* (engineer-hours). The backlog, in this view, is "a relic of human limitation" — never reject an idea for lack of time, only for lack of budget. + +This reframing changes how you think about each integration level: + +### Level 1: Tool adoption + +Individual developers use AI tools. No organizational change. + +**Status:** Most companies are here. +**Value:** 10-30% productivity improvement for adopters. +**Risk:** Fragmented, inconsistent, no compounding benefits. + +### Level 2: Process integration + +Agents integrated into workflows. Code review, CI/CD, documentation. + +**Status:** Leading companies are implementing. +**Value:** Systematic efficiency gains. Quality improvements. +**Risk:** Requires process changes. Some resistance. + +### Level 3: Development transformation + +AI in every phase: planning, architecture, implementation, testing, deployment, monitoring. + +**Status:** Experimental. Early pioneers. +**Value:** Fundamental capability expansion. New things become possible. +**Risk:** Significant investment. Unknown failure modes. + +### Level 4: AI-native development + +Humans orchestrate AI systems that handle most implementation. Focus shifts to strategy, design, and judgment. + +**Status:** Theoretical. Research territory. +**Value:** Massive leverage if achieved. +**Risk:** Unknown timeline. Uncertain path. + +## Strategic questions + +As an executive, you need answers to: + +**Where are we on this spectrum?** Honest assessment, not aspirational. + +**Where should we be in 12/24/36 months?** Based on competitive landscape and capability. + +**What's blocking progress?** Skills, tools, process, culture, investment? + +**What's the cost of moving too slow?** Competitive risk, talent retention, opportunity cost. + +**What's the risk of moving too fast?** Quality issues, security exposure, team burnout. + +## Building vs. buying + +### Buy (use off-the-shelf tools) + +**Pros:** + +- Fast adoption +- Low upfront investment +- Benefit from vendor R&D + +**Cons:** + +- Same tools as competitors +- Limited customization +- Dependency on vendor roadmap + +### Build (custom AI solutions) + +**Pros:** + +- Competitive differentiation +- Tailored to your domain +- Control over roadmap + +**Cons:** + +- Significant investment +- Talent requirements +- Slower to start + +### Hybrid (the common path) + +- Use off-the-shelf tools for general tasks +- Build custom solutions for domain-specific advantages +- Integrate both into cohesive workflows + +Most organizations will follow this path. The question is what to build and when. + +## The talent equation + +AI tools don't reduce headcount need—they change what headcount does. + +**More valuable:** + +- Engineers who can orchestrate AI effectively +- People who understand architecture and systems +- Domain experts who can guide AI output + +**Less differentiated:** + +- Raw coding speed +- Syntax memorization +- Boilerplate generation + +Your talent strategy needs to evolve accordingly. + +## Resources + +### Essential + +- [Dispatch from the Future – Dan Shipper, Every](https://www.youtube.com/watch?v=MGzymaYBiss) - "Compounding Engineering" and organizational transformation +- [The o16g Manifesto](https://o16g.com/) - "Outcome Engineering" — 16 principles for managing to cost instead of capacity + +### Deep dives + +- [AI in Product Development: Netflix, BMW, PepsiCo](https://www.virtasant.com/ai-today/ai-in-product-development-netflix-bmw) - Enterprise case studies +- [AI Product Development: Why Founders Are Fascinated](https://www.techmagic.co/blog/ai-product-development) - AI reshaping product development + +### Papers & research + +- [AI-assisted Code Authoring at Scale – Meta](https://arxiv.org/abs/2305.12050) - Meta's CodeCompose deployment experience diff --git a/src/content/docs/ru/executives/toy-tool-cycle.md b/src/content/docs/ru/executives/toy-tool-cycle.md new file mode 100644 index 0000000..bf43b3c --- /dev/null +++ b/src/content/docs/ru/executives/toy-tool-cycle.md @@ -0,0 +1,104 @@ +--- +title: The Toy-Tool Cycle +description: Understanding AI maturity phases to time your adoption +sidebar: + order: 5 +--- + +Every AI capability goes through predictable phases. Understanding this cycle helps you time investments and set realistic expectations. + +## The pattern + +New AI capabilities follow a recurring swing: + +1. **Toy phase**: Limited, weird, mostly good for demos and viral content. Obvious failures. Easy to dismiss. +2. **Tool phase**: Someone figures out practical applications. Novelty fades. Becomes infrastructure. +3. **New toy phase**: Mature capability enables unexpected use cases. New frontiers open. Cycle repeats. + +This isn't hype-to-disappointment. It's exploration-to-exploitation-to-exploration. + +## Examples + +### Text generation + +- **Toy (2019)**: GPT-2 writes Harry Potter in various styles. Fun experiment. +- **Tool (2021-2023)**: Customer service bots, email drafters, content automation. +- **New toy (2024+)**: Autonomous agents, multi-step reasoning, agentic coding experiments. + +### Image generation + +- **Toy (2022)**: Pope in a puffer jacket, Balenciaga memes. +- **Tool (2023-2024)**: Marketing concept art, product mockups, design iteration. +- **New toy (2024+)**: Video generation, consistent characters, real-time generation. + +### Video generation + +- **Toy (2023)**: Will Smith eating spaghetti—horrifying, broken, viral. +- **Tool (2025)**: Ads, B-roll, synthetic footage for production use. +- **New toy (emerging)**: Interactive video, personalized content, real-time generation. + +### Coding assistance + +- **Toy (2021)**: "Look, it can write fizzbuzz!" +- **Tool (2023-2024)**: Copilots shipping real code. Measurable productivity gains. +- **New toy (2025+)**: Vibe coding, autonomous agents, multi-hour unsupervised runs. + +## Strategic implications + +### Don't dismiss the toy phase + +The silly demos are reconnaissance. Will Smith eating spaghetti became an actual benchmark—researchers track progress against it. The Pope deepfake raised awareness of risks before bad actors exploited them. + +When you see people doing ridiculous things with new AI capabilities, they're scouting the frontier. The silly use case today often becomes serious infrastructure in 18-24 months. + +### Don't over-invest in the toy phase + +Toys are for learning, not production. When a capability is still producing obvious failures, treat it as R&D. Small experiments. Low stakes. Learning-oriented. + +Premature production deployment burns credibility and resources. + +### Recognize the tool transition + +The signal: boring reliability replaces exciting failures. When the demos stop being impressive because the capability just works, you're entering tool phase. + +This is when serious investment makes sense. The learning curve flattens. Best practices emerge. Integration paths become clear. + +### Watch for the next toy phase + +Mature tools enable new experiments. When something becomes reliable infrastructure, creative applications emerge that push it somewhere unexpected. + +Stay connected to practitioners. The next toy phase often starts with someone asking "what if we tried..." on a mature capability. + +## Timing your adoption + +| Phase | Appropriate investment | Goal | +|-------|----------------------|------| +| Early toy | Minimal. Observation. | Learn what's possible | +| Late toy | Small experiments | Build internal knowledge | +| Early tool | Pilot programs | Validate value proposition | +| Mature tool | Scaled deployment | Capture efficiency gains | +| New toy | Exploration budget | Scout next opportunities | + +The gap from "horrifying demo" to "boring infrastructure" averages about two years. Plan accordingly. + +## Red flags + +**Dismissing toy-phase capabilities entirely.** "That's just a gimmick" is how companies miss transitions. + +**Deploying toy-phase capabilities at scale.** Premature scaling burns trust and resources. + +**Treating tool-phase capabilities as finished.** The next frontier is always opening. + +**Ignoring practitioner experiments.** The people doing weird things with your tools are showing you the future. + +## Questions for your organization + +- Where is each AI capability you're using on this cycle? +- Are you appropriately matching investment to phase? +- Who's doing toy-phase exploration? Is anyone? +- What tool-phase capabilities are you under-utilizing? +- What's the next toy phase you should be watching? + +--- + +*The executives who time this well don't predict the future—they watch the cycle and position accordingly.* diff --git a/src/content/docs/ru/governance/accountability.md b/src/content/docs/ru/governance/accountability.md new file mode 100644 index 0000000..2031523 --- /dev/null +++ b/src/content/docs/ru/governance/accountability.md @@ -0,0 +1,128 @@ +--- +title: Accountability & Provenance +description: Who owns AI-generated code, and how to track it +sidebar: + order: 1 +--- + +**Humans are accountable for the code they commit.** This remains true regardless of how code was generated. "The AI did it" is not a defense. + +## Accountability by role + +### Individual contributor + +**Responsible for:** + +- Quality of code they commit (regardless of origin) +- Appropriate use of AI tools per policy +- Validating AI output before committing +- Understanding code they submit + +### Code reviewer + +**Responsible for:** + +- Reviewing to established standards +- Catching issues regardless of origin +- Raising concerns about quality or patterns + +### Team lead + +**Responsible for:** + +- Team practices around AI use +- Ensuring appropriate training +- Addressing patterns of issues + +### Engineering leadership + +**Responsible for:** + +- Organizational AI policy +- Tool decisions and procurement +- Risk acceptance at org level + +## When things go wrong + +### Production incident from AI code + +1. Treat like any incident—resolution first +2. Post-mortem includes AI involvement as context +3. Process improvements may involve AI practices + +**Don't:** Blame the AI, create special "AI incident" categories, or exempt individuals from accountability. + +### Security vulnerability from AI code + +1. Standard security response +2. Document AI involvement for learning +3. Review: would our process have caught this? + +**Accountability flows to:** Developer who committed it, reviewers who approved it—NOT the AI tool. + +## Code provenance + +Where does AI-generated code come from? Models train on vast public code with various licenses. Output is statistically influenced by training data but typically isn't direct copying. **Legal uncertainty exists**—courts haven't fully resolved how copyright applies to AI output. + +### What we know + +- **Training legality:** Ongoing lawsuits testing fair use; no resolution yet +- **Output ownership:** Person/org prompting is treated as author practically, but not legally settled +- **Verbatim reproduction:** If AI outputs exact copies, original copyright likely applies + +### Risk management + +**Low-risk scenarios:** + +- Boilerplate code anyone would write the same way +- Internal tools with no external distribution +- Code you heavily modify after generation + +**Higher-risk scenarios:** + +- Distributing generated code in products +- Open-source contributions with copyleft licenses +- Unique or distinctive algorithms + +## Tracking AI involvement + +### What to track + +- Which files/commits involved AI assistance +- Which tool was used +- Human review performed + +### How to track + +- **Git commit conventions:** Tags in commit messages +- **Code review annotations:** Note AI involvement in review +- **Tooling:** Some tools log AI interactions + +### Why track + +- Future legal compliance may require it +- Incident response if issues arise +- Regulatory compliance in some industries + +## Edge cases + +**Automated AI changes (CI/CD, bots):** Person who configured automation owns the output. Don't automate consequential changes without human approval. + +**Multi-person AI sessions:** Committer takes responsibility. Should review/understand before committing. + +**AI-assisted review:** Human reviewer still accountable. AI findings must be human-validated. + +## Policy checklist + +1. **Scope:** What activities are covered +2. **Roles:** Who has what accountability +3. **Requirements:** What must happen before commit/merge +4. **Documentation:** What must be recorded +5. **Exceptions:** How to handle special cases +6. **Enforcement:** What happens when policy is violated + +## Resources + +### Essential + +- [Your job is to deliver code you have proven to work](https://simonwillison.net/2025/Dec/18/code-proven-to-work/) - Accountability for AI-generated code diff --git a/src/content/docs/ru/governance/quality-gates.md b/src/content/docs/ru/governance/quality-gates.md new file mode 100644 index 0000000..b91ffe7 --- /dev/null +++ b/src/content/docs/ru/governance/quality-gates.md @@ -0,0 +1,111 @@ +--- +title: Quality Gates +description: Where to require human approval in agentic workflows +sidebar: + order: 2 +--- + +**Quality gates define where human approval is required.** As agents become more capable, gates prevent automation from bypassing critical checkpoints. + +## Types of gates + +### Merge gates + +Requirements before code merges to main/production branches. + +**Standard:** Passing tests, code review approval, no conflicts, docs updated. + +**AI-specific:** Different requirements for AI-heavy PRs? AI assist vs. replace review? Disclosure required? + +### Deployment gates + +Requirements before deploying to environments. + +**Standard:** Pre-deployment tests pass, security scan clean, performance benchmarks met, production approval. + +**AI-specific:** Extra scrutiny for first deploy of AI-generated code? Automated rollback triggers? + +### Design gates + +Approval required before significant architecture changes. + +**Standard:** Design doc approved, security review for sensitive areas, architecture review. + +**AI-specific:** AI can inform but not decide architecture. Human approval required for AI-suggested design changes. + +### Data gates + +Controls around data access and modification. + +**Standard:** Database migration reviewed, data deletion requires approval, PII access controlled. + +**AI-specific:** AI-generated migrations need extra review. No direct AI access to production data. + +## Implementation + +### Technical enforcement + +**CI/CD checks:** Automated testing, coverage thresholds, security scanning, linting. + +**Branch protection:** Required reviewers, status checks must pass, no direct pushes. + +### Process enforcement + +**Required reviewers:** Minimum approvals, specific approvers for specific paths, CODEOWNERS configuration. + +**Checklists:** PR templates with required confirmations, security checkboxes, AI disclosure prompts. + +### Human checkpoints + +**Required human involvement:** + +- Production deployments +- Database migrations +- Security-sensitive changes +- Customer-facing feature changes + +**Cannot be automated:** + +- Final deployment approval (critical systems) +- Architecture decisions +- Security exception approvals +- Compliance sign-off + +## Gate configuration by risk + +| Risk Level | Examples | Gates | +| ------------ | --------------------------------- | ---------------------------------------------------------- | +| **Low** | Docs, tests, style fixes | Automated checks, single reviewer, auto-merge | +| **Medium** | Feature code, non-critical bugs | Full automated checks, human review, standard approval | +| **High** | Security, payments, data handling | Enhanced checks, senior reviewer, security review | +| **Critical** | Auth, encryption, compliance | All gates + security team + lead approval + staged rollout | + +## Agents and gates + +**Agents can:** Run automated checks, flag issues, suggest reviewers, generate artifacts (changelogs, migration scripts). + +**Agents shouldn't:** Approve their own output, bypass human checkpoints, deploy to production without human trigger, grant elevated permissions. + +### Gate anti-patterns + +- **Rubber-stamp gates:** Approval always granted without review +- **Gate proliferation:** So many gates people game them +- **Inconsistent enforcement:** Gates apply sometimes but not others +- **AI gate avoidance:** Routing AI code around tighter reviews + +## Measuring effectiveness + +| Metric | Question | +| --------------- | ------------------------------------ | +| **Pass rate** | Are legitimate changes passing? | +| **Catch rate** | Are issues caught before production? | +| **Latency** | How much do gates slow the process? | +| **Bypass rate** | How often are gates skipped? | + +Use these metrics to tune gates—neither too permissive nor too restrictive. + +## Resources + +### Videos + +- [Agent Readiness – Eno Reyes, Factory AI](https://www.youtube.com/watch?v=example) - Preparing organizations for agentic workflows diff --git a/src/content/docs/ru/governance/security-review.md b/src/content/docs/ru/governance/security-review.md new file mode 100644 index 0000000..8fae04d --- /dev/null +++ b/src/content/docs/ru/governance/security-review.md @@ -0,0 +1,127 @@ +--- +title: Security Review +description: Catching security issues in AI-generated code +sidebar: + order: 3 +--- + +**AI-generated code can introduce security vulnerabilities.** Some are bugs humans write too; some are unique to AI patterns. + +## AI-specific security concerns + +### Pattern-based vulnerabilities + +AI learns from patterns—including vulnerable ones in training data. + +**Common issues:** + +- SQL/command injection +- Insecure deserialization +- Hardcoded credentials +- Missing auth checks +- Insecure defaults + +**Why:** Models optimize for "code that looks right," not "code that's secure." + +### Hallucinated security + +AI may implement security incorrectly: + +- Encryption using weak algorithms +- Authentication that doesn't actually validate +- Authorization checks that can be bypassed +- Input validation missing edge cases + +Code _looks_ secure but isn't. + +### Dependency risks + +AI may suggest packages that: + +- Don't exist (hallucinated—could be typosquatted) +- Have known vulnerabilities +- Are unmaintained + +## Security review checklist + +### Input handling + +- [ ] All user inputs validated +- [ ] Input length limits enforced +- [ ] Paths sanitized (no traversal) +- [ ] URLs validated + +### Authentication & authorization + +- [ ] Auth properly implemented +- [ ] Tokens validated correctly +- [ ] Sessions managed securely +- [ ] Access controls on sensitive operations +- [ ] Authorization checked server-side + +### Data protection + +- [ ] Sensitive data encrypted at rest +- [ ] TLS enforced +- [ ] Secrets not hardcoded +- [ ] No sensitive data in logs + +### Injection prevention + +- [ ] Parameterized database queries +- [ ] Shell commands properly escaped +- [ ] No eval() with user input +- [ ] Template injection prevented + +### Dependencies + +- [ ] All dependencies verified to exist +- [ ] No known vulnerable versions +- [ ] Lock files committed + +## Review by risk level + +| Code Type | Review Level | +| ------------------ | ----------------------------------------------------- | +| Any AI change | Skim for patterns, check inputs, verify deps exist | +| Security-sensitive | Full checklist, manual testing of boundaries | +| Auth/authz | Line-by-line, threat modeling, senior security review | + +## Automated tools + +**Static analysis (SAST):** Run on all code. Won't catch all AI-specific issues, but catches common vulnerabilities. + +**Dependency scanning:** Dependabot, Snyk. Check all deps exist before installing. + +**Secret scanning:** Pre-commit hooks, repository scanning, CI/CD checks. + +## Team training + +**AI-specific:** + +- Common patterns AI gets wrong +- How to spot hallucinated security +- When to be extra suspicious + +**General security:** + +- OWASP Top 10 +- Language-specific issues +- Secure coding guidelines + +## Incident response + +When AI-generated code causes a security issue: + +1. **Treat like any security incident**—don't minimize because "AI did it" +2. **Document AI involvement:** Tool, prompt, what review happened +3. **Root cause:** Was this AI-specific? Would human have caught it? +4. **Process improvement:** What would have caught this earlier? + +**Post-incident:** Update checklists, share learnings, consider tool-specific mitigations. + +## Resources + +### Videos + +- [Government Agents – Mark Myshatyn, Los Alamos](https://www.youtube.com/watch?v=example) - Security considerations for AI agents in government diff --git a/src/content/docs/ru/index.mdx b/src/content/docs/ru/index.mdx new file mode 100644 index 0000000..b22a752 --- /dev/null +++ b/src/content/docs/ru/index.mdx @@ -0,0 +1,124 @@ +--- +title: Агентная инженерия для людей +description: Практические руководства и ресурсы для изучения того, как работает инженерия программного обеспечения и руководство в пост-AI мире. +template: splash +hero: + tagline: Практические руководства и ресурсы для изучения того, как работает инженерия программного обеспечения и руководство в пост-AI мире. + image: + file: ../../../assets/human-ai.png + actions: + - text: Начать обучение + link: /ru/introduction/what-is-agentic-engineering/ + icon: right-arrow + - text: Присоединиться к сообществу + link: /ru/community/ + icon: discord + variant: minimal +--- + +import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +Автономные агенты создают целые приложения по единственному запросу, [вносят вклад в проекты с открытым исходным кодом](https://github.com/matplotlib/matplotlib/pull/31132), и даже [делают бронирование столика в ресторане](https://youtu.be/0iTb3a6eqKg) от имени людей. +Это замечательно для хобби-проектов и стартапов-первопроходцев, но для многих инженерных команд интеграция этих инструментов в реальную производственную среду кажется недостижимой. + +Если вы чувствуете, что отстаете, или обещания «агентной инженерии» кажутся нереалистичными для сложных, высокорисковых legacy-систем, этот ресурс для вас. +Agentic Engineering for Humans — это начало прагматичного, без преувеличений пути для управления этим переходом — сообщество-репозиторий, где реальные инженеры делятся тем, что работает на деле. + +[Выберите свой путь](/#choose-your-path) чтобы отнять время на скучных задачах и сосредоточиться на высокоценных проблемах, или [внесите свой вклад](/ru/community/contributing/) чтобы сделать этот документ живым описанием того, что происходит на самом деле. + + +## Выберите свой путь + +Выберите трек, соответствующий вашей роли. Каждый путь создан для того, где вы сейчас находитесь. + + + + Эффективные запросы, декомпозиция задач, проверка вывода агентов и создание AI-совместимых кодовых баз. + + [Начать здесь →](/ru/engineers/getting-started/) + + + Интеграция агентов в рабочие процессы, политики код-ревью, сдвиг тестирования влево и управление пробелами в навыках. + + [Начать здесь →](/ru/team-leads/adopting-agentic-tools/) + + + Стратегическое видение, фреймворки ROI, препятствия внедрению и подготовка к автономным агентам. + + [Начать здесь →](/ru/executives/strategic-vision/) + + + +--- + +## Что внутри + +### Основы + + + + + + + + +### Индивидуальная практика + + + + + + + +### Интеграция в команде + + + + + + + +### Стратегия + + + + + + + + +### По фазам + + + + + + + + +### Управление + + + + + + + +--- + +## Создано сообществом + +Это руководство — открытый источник и создано сообществом. Мы все вместе разбираемся с агентной инженерией — ваш опыт важен. + + + + Задавайте вопросы, делитесь успехами, обсуждайте то, что работает. Быстрейший способ учиться — вместе. + + [Присоединиться к Discord →](https://kilo.love/discord) + + + Нашли что улучшить? Есть экспертиза для деления? Каждый вклад помогает следующему человеку. + + [Как внести вклад →](/ru/community/contributing/) + + \ No newline at end of file diff --git a/src/content/docs/ru/introduction/how-agents-work.md b/src/content/docs/ru/introduction/how-agents-work.md new file mode 100644 index 0000000..f1503df --- /dev/null +++ b/src/content/docs/ru/introduction/how-agents-work.md @@ -0,0 +1,97 @@ +--- +title: How Agents Work +description: The technical foundations of AI agents - the ReAct loop, tool use, context windows, and common failure modes. +sidebar: + order: 2 +--- + +Understanding what's happening under the hood helps you work with agents more effectively. You don't need to be an ML engineer, but knowing the basics transforms how you collaborate with these systems. + +## The ReAct Loop + +Every AI agent follows the same core pattern: **Reason → Act → Observe**. This cycle, called ReAct (Reason + Act—not the frontend framework), is how agents turn your request into working code. + +Here's what happens with each iteration: + +1. **Observe**: Read the current state (code, errors, file system) +2. **Reason**: Decide what action will move toward the goal +3. **Act**: Execute that action (write code, run a command, ask for clarification) +4. **Evaluate**: Check if it worked, then repeat + +The quality of each step determines the quality of the output. When an agent seems stuck, it's usually failing at one specific step in this loop. + +## What LLMs Can and Can't Do + +The **Large Language Model (LLM)** is the "brain" of an agent—a neural network trained on massive amounts of text and code. Understanding its strengths and limitations helps you work with it, not against it. + +**What LLMs do well:** + +- Pattern recognition and code completion +- Following structured instructions +- Generating syntactically correct code +- Explaining concepts and reasoning through problems + +**What LLMs struggle with:** + +- No persistent memory between sessions: each conversation starts fresh +- No system access without tools: they can only generate text by default +- Probabilistic, not deterministic: the same input may produce different output +- Limited long-horizon planning: they work best with clear, bounded tasks + +## Closed vs Open Weight Models + +The models powering AI agents come in two flavors: **closed** and **open weight**. Each has tradeoffs that affect how you build and deploy agents. + +**Closed models** (Claude, GPT, Gemini, Grok, etc.) are accessed through APIs. You send requests to the provider's servers and pay per token. + +- **Pros:** State-of-the-art performance, no infrastructure to manage, continuous improvements +- **Cons:** Data leaves your network, usage costs scale with volume, dependent on provider availability + +**Open weight models** (Llama, Mistral, DeepSeek, Qwen) can be downloaded and run on your own hardware _or_ accessed through APIs. + +- **Pros:** Full data control, predictable costs at scale, customizable through fine-tuning +- **Cons:** Requires GPU infrastructure and you managing updates and security, with generally lower capability than frontier closed models + +**Choosing between them:** + +- **Start with closed models.** They're easier to integrate and currently more capable. Most teams should begin here. +- **Consider open weight when:** You have strict data residency requirements, predictable high-volume workloads where self-hosting is cheaper, or need to fine-tune for specialized domains. +- **Hybrid approaches work.** Use closed models for complex reasoning tasks and open weight for high-volume, simpler operations like code formatting or basic classification. + +The gap between closed and open weight models continues to narrow. What requires a closed model today may be achievable with open weight next year. Design your systems to swap models as the landscape evolves. + +## Tool Use + +Raw LLMs can only generate text. **Tools** are what transform them into agents that can actually do things in the world. + +Common tools include: + +- **File operations**: These read, write, and search code files +- **Terminal commands**: These run builds, tests, linters, and deployments +- **API calls**: These interact with external services and databases +- **Code execution**: These run and verify generated code + +Each tool extends what the agent can do. The quality of tool integration—how reliably tools work and how well the agent knows when to use them—matters as much as the underlying model. + +## Context Windows + +The **context window** is everything an agent can "see" at once: your instructions, the code, previous conversation, and tool results. It's measured in **tokens** (roughly 4 characters each). + +Larger windows let agents work with more code simultaneously. But there's a tradeoff: more context means slower responses and higher costs. + +When context fills up, older content gets **truncated**—the agent literally forgets it. Smart agents manage this by loading only what's relevant and summarizing when necessary. You can help by keeping tasks focused and providing only the context that matters. + +## Common Failure Modes + +Agents fail in predictable ways. Knowing these patterns helps you catch problems early: + +- **Hallucination**: Generating plausible but incorrect information, like APIs or functions that don't exist +- **Context drift**: Gradually losing track of the original goal as steps accumulate +- **Infinite loops**: Getting stuck repeating the same failed approach without trying something new +- **Overconfidence**: Asserting that code works without actually verifying it runs + +When you see these patterns, intervene. Reset the context, clarify the goal, or break the task into smaller pieces. The agent isn't being stubborn—it's hitting a limitation you can work around. + +--- + +**Did we miss a failure mode?** This guide is community-driven. [Share your experience](/community/contributing/) so others can learn from it. \ No newline at end of file diff --git a/src/content/docs/ru/introduction/patterns/openclaw.md b/src/content/docs/ru/introduction/patterns/openclaw.md new file mode 100644 index 0000000..6209a20 --- /dev/null +++ b/src/content/docs/ru/introduction/patterns/openclaw.md @@ -0,0 +1,166 @@ +--- +title: OpenClaw +description: An open-source AI agent runtime that connects to your existing tools and services +sidebar: + order: 9 +--- + +Most AI coding tools assume you're at a terminal, copying prompts and pasting responses. The agent exists in a browser tab, disconnected from everything else you use. You're the integration layer. + +OpenClaw takes a different approach: the agent lives in your infrastructure. It connects to your messaging apps, calendar, email, filesystem, and whatever else you wire up. Instead of context-switching to AI, the AI has context about you. + +## The core idea + +OpenClaw is an open-source runtime that gives AI agents persistent access to your tools. It runs locally or on a VPS you control. Your data stays yours. + +```bash +# Install +npm install -g openclaw + +# Setup (interactive) +openclaw onboard + +# Start the daemon +openclaw gateway start +``` + +Once running, you can reach your agent via Telegram, Discord, Signal, Slack, CLI, or web dashboard. One agent, multiple surfaces. + +**The philosophy:** AI should adapt to your workflow, not the other way around. Persistent context beats fresh starts. + +## How it works + +OpenClaw connects three things: + +``` +┌─────────────────────────────────────────────────────┐ +│ Channels (how you talk to it) │ +│ Telegram, Discord, Signal, Slack, CLI, Web │ +└─────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────┐ +│ Gateway (the runtime) │ +│ Routes messages, manages sessions, runs tools │ +└─────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────┐ +│ Tools & Skills │ +│ Shell, browser, files, MCP servers, custom skills │ +└─────────────────────────────────────────────────────┘ +``` + +The agent maintains context through workspace files: + +- `AGENTS.md` — How the agent should behave +- `SOUL.md` — Personality and tone +- `USER.md` — Context about who it's helping +- `MEMORY.md` — Long-term curated memory +- `memory/YYYY-MM-DD.md` — Daily session notes + +These files are injected into every conversation. The agent builds understanding over time, like a colleague who's been paying attention. + +## Key capabilities + +### Proactive behavior + +Unlike chat-only tools, OpenClaw can reach out to you: + +```markdown +# HEARTBEAT.md - checked every 30 minutes +- Check inbox for urgent emails +- Review calendar for upcoming meetings +- Monitor GitHub notifications +``` + +The agent polls on a schedule. When something needs attention, it messages you. No need to remember to ask. + +### Background tasks + +Spawn sub-agents for parallel work: + +``` +You: "Research competitors while I focus on the pitch deck" +Agent: [spawns research sub-agent, continues helping with deck] +Sub-agent: [works independently, reports back when done] +``` + +Long-running tasks don't block the conversation. + +### Tool integration + +Built-in tools cover common needs: + +- **Shell execution** — Run commands, scripts, builds +- **Browser automation** — Navigate, scrape, interact with web apps +- **File operations** — Read, write, edit, organize +- **Web search** — Research without leaving the conversation + +Extend with skills for specific workflows: + +```bash +# Install a skill +clawhub install trello + +# Now the agent can manage your boards +"Move the 'API redesign' card to Done" +``` + +### Multi-channel presence + +Same agent, multiple ways to reach it: + +- Quick question via Telegram while mobile +- Deep work session via CLI at your desk +- Team collaboration via Discord or Slack +- Dashboard for reviewing history + +Context carries across channels. The agent knows what you discussed on Telegram when you continue on CLI. + +## When to use it + +OpenClaw works well for: + +- **Personal AI assistant** — Inbox triage, calendar management, task tracking +- **Development workflows** — Code review, PR monitoring, CI/CD notifications +- **Research and writing** — Web research, drafting, editing with persistent context +- **Automation** — Scheduled tasks, monitoring, proactive alerts + +It's less suited for: + +- One-off coding questions (just use ChatGPT) +- Team-wide deployment (designed for personal/small team use) +- Environments where local installation isn't possible + +## Getting started + +```bash +# Install globally +npm install -g openclaw + +# Interactive setup - configures model, channels, workspace +openclaw onboard + +# Start the gateway daemon +openclaw gateway start + +# Check status +openclaw status +``` + +The onboarding wizard walks through: +1. Choosing an AI provider (OpenRouter, Anthropic, OpenAI, etc.) +2. Setting up channels (Telegram bot, Discord, etc.) +3. Configuring your workspace + +## Resources + +- [GitHub Repository](https://github.com/openclaw/openclaw) — Source code +- [Documentation](https://docs.openclaw.ai) — Full docs +- [ClawHub](https://clawhub.com) — Find and share skills +- [Discord Community](https://discord.com/invite/clawd) — Support and discussion + +--- + +*OpenClaw is open source and actively developed. The project welcomes contributions.* + +*Note: OpenClaw was originally called "ClawdBot", then "MoltBot", before landing on "OpenClaw".* diff --git a/src/content/docs/ru/introduction/patterns/outcome-engineering.md b/src/content/docs/ru/introduction/patterns/outcome-engineering.md new file mode 100644 index 0000000..71e9c85 --- /dev/null +++ b/src/content/docs/ru/introduction/patterns/outcome-engineering.md @@ -0,0 +1,192 @@ +--- +title: Outcome Engineering (o16g) +description: A manifesto for moving beyond code to outcomes in the age of AI agents +sidebar: + order: 8 +--- + +Software engineering has always been about outcomes, not code. Code is just the incantation that transforms computation into magic—the mechanism that delivers an idea. With AI agents removing the constraints of time and human bandwidth, we can finally treat code as what it is: a means to an end, not the end itself. + +**Outcome Engineering** (o16g) is a framework for reorienting development around delivered impact rather than lines written. It's a set of principles for making agentic development vastly more capable, faster, and trustworthy than either vibe coding or hand-coding alone. + +## The core insight + +> "It was never about the code." + +The traditional backlog exists because human bandwidth was the limiting factor. You rejected ideas for lack of time, not lack of value. With agents, creation is limited only by the cost of compute, not capacity. + +This changes everything: + +- **Creation, not code** — Focus on what you're building, not how you're typing it. +- **Cost, not time** — Manage to budget, not capacity. If the outcome is worth the tokens, it gets built. +- **Capacity, not backlog** — Never reject an idea for lack of time, only for lack of budget. +- **Certainty, not vibes** — The only truth is the rate of positive change delivered to the customer. + +## The 16 principles + +O16g starts with 16 principles that guide agentic development. + +### Human Intent + +> Agents explore paths; humans choose the destination. + +Do not abdicate vision to the machine. Create with mission, goals, and authorial intent. You decide where you're going; agents get you there. + +### Verified Reality is the Only Truth + +> Code is a vanity metric; vibes are not tests. + +The only truth is the rate of positive change delivered to the customer. Grade agents not on the lines they write, but on the binary reality they verify. If you cannot predict, measure, and prove it worked, you failed. + +### No More Single Player Mode + +> Chat is a bottleneck, not an API. + +Whether humans or agents, outcome engineering is a team sport. Define the protocol for debate, decision, and delivery. Ambiguity in coordination is a system failure. Surface all the debates formerly hidden by the backlog. + +### The Backlog is Dead + +> The backlog is a relic of human limitation. + +Never reject an idea for lack of time, only for lack of budget. If the outcome is worth the tokens, it gets built. + +### Unleash the Builders + +> We are architects of reality, not typewriters. + +Write code only when it brings joy. Delegate the toil. Never let implementation details, integration, or time block exploration and creation. + +### No Wandering in the Dark + +> Never dispatch an agent without context. + +Map the territory before building. If you don't know where you stand, you cannot calculate the path to the destination. + +### Build It All + +> In an agentic world, code is the cheapest resource. + +Build to answer questions. Build to test hypotheses. Build to inform debates openly. Build the things you used to buy so you can prove they work perfectly for you. Take every opportunity to get better at knowing you can deliver the outcomes you want. + +### Failures are Artifacts + +> Opinions are conjecture; outcomes are data. + +When an outcome fails, do not simply rollback. Dissect the failure. Understand why the hypothesis was wrong. Debug the decision, not just the code. + +### Agentic Coordination is a New Org + +> Scaling agents mirrors scaling people, but faster, weirder, and harder. + +Design the organization chart and employee handbook for the swarm. Engineer against the infinite spins of indecision and the echo chambers of model groupthink. Build the structures that keep a massive, tireless workforce aligned, decisive, and sane. + +### Code the Constitution + +> Don't fall victim to decision fatigue. + +Don't paper over poor architecture with checkpoints. Encode laws into the environment. Codify mission, vision, and goals. If the agent cannot parse the intent, it cannot provably deliver the outcome. Ambiguity is the enemy of alignment. + +### All the Context, Everywhere + +> Agents cannot reason in a vacuum. + +Embed context into the infrastructure, not just the prompt. Build the knowledge graph so the agent understands the world before it attempts to change it. + +### Priorities Drive Compute + +> No matter how scalable, compute is still a cost. + +Always know the next most important task, what would most benefit from compute and attention. Do the hard work to align. Optimize for outcomes. Everything you learn informs your priorities. + +### Show Your Work + +> Code is the what; reasoning is the why. + +Do not accept a black box. Agents must record their discoveries, their rejected paths, and their logic. Pay the compute cost to understand the machine. + +### Continuous Improvement + +> Repeating a mistake is a system failure. + +Spend compute on the post-mortem. Automate the analysis of what went wrong. Inoculate the system so the error never happens again. + +### Risk Stops the Line + +> Speed is dangerous without brakes. + +Make risk a blocking function. If the risk is unknown or unmitigated, the line stops. Do not hide danger in a report; encode it as a gate. + +### Audit the Outcomes + +> Trust is a vulnerability. + +Models drift. Prompts break. Capabilities change overnight. Continuously audit the agent against the domain. Verify the tool is sharp before you use it. + +## Applying o16g in practice + +### Managing to cost, not capacity + +The traditional question: "Do we have bandwidth for this feature?" + +The o16g question: "Is this feature worth the compute cost?" + +This reframing has practical implications: + +- **Exploration becomes cheap** — Spin up variants to test hypotheses rather than debating in meetings. +- **Technical debt becomes a budget line** — Instead of accumulating debt because "we don't have time," you decide whether paying it down is worth the tokens. +- **Prioritization becomes economics** — Stack rank by expected value per token, not by available engineer-hours. + +### Encoding intent as infrastructure + +O16g emphasizes codifying intent where agents can actually use it: + +- **Constitutions** — Non-negotiable principles encoded as guardrails (similar to [Spec-Driven Development's](/introduction/patterns/spec-driven-development/) constitution phase). +- **Knowledge graphs** — Context embedded in infrastructure, not scattered across prompts. +- **Verification gates** — Risk encoded as blocking functions, not post-hoc reports. + +### Treating failures as data + +When an agent fails, o16g prescribes: + +1. Don't just rollback — dissect the failure. +2. Debug the decision, not just the code. +3. Automate the post-mortem analysis. +4. Inoculate the system against repeat failures. + +This mirrors the [RPI pattern's](/introduction/patterns/rpi/) emphasis on research before implementation, but extends it to continuous learning from production outcomes. + +## Relationship to other patterns + +O16g is a philosophical framework that complements tactical patterns: + +| Pattern | Focus | O16g connection | +|---------|-------|-----------------| +| [Spec-Driven Development](/introduction/patterns/spec-driven-development/) | Capturing intent before code | "Code the Constitution" — encode laws into the environment | +| [RPI](/introduction/patterns/rpi/) | Research → Plan → Implement | "No Wandering in the Dark" — map territory before building | +| [Ralph Wiggum](/introduction/patterns/ralph-wiggum/) | Autonomous iteration loops | "Build It All" — let agents iterate until outcomes are verified | + +While these patterns provide the *how*, o16g provides the *why*: measuring success by outcomes delivered, not code written. + +## Who this is for + +O16g emerged from practitioners building real systems with agents. The author, Cory Ondrejka, was CTO of Onebrief, co-creator of Second Life, an engineering leader at Google, and is credited with [saving Meta](https://www.businessinsider.com/meet-the-engineer-who-saved-facebook-2013-1) during a critical period. + +The framework is particularly relevant for: + +- **Teams scaling agentic workflows** — The "Agentic Coordination is a New Org" principle addresses the organizational challenges of agent swarms. +- **Leaders setting strategy** — Cost-based prioritization changes how you think about roadmaps. +- **Engineers questioning fundamentals** — If you sense that vibe coding isn't enough but aren't sure what comes next. + +## Resources + +### Official + +- READ: [The o16g Manifesto](https://o16g.com/) — The complete manifesto with all 16 principles + +### Author + +- Cory Ondrejka — CTO of Onebrief, co-creator of Second Life, former engineering leader at Google and Meta + +--- + +**Practicing outcome engineering?** [Share your experience](/community/contributing/)—how measuring outcomes instead of output has changed your team's approach. diff --git a/src/content/docs/ru/introduction/patterns/ralph-wiggum.md b/src/content/docs/ru/introduction/patterns/ralph-wiggum.md new file mode 100644 index 0000000..67e3be8 --- /dev/null +++ b/src/content/docs/ru/introduction/patterns/ralph-wiggum.md @@ -0,0 +1,219 @@ +--- +title: Ralph Wiggum +description: A technique for running AI agents in continuous loops until the job is actually done +sidebar: + order: 6 +--- + +You've probably been here: you ask an AI agent to implement a feature, it writes some code, declares victory, and... the tests fail. You prompt again. It tries a different approach. Still broken. Three iterations later, you're doing it yourself. + +Ralph Wiggum flips this dynamic. Instead of hoping for first-try perfection, you design for iteration. The agent keeps running until the work is actually complete—tests pass, types check, linting clears. No premature exits. No false victories. + +## The core idea + +At its simplest, Ralph is a bash loop: + +```bash +while :; do cat PROMPT.md | claude ; done +``` + +That's it. Feed the agent the same task repeatedly. Each iteration builds on the last through git history and progress tracking. The agent doesn't need to be perfect—it just needs to be persistent. + +**The philosophy:** Iteration beats perfection. Deterministic failures are data. Keep trying until success. + +## How it works + +Ralph wraps the standard AI tool loop with an outer verification layer: + +``` +┌──────────────────────────────────────────────────────┐ +│ Ralph Loop (outer) │ +│ ┌────────────────────────────────────────────────┐ │ +│ │ AI SDK Tool Loop (inner) │ │ +│ │ LLM ↔ tools ↔ LLM ↔ tools ... until done │ │ +│ └────────────────────────────────────────────────┘ │ +│ ↓ │ +│ verifyCompletion: "Is the TASK actually complete?" │ +│ ↓ │ +│ No? → Inject feedback → Run another iteration │ +│ Yes? → Return final result │ +└──────────────────────────────────────────────────────┘ +``` + +The key mechanisms: + +- **Stop hook**: This intercepts exit attempts and checks completion criteria before allowing the agent to stop. +- **Progress tracking**: A `progress.txt` file tracks what's been done, decisions made, and blockers encountered. +- **Git commits**: Each iteration commits work, creating context for future iterations. +- **Feedback loops**: Types, tests, and linting verify quality before continuing. +- **Verification**: Custom completion criteria determine when the task is truly done. + +## Two operating modes + +### HITL (Human-In-The-Loop) + +Run one iteration at a time. Watch the agent work. Intervene when needed. + +This is pair programming with AI. You see every decision, catch mistakes early, and guide the direction. + +Best for: + +- Learning the technique +- Refining prompts +- Working on risky tasks where you want eyes on every change + +### AFK (Away From Keyboard) + +Set a maximum iteration count and let it run. Come back to results. + +This is overnight work. You define clear success criteria, cap the iterations, and let the agent grind through mechanical tasks while you sleep. + +Best for well-defined work like: + +- Test migrations +- Coverage improvements +- Large refactors with clear patterns + +**Critical for AFK mode:** Use Docker sandboxes. You're giving an agent autonomous access to your system. Contain it. + +```bash +docker sandbox run claude +``` + +## When Ralph works + +Ralph excels at tasks with clear completion criteria: + +| Task type | Why it works | +| ------------------------ | -------------------------------------------------------- | +| **Large refactors** | Converting class components to hooks, Jest to Vitest | +| **Framework migrations** | Test suite conversions with clear before/after states | +| **TDD workflows** | Implement features until tests pass | +| **Test coverage** | Add tests to uncovered code until coverage threshold met | +| **Greenfield builds** | REST APIs, complete features with defined specs | +| **Mechanical cleanup** | Linting fixes, duplicate removal, code smell elimination | + +## When Ralph doesn't work + +Some tasks resist iteration: + +- **Ambiguous requirements**: If you can't define "done," the loop can't verify completion. +- **Architectural decisions**: These need human judgment, not persistence. +- **Security-sensitive code**: Auth, payments, and crypto require human review regardless of test results. +- **Exploration tasks**: "Figure out why the app is slow" has no clear stopping point. +- **One-shot operations**: If you need immediate results, the loop overhead isn't worth it. + +## Practical tips + +### Define clear scope + +Use structured completion criteria: + +```json +{ + "category": "functional", + "description": "New chat button creates conversation", + "steps": ["Click button", "Verify conversation", "Check welcome state"], + "passes": false +} +``` + +The agent knows exactly what "done" means. + +### Track progress + +Maintain a `progress.txt` with: + +- Tasks completed +- Decisions made and why +- Blockers encountered +- Files changed + +This gives future iterations context about past work. + +### Use feedback loops + +Block commits unless ALL feedback loops pass: + +- TypeScript type checking +- Unit tests +- E2E tests (Playwright, Cypress) +- Linting +- Pre-commit hooks + +If any check fails, the iteration isn't complete. + +### Take small steps + +Keep it to one logical change per commit. Break large tasks into subtasks, and run feedback loops after each change. You want quality over speed. + +### Cap iterations + +- **HITL:** Watch every iteration +- **AFK:** Set max-iterations (10-20 for small tasks, 30-50 for large) +- **Never use unlimited iterations** + +A 50-iteration loop on a large codebase can cost $50-100+ in API credits. Start with 10-20 iterations to understand token consumption before scaling up. + +### Commit after each feature + +Good git hygiene creates a clean git history and clear rollback points. If iteration 15 breaks something, you can revert to iteration 14. + +## Getting started + +### Claude Code Plugin + +```bash +/plugin install ralph-loop@claude-plugins-official +/ralph-loop "Add JSDoc comments to all exported functions" --max-iterations 10 +``` + +### NPM Package + +```bash +npm install ralph-loop-agent ai zod +``` + +```javascript +const agent = new RalphLoopAgent({ + model: "anthropic/claude-opus-4.5", + instructions: "You are a helpful coding assistant.", + stopWhen: iterationCountIs(10), + verifyCompletion: async ({ result }) => ({ + complete: result.text.includes("DONE"), + reason: "Task completed successfully", + }), +}); +``` + +## The skill shift + +Traditional AI coding asks: "How do I get the perfect prompt?" + +Ralph asks: "How do I design conditions where iteration leads to success?" + +You stop directing the AI step-by-step and start designing loops that converge on solutions. The agent's job is persistence. Your job is defining what "done" looks like and ensuring the feedback loops catch failures. + +This is continuous autonomy—the agent works until the job is actually done, not just until the LLM stops calling tools. + +## Resources + +### Official + +- [Ralph Wiggum as a Software Engineer](https://ghuntley.com/ralph/) +- [GitHub - vercel-labs/ralph-loop-agent](https://github.com/vercel-labs/ralph-loop-agent) — Core NPM package +- [Ralph Wiggum - AI Loop Technique for Claude Code](https://awesomeclaude.ai/ralph-wiggum) — Complete guide and examples + +### Tutorials + +- [11 Tips For AI Coding With Ralph Wiggum](https://www.aihero.dev/tips-for-ai-coding-with-ralph-wiggum) — Practical tips for autonomous loops +- [The Ralph Wiggum Approach: Running AI Coding Agents for Hours](https://dev.to/sivarampg/the-ralph-wiggum-approach-running-ai-coding-agents-for-hours-not-minutes-57c1) — DEV Community tutorial + +### Community tools + +- **ralph-claude-code** — Rate limiting, tmux dashboards, circuit breakers +- **ralph-orchestrator** — Token tracking, spending limits, checkpointing + +--- + +**Using Ralph in production?** [Share your experience](/community/contributing/)—what worked, what didn't, and what you learned along the way. diff --git a/src/content/docs/ru/introduction/patterns/rpi.md b/src/content/docs/ru/introduction/patterns/rpi.md new file mode 100644 index 0000000..f85785f --- /dev/null +++ b/src/content/docs/ru/introduction/patterns/rpi.md @@ -0,0 +1,467 @@ +--- +title: Research, Plan, Implement (RPI) +description: A three-phase framework for transforming chaotic AI interactions into predictable, high-quality software delivery +sidebar: + order: 8 +--- + +You've been there. You ask an AI to "refactor this authentication module" and it generates 500 lines of code using libraries you don't have, invents methods that don't exist, and solves a problem you didn't actually have. Three hours later, you're untangling hallucinations and wondering if you should have just done it yourself. + +The AI isn't broken. You're asking it to read your mind without giving it structure. + +RPI (Research → Plan → Implement) fixes this. Instead of jumping straight to code generation, you break work into three focused phases with built-in validation. The AI researches what exists, plans the change systematically, then executes mechanically. It's slower than "just do it"—and that's the point. + +## The problem with direct prompting + +When you ask an AI agent to implement something without structure, you're gambling on several things going right simultaneously: + +- The AI correctly understands your intent +- It discovers all relevant code and patterns +- It makes architectural decisions you'd agree with +- It doesn't hallucinate APIs or libraries +- It stays within scope + +**What actually happens:** + +- Context overflow: With too much information, AI loses focus. +- Hallucination: AI invents code that doesn't exist. +- Wrong problem solved: AI misunderstands your requirements. +- Scope creep: Work expands beyond intended boundaries. +- Untestable code: You have no clear success criteria. + +The insight: without structure, even brilliant AI assistants become expensive random code generators. + +## What RPI actually is + +RPI is a three-phase framework with validation gates between each phase. Think of it as turning your AI from an eager intern into a seasoned developer with a GPS. + +**The phases:** + +1. **Research**: Build context. Document what exists today—no opinions, no suggestions. +2. **Plan**: Design the change. Use a phased approach with atomic tasks and success criteria. +3. **Implement**. Execute mechanically. Follow the plan, and verify after each phase. + +**Core principles:** + +- One goal per session: Keep the LLM laser-focused. +- Validation before progression: Use scoring scales to verify readiness. +- Human judgment preserved: AI doesn't make big decisions without validation. +- Context management: Start with a fresh session for each phase. + +The framework trades speed for clarity, predictability, and correctness. You'll spend more time upfront, but you'll spend far less time debugging hallucinations and fixing architectural mistakes. + +## Phase 1: Research + +The research phase builds context and insight. You're documenting what exists today—nothing more. + +**Strict rules:** + +- Document what exists +- Do NOT suggest changes +- Do NOT critique +- Do NOT plan +- Base everything on facts, not assumptions + +**In goose:** + +```bash +/research "look through the codebase and research how +the LLM Tool Discovery is implemented" +``` + +This spawns three parallel sub-agents: + +| Sub-agent | Purpose | +| --------------- | ------------------------------------------------- | +| `find_files` | Uses codebase locator to find relevant files | +| `analyze_code` | Reads files fully and documents how they work | +| `find_patterns` | Looks for similar features or conventions in repo | + +**Output:** A structured research document at `thoughts/research/YYYY-MM-DD-HHmm-topic.md` + +The document includes git metadata, file and line references, flow descriptions, key components, open questions, and a technical map of the feature as it exists today. + +### Reverse prompting + +Here's where things get interesting. Instead of you explaining everything upfront, the AI asks _you_ clarifying questions one at a time: + +- "Should this work from the file manager or dashboard?" +- "Any file type restrictions?" +- "What happens to shared files?" + +This reveals insights you hadn't considered, and prevents wrong assumptions from propagating through the entire workflow. + +### Validating research: the FAR scale + +Before moving to planning, validate your research against FAR criteria: + +| Criterion | Description | What it prevents | +| -------------- | ------------------------------------- | -------------------- | +| **F**actual | Based on actual code, not assumptions | Hallucination | +| **A**ctionable | You know exactly what to build | Vague requirements | +| **R**elevant | Solves the real user need | Wrong problem solved | + +**Critical:** A human must review the research document before proceeding. This informs everything downstream. + +## Phase 2: Plan + +The planning phase translates research into a phased implementation plan. You're designing the change with clear success criteria. + +**In goose:** + +```bash +/plan a removal of the Tool Selection Strategy feature +``` + +**AI's Process:** + +1. Read the research document from the previous phase +2. Ask clarifying questions (full removal vs deprecation? config cleanup behavior?) +3. Present design options where multiple approaches exist +4. Produce a phased implementation plan + +**Output:** A detailed plan at `thoughts/plans/YYYY-MM-DD-HHmm-description.md` + +The plan includes: + +- Explicit phases (e.g., 10 phases) +- Exact file paths +- Code snippets showing what to change +- Automated success criteria +- Manual verification steps +- Checkboxes for tracking progress +- Atomic tasks per phase + +### Why atomic tasks matter + +Each task should be a single, focused unit of work—one command call or file edit. This keeps the AI on track with simple instructions, makes progress easy to verify, prevents context overflow, and allows recovery if the context window fills. + +The plan must be explicit enough that someone else (or a fresh AI session) could execute it without additional context. + +### Validating plans: the FACTS scale + +Validate each task against FACTS criteria: + +| Criterion | Description | What it prevents | +| ------------ | ---------------------------------------------- | ----------------------------- | +| **F**easible | Can actually be done with available tools/APIs | Impossible tasks | +| **A**tomic | Single, focused unit of work | Context overflow, scope creep | +| **C**lear | Unambiguous instructions | Misinterpretation | +| **T**estable | Has clear success criteria | Untestable code | +| **S**coped | Properly bounded | Runaway execution | + +## Phase 3: Implement + +The implementation phase executes the plan step-by-step with verification. This should feel intentionally boring and mechanical. If it feels creative, something upstream is missing. + +**In goose:** + +```bash +/implement thoughts/plans/2025-12-23-remove-tool-selection-strategy.md +``` + +**AI's Process:** + +1. Read the plan completely +2. Execute phases in order +3. Run verification after each phase +4. Update checkboxes directly in the plan file as you go + +### Feedback loop options + +Choose your control level based on confidence in the plan: + +| Loop type | When to use | Control level | +| ------------------------- | ------------------------- | --------------------------------------- | +| Task-by-task validation | Maximum control needed | High—validate after each atomic task | +| Phase-by-phase validation | Balance speed and control | Medium—validate after completing phase | +| Full plan validation | High confidence in plan | Low—execute everything, validate at the end | + +### Verification gates + +Every phase must pass quality gates: + +- Tests must pass +- Builds must succeed +- Linters must pass +- No regressions introduced + +If any gate fails, the implementation pauses. Fix the issue before proceeding. + +### Recovery mechanism + +If the context window fills mid-implementation, the checkboxes in the plan allow the AI to compact and pick up exactly where it left off. This is why atomic tasks and progress tracking matter—they enable graceful recovery. + +## Optional: Iterate + +Sometimes plans need adjustment after review or during implementation. + +**In goose:** + +```bash +/iterate "plan path" + feedback +``` + +**AI's Process:** + +1. Read the existing plan +2. Research only what needs rethinking +3. Propose targeted updates +4. Edit the plan surgically (doesn't start over) + +This enables refinement without discarding good work. Changed sections must pass FACTS validation again. + +## File structure + +All RPI outputs live in predictable locations: + +``` +thoughts/ +├── research/ +│ └── YYYY-MM-DD-HHmm-topic.md +└── plans/ + └── YYYY-MM-DD-HHmm-description.md +``` + +## A Real-world example + +Let's walk through an actual RPI execution: removing the "Tool Selection Strategy" feature from a large codebase. + +**Complexity:** + +- Spans 32 files +- Touches Rust core code +- Affects TypeScript +- Changes configuration +- Modifies tests +- Updates documentation + +### Research phase (9 minutes) + +Started with `/research "LLM Tool Discovery"`. Realized scope was too broad—course corrected and reran: `/research "Tool Selection Strategy feature specifically"`. + +Output: detailed technical map of the feature. + +Human review: validated research accuracy before proceeding. + +### Plan phase (4 minutes) + +Ran `/plan a removal of the Tool Selection Strategy feature`. + +AI asked clarifying questions: + +- Full removal vs deprecation? +- How should config cleanup behave? +- Should artifacts be regenerated? +- Where do related tests live? + +Presented design options. Generated 10-phase plan with atomic tasks. + +Human review: validated plan feasibility. + +### Implement phase (39 minutes) + +Ran `/implement thoughts/plans/2025-12-23-remove-tool-selection-strategy.md`. + +AI executed mechanically phase by phase. Context window filled mid-way—AI compacted and resumed from checkboxes. + +Human activity during this phase: "I fell asleep." Intentionally boring and reliable. + +### Results + +- **Total time:** 52 minutes (including AI work, testing, human Q&A) +- **PR submitted:** Build passed on first try +- **Code review agent:** Zero comments +- **Quality:** Top-notch + +**Comparison:** + +| Approach | Outcome | +| -------------- | -------------------------------------------------------------- | +| Without AI | Several hours of manual work | +| AI without RPI | Drift, bugs, rework cycles | +| RPI | Slower than direct implementation, but predictable and correct | + +## When to use RPI + +### Ideal scenarios + +**Complex tasks spanning multiple files:** + +- Refactors +- Migrations +- Feature additions +- Large upgrades +- Incident cleanup +- Documentation overhauls + +**Characteristics that signal RPI is worth it:** + +- Complex integration +- Multiple touchpoints +- High consequences of errors +- Need for systematic approach +- Require clear validation + +### When to skip it + +**Simple, basic tasks:** + +- Single file changes +- Obvious bug fixes +- Simple feature additions +- Quick prototypes + +RPI is deliberately slower. The validation overhead isn't worth it for trivial work. + +## Why RPI works + +### Prevents common AI failures + +| Failure mode | How RPI prevents it | +| -------------------- | ----------------------------------------------------- | +| Context overflow | Atomic tasks keep work focused and bounded | +| Hallucination | FAR validation requires factual evidence | +| Wrong problem solved | Research validates relevance before planning | +| Untestable code | FACTS validation ensures clear success criteria | +| Scope creep | Atomic tasks and validation gates maintain boundaries | + +### Leverages AI strengths + +- **Pattern matching:** AI excels at finding similar code +- **Code generation:** AI writes boilerplate efficiently +- **Systematic execution:** AI follows checklists perfectly + +### Preserves human judgment + +- Humans handle strategy and validation +- Humans make architectural decisions +- Humans verify relevance and correctness +- AI doesn't make big decisions without validation + +### Built-in quality gates + +Every phase has checkpoints: + +- Research: FAR validation +- Plan: FACTS validation +- Implement: Tests, builds, lints must pass + +### Context management + +- Fresh sessions per phase—LLM stays focused +- Explicit handoffs—plan has all context for implementation +- Checkpoint system—can resume after interruptions + +## Integration with AI tools + +### Tool agnostic + +RPI works with any AI coding assistant: + +- Claude +- GitHub Copilot +- Cursor +- OpenAI +- Gemini +- Any agent that can follow structured prompts + +The framework is about structure, not specific tooling. + +### goose implementation + +Block's goose tool provides built-in RPI support with slash commands: + +| Command | Purpose | +| --------------------------------- | -------------------- | +| `/research "topic"` | Research phase | +| `/plan "feature/task"` | Planning phase | +| `/implement "plan path"` | Implementation phase | +| `/iterate "plan path" + feedback` | Plan refinement | + +**Recipes used:** + +- `rpi-codebase-locator` — Find relevant files +- `rpi-codebase-analyzer` — Analyze code +- `rpi-pattern-finder` — Find patterns +- `rpi-create-plan` — Generate plan +- `rpi-implement-plan` — Execute implementation +- `rpi-iterate-plan` — Refine plan + +### Without goose + +You can implement RPI manually: + +1. Create `thoughts/research/` and `thoughts/plans/` directories +2. Use structured prompts for each phase +3. Manually validate with FAR and FACTS scales +4. Track progress with checkboxes in markdown + +The tooling helps, but the framework works without it. + +## Common patterns + +### Feature addition + +```bash +1. /research "current authentication system" +2. /plan "add OAuth2 support" +3. /implement [plan path] +``` + +### Bug fix + +```bash +1. /research "payment processing error handling" +2. /plan "fix race condition in transaction commits" +3. /implement [plan path] +``` + +### Refactor + +```bash +1. /research "current data access layer" +2. /plan "migrate from ORM to raw SQL" +3. /implement [plan path] +4. /iterate [plan path] "need to handle edge case in migrations" +``` + +### Migration + +```bash +1. /research "React class components in codebase" +2. /plan "convert to functional components with hooks" +3. /implement [plan path] +``` + +## The skill shift + +Traditional AI coding asks: "How do I get the perfect prompt?" + +RPI asks: "How do I structure work so AI can execute reliably?" + +You stop directing the AI step-by-step and start designing workflows that converge on correct solutions. The AI's job is systematic execution. Your job is defining what "done" looks like and validating at checkpoints. + +**The mindset shift:** + +- **From:** "AI, build this feature" +- **To:** "AI, help me understand what exists, plan the change systematically, then execute with validation" + +## Resources + +### Official + +- READ: [Research → Plan → Implement Pattern | goose](https://block.github.io/goose/docs/tutorials/rpi/) — Official tutorial with demonstrations +- READ: [Introducing the RPI Strategy](https://patrickarobinson.com/blog/introducing-rpi-strategy/) — Creator's blog post explaining the approach + +### Community + +- LISTEN: [The RPI workflow - Build Wiz AI Show (Podcast)](https://open.spotify.com/episode/1OdIYj0SZzhyzFGGoVuELP) — Audio discussion on advanced AI coding + +### Origins + +Originally inspired by a YouTube video that sparked the idea for systematic AI development. Developed and popularized by HumanLayer (framework creators), Block's goose team (implementation and tooling), and Patrick Robinson (documentation and evangelism). + +--- + +**Using RPI in production?** [Share your experience](/community/contributing/)—what worked, what didn't, and what you learned along the way. diff --git a/src/content/docs/ru/introduction/patterns/spec-driven-development.md b/src/content/docs/ru/introduction/patterns/spec-driven-development.md new file mode 100644 index 0000000..f475488 --- /dev/null +++ b/src/content/docs/ru/introduction/patterns/spec-driven-development.md @@ -0,0 +1,381 @@ +--- +title: Spec-Driven Development +description: Using specifications as executable contracts that drive AI agent implementation +sidebar: + order: 7 +--- + +You've watched it happen: you ask an AI agent to "add photo sharing to the app" and it builds something. The code compiles. Tests pass. But the architecture doesn't match what you'd choose. The data model makes assumptions you'd never make. And now you're three days into a feature that needs a rewrite. + +This is the vibe coding trap. The agent isn't broken—it's doing exactly what you asked. The problem is you asked for code when you should have asked for clarity first. + +Spec-Driven Development (SDD) flips the script. Instead of jumping straight to implementation, you define what you want in a specification that becomes the source of truth. The spec isn't documentation written after the fact—it's an executable contract that determines what gets built. + +## The problem with code-first + +When you prompt an AI agent without clear specifications, you're asking it to read your mind. And language models are exceptional at pattern completion, not mind reading. + +**What happens with vague prompts:** + +- The agent makes reasonable assumptions—some will be wrong. +- Requirements emerge incrementally, locking you into early decisions. +- The codebase becomes the de-facto specification. +- Crucial decisions get trapped in Slack threads or people's heads. +- Major rewrites require enormous effort because code is inherently binding. + +You discover issues deep into implementation when they're expensive to fix. The agent built what you said, not what you meant. + +## What SDD actually is + +Let's be clear about what SDD isn't: + +- **Not waterfall planning**: You're not writing exhaustive documentation before touching code. +- **Not bureaucracy**: This shouldn't slow you down; it should prevent expensive rework. +- **Not predicting the future**: You're capturing current understanding, which evolves. + +SDD is making technical decisions explicit, reviewable, and evolvable. It's version control for your thinking. + +**The core insight:** Specifications become living documents that evolve alongside code. They're active tools that help you think through edge cases, coordinate across teams, and enable multi-variant implementations. + +When your spec turns into working code automatically, intent becomes the source of truth—not the code itself. + +## The SDD workflow + +SDD breaks development into distinct phases. Each phase has a specific purpose and produces artifacts that feed the next phase. + +### Phase 0: Constitution (optional but recommended) + +Before any iteration begins, establish the rules of the game. What are your non-negotiable principles? + +**What goes in a constitution:** + +- Testing approaches and standards +- Security policies and compliance rules +- Design system constraints +- Tech stack conventions (CLI-first, API-first, etc.) +- Engineering practices +- Integration requirements + +This becomes the guardrails that guide all development. The agent knows what's off-limits before it writes a single line of code. + +### Phase 1: Specify + +Define the "what" and "why": the problem, users, scope, and success criteria. + +**Focus on:** + +- Problem statement +- User personas and cohorts +- Key user flows and experiences +- Success metrics +- Constraints (performance, privacy, security) +- What's explicitly out of scope + +**Avoid:** Technical implementation details, stack choices, architecture (that comes later). + +**Example specification prompt:** + +``` +Build a trip planner that generates day-by-day itineraries for multi-city trips. + +Problem: help travelers plan multi-city trips with realistic timing, budget guidance +Users: casual travelers, travel bloggers, small tour operators +Key flows: create trips, add cities, auto-generate itinerary, adjust by preferences +Non-functional: P95 itinerary generation under 4 seconds for 7-day trips +Out of scope: airline booking, hotel payments +``` + +The output is a structured `SPEC.md` that captures requirements. The agent may flag `[NEEDS CLARIFICATION]` sections—resolve these before proceeding. + +### Phase 2: Plan + +Translate the product spec into technical implementation. Now you're defining the "how". + +**Focus on:** + +- Tech stack selection +- Architecture and design patterns +- Integration boundaries +- Data contracts and schemas +- Performance targets +- Security approach +- Identified risks + +**Example planning prompt:** + +``` +Stack: FastAPI + Postgres + Redis; Next.js front end; mobile via Expo. +Architecture: API-first, backend service + vector store for place of interest (POI) embeddings. +AI: routing agent for POIs, scheduler for packing days, critic for validation. +Performance: target end-to-end plan in under 4 seconds at P95. +Security: redact PII in logs, encrypt at rest. +``` + +The output is a `PLAN.md` with technical architecture. A key benefit: you can generate multiple plan variations to compare different approaches before committing. + +### Phase 3: Tasks + +Break the spec and plan into manageable, testable, ordered work items. + +**Each task includes:** + +- Clear description +- Acceptance criteria +- Dependencies +- Links to spec sections +- Test requirements + +**Example task breakdown:** + +- API contract for itinerary generation with schemas +- Agent prompts and guardrails +- Data loaders for POI metadata +- Caching and rate-limit handling +- Frontend flows: create trip, edit preferences, view itinerary +- Observability: timing spans, cost tracking, error taxonomies + +By default, test-related items are included and ordered before implementation—TDD structure baked in. + +### Phase 4: Implement + +Execute tasks in small slices while staying within constraints. + +**Key practice:** Keep agents pointing back to `SPEC.md` and `PLAN.md` for every change. Work from the spec, plan, or task file rather than ad-hoc prompts. Execute in small, reviewable chunks. + +**Example implementation slice:** + +- Implement POST /itinerary with schema validation +- Add scheduler agent prompt respecting constraints +- Cache lookups and transit matrices +- Verify against acceptance criteria + +Each chunk should solve a specific piece of the puzzle. + +### Phase 5: Testing + +Testing isn't a separate phase—it's integrated throughout. Tests attach directly to requirements for traceability. + +**Types of tests:** + +- **Contract tests:** API request/response validation +- **Property tests:** Constraint verification (e.g., no day exceeds 10km walking) +- **Performance tests:** P95 latency under target +- **Security tests:** PII redaction, encryption verification + +The trace from "what was promised" to "what was delivered" becomes auditable. + +### Phase 6: Maintain + +Requirements change. SDD handles this gracefully: + +1. Update spec first +2. Regenerate plan +3. Update tasks +4. Let agents refactor within boundaries +5. Extend tests for new rules +6. Keep changelog of spec revisions + +**Example change request:** + +``` +Add "family mode" that favors kid-friendly POIs and shorter walking segments. + +Process: +- Update SPEC.md constraints +- Re-run planning +- Regenerate affected tasks +- Adjust prompts +- Extend tests for new rules +- Document why trade-offs were made +``` + +Human review is essential before accepting regenerated plans. + +## GitHub Spec Kit + +GitHub's [Spec Kit](https://github.com/github/spec-kit) is an open-source toolkit that operationalizes SDD across multiple AI coding agents. + +### What it provides + +- **Specify CLI:** Python-based tool that bootstraps projects for SDD +- **Templates:** Structured formats for specs, plans, tasks, and constitution +- **Slash commands:** AI agent prompts for structured development workflow +- **Helper scripts:** Automation for maintaining SDD scaffolding + +### Installation + +```bash +# Persistent installation (recommended) +uv tool install specify-cli --from git+https://github.com/github/spec-kit.git + +# Initialize project +specify init + +# Or in current directory +specify init . --ai claude +``` + +### Supported agents + +Spec Kit works with most modern AI coding agents: + +| Agent | Support | +| -------------- | ------- | +| Claude Code | ✅ | +| GitHub Copilot | ✅ | +| Cursor | ✅ | +| Gemini CLI | ✅ | +| Windsurf | ✅ | +| Kilo Code | ✅ | +| Roo Code | ✅ | +| Codex CLI | ✅ | +| opencode | ✅ | + +The templates are designed to work across agents without tweaks. + +### Project structure + +After running `specify init`, you'll see: + +``` +├───.github (or agent-specific folder) +│ └───prompts +│ plan.prompt.md +│ specify.prompt.md +│ tasks.prompt.md +│ +└───.specify + ├───memory + │ constitution.md + │ + ├───scripts + │ └───bash (or powershell) + │ check-task-prerequisites.sh + │ create-new-feature.sh + │ setup-plan.sh + │ + └───templates + plan-template.md + spec-template.md + tasks-template.md +``` + +## When SDD works + +### Ideal scenarios + +**Greenfield development (0-to-1):** Starting new projects from scratch. Small upfront work ensures AI builds actual intent, not generic solutions based on common patterns. + +**Feature work in existing systems (N-to-N+1):** The most powerful use case. Adding features to complex, existing codebases. Forces clarity on how new features interact with existing systems. New code feels native, not bolted-on. + +**Legacy modernization:** Rebuilding legacy systems where original intent is lost to time. Capture essential business logic in a modern spec, design fresh architecture, and let AI rebuild without inherited debt. + +**Complex systems with many contributors:** Microservice architectures, multi-repo frontends, AI-powered backends. Every boundary becomes explicit, enabling contract testing. + +**High-stakes features:** Payment flows, healthcare diagnostics, safety-critical automation. Encode performance, security, and reliability thresholds. + +**Long-term projects:** When a project will outlive the founding team, SDD preserves design intent as institutional memory. + +### When to skip it + +**Quick prototypes:** SDD might be overkill. Lighten the process—short spec, simple plan, manual notes. + +**Design experiments:** SDD's full structure slows momentum when you're exploring. + +**One-shot operations:** Sometimes you need immediate results without iteration. + +**Simple, well-understood problems:** Overhead isn't justified for trivial tasks. + +## Why this works + +The core problem with vague prompting is that language models are exceptional at pattern completion, not mind reading. + +Vague prompt: "add photo sharing to my app" + +This forces the model to guess at thousands of unstated requirements. It makes reasonable assumptions—but some will be wrong. You discover issues deep into implementation when they're expensive to fix. + +**With clear specification + technical plan + focused tasks = AI clarity** + +Now, instead of guessing, AI: + +- **Knows what to build:** From specification +- **Knows how to build it:** From plan +- **Knows sequence:** From tasks +- **Knows constraints:** From constitution + +The approach works across different stacks because the fundamental challenge is the same: translating intent into working code. Your specification captures intent clearly. Your plan translates intent to technical decisions. And tasks break the work down into implementable pieces. AI just handles the actual coding. + +## Common pitfalls + +### Over-specifying too early + +**Problem:** Trying to capture every pixel before building. + +**Solution:** Specs should evolve with insight. Aim for just-enough structure for test automation and AI generation, and iterate as you validate assumptions. + +### Letting specs drift + +**Problem:** Changes sneak into production without spec updates. + +**Solution:** Treat the document as your changelog's front line. Update the spec first, then merge code. This preserves traceability for audits. + +### No clear ownership + +**Problem:** "Someone else will fix it later" syndrome. + +**Solution:** Appoint a "spec steward" (a role that rotates) to ensure that merge requests include spec updates. They should flag inconsistencies early. + +### Focusing on what instead of why + +**Problem:** Future teammates lack context for confident changes. + +**Solution:** Capture rationale as well as requirements. Include business drivers ("reduce checkout time to under 2 seconds") and document risks mitigated ("meet SOC 2 audit log mandates"). + +### Treating as static document + +**Problem:** The spec becomes an outdated artifact. + +**Solution:** Keep your spec as living document that evolves alongside the code. Update during maintenance phase and keep a changelog of revisions. + +## Enterprise benefits + +**Centralized requirements:** Security policies, compliance rules, design system constraints, integration needs—these should all live in the specification and plan, where AI can actually use them. Not in someone's head, buried in a wiki nobody reads, or scattered across Slack conversations. + +**Auditability:** With a spec commit linked to every release, you have a provable chain from requirement to implementation, to satisfy auditors demanding due diligence. + +**Shared vocabulary:** One glossary of user flows, metrics, and error states. With no dueling definitions of "session", "tenant", or "SLA", you have less friction in cross-functional work. + +**Accelerated onboarding:** New hires skim change-tracked specs. They can see how requirements evolved and reach productive coding in days, not weeks. + +**Safe parallel development:** With interfaces frozen in contract and mock servers generated from specification, you can surface integration issues early, before staging. + +## The shift in thinking + +Traditional development: code is the source of truth. + +Spec-driven development: _intent_ is the source of truth. + +You stop asking "How do I get the perfect prompt?" and start asking "How do I capture intent clearly enough that AI can execute it?" + +The agent's job is translating intent into working code. Your job is making that intent explicit, reviewable, and evolvable. + +## Resources + +### Official + +- TRY: [GitHub - github/spec-kit](https://github.com/github/spec-kit) — Official repository (62k+ stars, MIT license) +- READ: [Spec-driven development with AI - GitHub Blog](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) — Official announcement and overview + +### Tutorials + +- READ: [Spec-Driven Development Tutorial using GitHub Spec Kit](https://www.scalablepath.com/machine-learning/spec-driven-development-workflow) — Real-world tutorial with examples +- READ: [Diving Into Spec-Driven Development With GitHub Spec Kit](https://developer.microsoft.com/blog/spec-driven-development-spec-kit) — Microsoft Developer Blog + +### Maintainers + +- Den Delimarsky (@localden) +- John Lam (@jflam) + +--- + +**Using SDD in production?** [Share your experience](/community/contributing/)—what worked, what didn't, and what you learned along the way. diff --git a/src/content/docs/ru/introduction/trends-patterns.md b/src/content/docs/ru/introduction/trends-patterns.md new file mode 100644 index 0000000..60cc5c7 --- /dev/null +++ b/src/content/docs/ru/introduction/trends-patterns.md @@ -0,0 +1,275 @@ +--- +title: AI Coding Trends & Patterns +description: Emerging patterns and techniques in AI-assisted development +sidebar: + order: 5 +--- + +A collection of emerging patterns, techniques, and methodologies in AI-assisted software development. These approaches represent evolving best practices from the community. + +## Development Patterns + +### Ralph Wiggum + +An AI loop technique for running coding agents in continuous loops where the AI iterates on its own output repeatedly until tests pass and the code compiles. This approach uses "stop hooks" to prevent premature exit, forcing the AI to refine its work through multiple passes instead of attempting perfection on the first try. + +→ **[Read the full Ralph Wiggum guide](/introduction/patterns/ralph-wiggum/)** + +**Key characteristics:** + +- Deterministically bad failures (predictable and informative) +- Automatic retry logic +- Loop continues until completion criteria met +- Success depends on good prompt engineering + +**Use cases:** + +- Refactoring loops (duplicate code detection and cleanup) +- Linting loops (incremental error fixing) +- Entropy reduction (code smell removal) + +**Resources:** + +- READ: [Ralph Wiggum as a Software Engineer](https://ghuntley.com/ralph/) - Original concept +- READ: [Ralph Wiggum - AI Loop Technique for Claude Code](https://awesomeclaude.ai/ralph-wiggum) - Complete guide and examples +- READ: [11 Tips For AI Coding With Ralph Wiggum](https://www.aihero.dev/tips-for-ai-coding-with-ralph-wiggum) - Practical tips for autonomous loops +- READ: [The Ralph Wiggum Approach: Running AI Coding Agents for Hours](https://dev.to/sivarampg/the-ralph-wiggum-approach-running-ai-coding-agents-for-hours-not-minutes-57c1) - DEV Community tutorial +- TRY: [GitHub - vercel-labs/ralph-loop-agent](https://github.com/vercel-labs/ralph-loop-agent) - Open source implementation + +### Spec-Driven Development (Spec Kit) + +A methodology that treats specifications as executable, living artifacts that directly drive AI agent implementation. Instead of jumping straight to code, you define intent in a specification that becomes the source of truth—preventing the "vibe coding" trap where agents build something that compiles but doesn't match what you actually wanted. + +→ **[Read the full Spec-Driven Development guide](/introduction/patterns/spec-driven-development/)** + +**Key characteristics:** + +- Specifications defined upfront as living documents +- Phased workflow: Constitution → Specify → Plan → Tasks → Implement +- Multi-variant exploration from same spec +- Works with GitHub Copilot, Claude Code, Gemini CLI, Cursor, and more + +**Use cases:** + +- Greenfield development with clear intent +- Feature work in complex existing codebases +- Legacy modernization +- High-stakes features (payments, healthcare, safety-critical) + +**Resources:** + +- READ: [Spec-driven development with AI - GitHub Blog](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) - Official announcement and overview +- TRY: [GitHub - github/spec-kit](https://github.com/github/spec-kit) - Official spec-kit repository +- READ: [Spec-Driven Development Tutorial using GitHub Spec Kit](https://www.scalablepath.com/machine-learning/spec-driven-development-workflow) - Real-world tutorial with examples +- READ: [Diving Into Spec-Driven Development With GitHub Spec Kit](https://developer.microsoft.com/blog/spec-driven-development-spec-kit) - Microsoft Developer Blog + +### Research, Plan, Implement (RPI) + +A three-phase framework for transforming chaotic AI interactions into predictable, high-quality software delivery. Instead of jumping straight to code generation, RPI breaks work into focused phases with built-in validation: research what exists, plan the change systematically, then execute mechanically. + +→ **[Read the full RPI guide](/introduction/patterns/rpi/)** + +**The three phases:** + +1. **Research**: Document what exists today—no opinions, no suggestions, just facts. +2. **Plan**: Design the change with atomic tasks, success criteria, and validation checkpoints. +3. **Implement**: Execute mechanically, verify after each phase, and update progress tracking. + +**Key principle:** Planning without research leads to bad assumptions. RPI uses FAR (Factual, Actionable, Relevant) and FACTS (Feasible, Atomic, Clear, Testable, Scoped) validation scales to ensure readiness before proceeding. + +**Resources:** + +- READ: [Research → Plan → Implement Pattern | goose](https://block.github.io/goose/docs/tutorials/rpi/) - Official tutorial with demonstrations +- READ: [Introducing the RPI Strategy](https://patrickarobinson.com/blog/introducing-rpi-strategy/) - Creator's blog post explaining the approach +- WATCH: [The RPI workflow - Build Wiz AI Show (Podcast)](https://open.spotify.com/episode/1OdIYj0SZzhyzFGGoVuELP) - Audio discussion on advanced AI coding + +### Outcome Engineering (o16g) + +A manifesto for reorienting development around outcomes rather than code. O16g argues that with AI agents removing the constraints of human bandwidth, we should manage to cost (tokens) instead of capacity (engineer-hours), measure success by verified impact rather than lines written, and treat code as the mechanism for delivering ideas rather than the end goal itself. + +→ **[Read the full Outcome Engineering guide](/introduction/patterns/outcome-engineering/)** + +**Core reframing:** + +- Creation, not code — Focus on what you're building, not how you're typing it. +- Cost, not time — If the outcome is worth the tokens, it gets built. +- Certainty, not vibes — The only truth is the rate of positive change delivered to the customer. + +**The 16 principles include:** + +- "The Backlog is Dead" — Never reject an idea for lack of time, only for lack of budget. +- "Code the Constitution" — Encode laws and intent into the environment where agents can use them. +- "Verified Reality is the Only Truth" — Grade agents on verified outcomes, not lines written. +- "Failures are Artifacts" — Debug the decision, not just the code. + +**Resources:** + +- READ: [The o16g Manifesto](https://o16g.com/) — Complete manifesto with all 16 principles + +### OpenClaw + +An open-source AI agent runtime that connects language models to your existing tools and services. Instead of AI living in a browser tab, OpenClaw runs locally (or on your VPS) and integrates with messaging apps, calendars, email, shell, browser, and more—giving agents persistent context about your workflow. + +→ **[Read the full OpenClaw guide](/introduction/patterns/openclaw/)** + +**Key characteristics:** + +- Runs locally or self-hosted (your data stays yours) +- Connects to messaging (Telegram, Discord, Signal, Slack), calendars, email, and more +- Persistent memory across sessions via workspace files +- Sub-agent spawning for parallel background tasks +- Skills system for extending capabilities + +**Use cases:** + +- Personal AI assistant with access to your actual tools +- Automated workflows (inbox triage, calendar management, code review) +- Proactive monitoring and scheduled tasks +- Background research and task execution + +**Resources:** + +- TRY: [OpenClaw GitHub](https://github.com/openclaw/openclaw) - Open source repository +- READ: [OpenClaw Documentation](https://docs.openclaw.ai) - Official docs +- JOIN: [OpenClaw Discord](https://discord.com/invite/clawd) - Community support + +*Note: OpenClaw was originally called "ClawdBot", then "MoltBot", before landing on "OpenClaw".* + +## Prompting Patterns + +### Stepwise / Iterative Prompting + +In this pattern, you break complex tasks into small, manageable chunks with feedback loops between each iteration, rather than requesting monolithic code blocks. + +**Benefits:** + +- Easier to debug and validate +- Better context management +- More control over direction +- Reduced cognitive load + +**Example approach:** + +1. "First, update the type definitions" +2. Review and approve +3. "Now update the implementation to match" +4. Review and approve +5. "Finally, add tests" + +**Resources:** + +- READ: [How to write better prompts for AI code generation](https://graphite.com/guides/better-prompts-ai-code) - Best practices guide +- READ: [Iterative Prompt Refinement: Step-by-Step Guide](https://latitude-blog.ghost.io/blog/iterative-prompt-refinement-step-by-step-guide/) - Structured experimentation approach +- READ: [What is Iterative Prompting? | IBM](https://www.ibm.com/think/topics/iterative-prompting) - Enterprise perspective on best practices + +### Context Packing / Brain Dumps + +This is the practice of frontloading all relevant context (codebase architecture, API docs, constraints, invariants) into prompts before coding. + +**What to include:** + +- Architecture overview +- API documentation +- Constraints and requirements +- Existing patterns and conventions +- Known gotchas or edge cases + +**Benefit:** Reduces hallucinations and improves first-attempt accuracy. + +**Resources:** + +- READ: [How to Manage Context in AI Coding Workflows](https://refactoring.fm/p/managing-context-for-ai-coding) - Context management strategies +- READ: [16x Prompt - AI Coding with Advanced Context Management](https://prompt.16x.engineer/) - Tool and methodology +- READ: [Context Engineering: Bringing Engineering Discipline to Prompts](https://addyo.substack.com/p/context-engineering-bringing-engineering) - Engineering approach to context + +### Chain-of-Thought Prompting + +Asking AI to explain its reasoning step-by-step before providing code, similar to requiring a design doc. + +**Example prompt structure:** + +``` +Before writing code, explain: +1. What problem you're solving +2. Your approach and why +3. Key design decisions +4. Potential trade-offs + +Then provide the implementation. +``` + +**Benefits:** + +- Catches logical errors early +- Makes reasoning auditable +- Helps humans understand approach +- Often improves code quality + +**Resources:** + +- READ: [Chain-of-Thought Prompting | Prompt Engineering Guide](https://www.promptingguide.ai/techniques/cot) - Comprehensive technique guide +- READ: [Chain of Thought Prompting Explained | Codecademy](https://www.codecademy.com/article/chain-of-thought-cot-prompting) - Tutorial with examples +- READ: [Chain-of-Thought Prompting: Techniques, Tips, and Code Examples](https://www.helicone.ai/blog/chain-of-thought-prompting) - Implementation guide with code + +## Development Styles + +### Vibe Coding / Prompt-First Development + +In this style of AI-assisted development, developers describe what they want in natural language and iterate with the AI. + +**Characteristics:** + +- Natural language specifications +- Rapid iteration +- Learn by doing +- Less upfront planning + +**When it works:** + +- Prototyping and exploration +- Well-understood domains +- Individual developer projects + +**Risks:** + +- Accumulated technical debt +- Unclear requirements +- Harder to maintain long-term + +**Resources:** + +- TRY: [Vibe Coding Prompts | VibeCodex](https://vibecodex.io/) - Curated prompt directory +- READ: [The 50 Most Important Vibe Coding Prompts to Learn First](https://hexshift.medium.com/the-50-most-important-vibe-coding-prompts-to-learn-first-9a1e2a6d5623) - Essential prompt library +- READ: [8 Vibe Coding Prompt Techniques for Web Development](https://strapi.io/blog/vibe-coding-prompt-techniques) - Practical techniques +- READ: [Mastering prompting techniques for vibe coding](https://medium.com/@zahwahjameel26/mastering-prompting-techniques-for-vibe-coding-e140ad07603b) - Advanced prompting guide + +### Objective-Validation Protocol + +This is a systematic approach to defining clear success criteria and validation objectives for AI-generated code, establishing performance thresholds and tracking validation goals across iterations. + +**Components:** + +- Clear success criteria +- Performance thresholds +- Validation checkpoints +- Tracking across iterations + +**Benefits:** + +- Measurable progress +- Objective quality gates +- Easier debugging +- Better documentation + +## Adoption Considerations + +When evaluating these patterns, consider: + +- **Team maturity**: Some patterns require more AI experience. +- **Project phase**: Different patterns suit exploration vs. production. +- **Code criticality**: Safety-critical code needs more rigorous approaches. +- **Team size**: Collaborative work may need more structured patterns. + +--- + +_This is a living document. Patterns will evolve as the community learns what works._ \ No newline at end of file diff --git a/src/content/docs/ru/introduction/what-is-agentic-engineering.md b/src/content/docs/ru/introduction/what-is-agentic-engineering.md new file mode 100644 index 0000000..6b9f021 --- /dev/null +++ b/src/content/docs/ru/introduction/what-is-agentic-engineering.md @@ -0,0 +1,95 @@ +--- +title: What is Agentic Engineering? +description: The practice of orchestrating AI agents to accomplish software development tasks with varying degrees of autonomy. +sidebar: + order: 1 +--- + +**Agentic engineering** is the practice of orchestrating AI agents to accomplish software development tasks—shifting your role from writing every line to directing a team of intelligent assistants. + +## The core concept + +With agentic engineering, you become a general contractor, not a bricklayer. Instead of typing all the code yourself, you define requirements, coordinate AI agents, and ensure the final result meets spec. The best practitioners know _how_ to do the work—they choose to delegate most of it. + +**Your job shifts from production to direction.** You spend less time typing and more time on: + +- Defining clear requirements +- Breaking problems into agent-sized tasks +- Reviewing and validating output +- Catching what agents miss + +**Communication becomes your primary skill.** Agents do what you tell them, not what you mean (just like computers!). Precision in task definition determines output quality. + +## What hasn't changed + +You still need to understand code deeply. Agents make mistakes—sometimes subtle ones. If you can't read code critically, you'll ship bugs faster than ever. AI is the ultimate force multiplier—and that includes multiplying all your mistakes. + +You still own the architecture. Agents excel at local changes but struggle with system-level thinking. + +You still need domain knowledge. Agents don't know your users, constraints, or business logic. You bring the context they lack. + +## The autonomy spectrum + +**Choose your level of AI involvement based on the clarity of your task and risk.** Not all AI assistance is equal—the right level depends on how well-defined your task is and how much oversight you need. + +### AI as Copilot + +At this level, AI suggests, and you approve every change. + +- **What it does:** Generates code blocks based on context and comments +- **You control:** When to invoke, what context to provide, what to accept +- **Best for:** Writing functions from descriptions, explaining code, generating tests + +### AI as Task Agent + +At this level, AI executes defined tasks autonomously, and you review the results. + +- **What it does:** Takes a defined task and executes multiple steps to complete it +- **You control:** The goal, constraints, and validation criteria +- **Best for:** Features spanning multiple files, refactoring, bug fixes with clear repro steps + +### AI as Workflow Agent + +At the far end of the spectrum, AI manages multi-step workflows, while you set goals and constraints. + +- **What it does:** Handles entire workflows including planning, implementation, testing, and iteration +- **You control:** High-level objectives and guardrails +- **Best for:** Well-defined projects with clear acceptance criteria, prototypes, exploration + +### Choosing the right level + +Higher autonomy doesn't necessarily mean better, so you want to match the level to your situation. Here are some factors to consider: + +- **Task clarity:** Ambiguous tasks fail at higher autonomy levels. +- **Risk tolerance:** Critical code paths deserve more human oversight. +- **Your familiarity:** In unfamiliar territory, stick to lower autonomy. +- **Iteration speed:** Sometimes writing it yourself is faster than going through the prompt-debug-reprompt loop. + +Think of autonomy as a slider, not a fixed setting. Start at Copilot for exploration, move to Task Agent for well-understood work, and always be ready to take manual control. + +## Why now? + +**AI coding tools crossed a usefulness threshold in 2023-2024.** Three capabilities converged: context windows expanded to handle entire codebases, tool use became reliable enough for agents to read files and run commands, and reasoning improved enough for multi-step planning. Models stopped being chatbots and became actors. + +## Who this guide is for + +Different roles have different concerns. Jump to what matters most for your role, or read through for the complete picture. + +- **Engineers:** Learn how to work effectively with agents without losing your edge. See the [Getting Started](/engineers/getting-started/) guide for practical workflows. +- **Team leads:** Learn how to integrate these tools into existing workflows and train your teams. Start with [Adopting Agentic Tools](/team-leads/adopting-agentic-tools/). +- **Executives:** Learn how to make strategic decisions about AI adoption, budget, and risk. The [Strategic Vision](/executives/strategic-vision/) section covers the business case. + +**This guide is community-driven.** We're all learning together. If you have experience to share or gaps to fill, [join us](/community/). + +## Resources + +### Essential + +- READ: [The Space Between AI Hype and AI Denial](https://blog.kilo.ai/p/between-ai-hype-and-ai-denial) - Finding the productive middle ground for AI adoption +- WATCH: [The 3 Pillars of Autonomy – Michele Catasta, Replit](https://www.youtube.com/watch?v=MLhAA9yguwM) - Core framework for agent autonomy +- READ: [The o16g Manifesto](https://o16g.com/) - "Outcome Engineering" — reframing development around outcomes, not code + +### Deep dives + +- WATCH: [From Vibe Coding To Vibe Engineering – Kitze, Sizzy](https://www.youtube.com/watch?v=JV-wY5pxXLo) - How AI collaboration redefines development +- READ: [Vibe engineering](https://simonwillison.net/2025/Oct/7/vibe-engineering/) - Defining responsible AI-assisted development \ No newline at end of file diff --git a/src/content/docs/ru/introduction/working-with-agents.md b/src/content/docs/ru/introduction/working-with-agents.md new file mode 100644 index 0000000..ca082f7 --- /dev/null +++ b/src/content/docs/ru/introduction/working-with-agents.md @@ -0,0 +1,65 @@ +--- +title: Working with Agents +description: Practical patterns for human-AI collaboration - when to intervene, how to review, and structuring code for agent effectiveness. +sidebar: + order: 3 +--- + +## The Collaboration Spectrum + +Maximizing AI involvement isn't the point—effective agentic engineering is about finding the right balance for each task. Neither doing everything yourself nor delegating everything works well. + +**Hands-off** works best for well-defined tasks: +- Boilerplate generation +- Test writing +- Documentation +- Refactoring established patterns + +**Hands-on** is essential for: +- Architecture decisions +- Security-sensitive code +- Requirements clarification +- Domain-specific logic + +Most real work falls somewhere in between. Feature implementation, debugging, and API design benefit from active collaboration where you guide while the agent executes. + +## When to Intervene + +Watch for these signals that it's time to step in: + +- **Agent looping**: Repeating similar attempts without progress +- **Quality declining**: Output getting worse, not better +- **Scope creep**: Drifting beyond the original task boundaries +- **Irreversible actions**: About to delete data, push to production, or make breaking changes + +When the agent is making steady progress and errors are getting corrected, let it continue. Intervene when you see circular patterns or diminishing returns after 2-3 reprompts. + +## The Review Mindset + +Reviewing agent output differs fundamentally from reviewing human code. Focus on **intent and correctness**, not style preferences—the agent won't learn from your feedback anyway. + +**Always verify:** + +- Does the output actually solve the stated problem? +- Are edge cases and error conditions handled? +- Is the approach reasonable, not just functional? +- Any security implications? + +Don't assume passing tests mean correctness or that confident explanations reflect accuracy. Treat agent output like code from a skilled contractor: technically competent but unfamiliar with your specific context. + +## Building AI-Ready Codebases + +The Unix philosophy—small tools, clear interfaces, composability—is exactly what agents need to work effectively. Structure your code with agents in mind. + +- **Small, focused functions**: A 20-line function is far easier for an agent to understand and modify correctly than a 200-line one. Smaller scope means fewer errors. +- **Clear interfaces**: Explicit inputs and outputs help agents reason about dependencies and chain operations together. Ambiguous interfaces cause integration bugs. +- **Consistent patterns**: Predictable structure reduces agent errors. When similar problems are solved similarly, agents can apply patterns reliably. +- **Good naming**: `getUserById(id)` beats `get(x)`. Descriptive names are context that helps agents understand code without extensive exploration. + +You don't need to rewrite everything. As you touch code, nudge it toward these patterns—the benefits compound over time. + +## Effective Feedback + +When course-correcting, be specific about what's wrong and what you want instead. "The error handling is missing—add try/catch blocks that log failures and return graceful fallbacks" will get far better results than "Fix the error handling." + +Keep corrections focused. A single clear direction works better than multiple vague complaints. diff --git a/src/content/docs/ru/team-leads/1-pizza-teams.md b/src/content/docs/ru/team-leads/1-pizza-teams.md new file mode 100644 index 0000000..093e3bc --- /dev/null +++ b/src/content/docs/ru/team-leads/1-pizza-teams.md @@ -0,0 +1,90 @@ +--- +title: "The 1-Pizza Team: Why AI Makes Smaller Engineering Teams More Effective" +description: How AI agents are enabling smaller teams to ship what once required much larger groups +sidebar: + order: 4 +--- + +Amazon's "two-pizza team" rule has been gospel for decades: if you need more than two pizzas to feed a team, the team is too big. But something is shifting. Directors at traditional companies are now talking about "one-pizza teams." The math is changing. + +This isn't about layoffs or doing more with less in a grim, squeeze-the-workers sense. It's about what individuals can accomplish when they're managing AI agents alongside human collaborators. + +## The research backs this up + +A [Harvard and Wharton study at P&G](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5188231) found something striking: individuals using AI performed as well as teams without it. And teams with AI significantly outperformed teams without AI on producing top-tier ideas. + +Read that again. One person with AI tools matched the output of a traditional team. + +Microsoft's WorkLab research calls this the rise of the ["agent boss"](https://www.microsoft.com/en-us/worklab/ai-at-work-how-human-agent-teams-will-reshape-your-workforce)—everyone from interns to executives will manage their own constellation of AI agents. The hierarchy isn't flattening; it's extending into a new dimension where humans orchestrate machine intelligence. + +## What this looks like in practice + +Kilo's engineering model is one example. Each engineer [owns an entire product area and a WAU metric](https://blog.kilo.ai/p/our-engineers-own-a-number), not just a codebase. They manage teams of AI agents to parallelize work that would traditionally require multiple people. + +One engineer. One product area. One number to own. AI agents handling the parallelizable work. + +[Anthropic's internal research](https://www.anthropic.com/research/how-ai-is-transforming-work-at-anthropic) shows their engineers now use Claude in 60% of their work, reporting a 50% productivity boost—a 2-3x increase from the previous year. More telling: 27% of their Claude-assisted work is tasks that wouldn't have been done otherwise. This isn't just efficiency. It's expanded capability. + +## The new mental model: engineers as agent managers + +The shift requires thinking about your team differently. It's not just "how many engineers do I need?" but "what's the optimal ratio of humans to agents for this work?" + +Microsoft is already calling this the ["human-agent ratio"](https://www.microsoft.com/en-us/worklab/ai-at-work-how-human-agent-teams-will-reshape-your-workforce)—a new metric that will vary by task, process, and industry. Get it wrong, and you miss out on AI's value or overwhelm your team. Get it right, and you unlock the performance demonstrated in that P&G study. + +Your best engineers aren't just coding anymore. They're: + +- **Decomposing work** into agent-appropriate chunks +- **Reviewing agent output** for quality and correctness +- **Orchestrating parallel workstreams** across multiple agents +- **Making judgment calls** agents can't handle +- **Maintaining context** that agents lose between sessions + +These are management skills applied to AI systems. The job title stays "engineer," but the work looks more like coordination. + +## What this means for team structure + +Traditional team planning: "This project needs a frontend engineer, two backend engineers, a DevOps person, and a QA engineer. Five people." + +AI-native team planning: "This project needs two senior engineers who can each manage agent workstreams for their domain, plus one engineer focused on integration and quality. Three people, with explicit agent allocation." + +The [InsideAI News](https://insideainews.com/2024/04/24/artificial-intelligence-means-smaller-teams-doing-more-with-less-makes-the-small-autonomous-teams-structure-even-more-important/) analysis argues that AI actually makes small autonomous teams more necessary, not less. When individual contributors can have outsized impact through AI leverage, the overhead of large team coordination becomes even more costly. + +## The skill distribution shifts + +[Galileo's research on AI team dynamics](https://galileo.ai/blog/ai-engineering-team-dynamics) highlights how AI is blurring traditional role boundaries. Everyone shares responsibility for production outcomes, creating cross-functional teams that approach problems holistically. + +But this creates a new challenge: engineers must now cultivate expertise in analyzing production data, ensuring system observability, and managing complete software lifecycles—skills that extend beyond writing code. As Charity Majors puts it: "Software engineering is not about writing code. It's about solving business problems with technology." + +Engineers who can orchestrate AI effectively become force multipliers. Those who can't risk being outpaced by smaller teams that can. + +## Practical steps for team leads + +**Audit your team structure.** Where are you overstaffing because you're not accounting for AI leverage? A team of 8 doing what 4 people with good AI workflows could handle isn't sustainable when competitors figure this out. + +**Define agent allocation explicitly.** Don't let AI usage be ad-hoc. Identify which workstreams benefit from agent parallelization and resource them accordingly. + +**Measure the human-agent ratio.** Start tracking it even informally. How much of your team's output comes from direct human work vs. agent-assisted work? This will become a key metric. + +**Train for orchestration, not just coding.** Your best engineers need to develop skills in prompt engineering, agent workflow design, and AI output validation. These are trainable skills with compounding returns. + +**Watch for capability expansion.** Anthropic found 27% of AI-assisted work was new work that wouldn't have happened otherwise. Are your teams using AI to do the same work faster, or to do work that was previously impossible? The latter is where competitive advantage lives. + +## The uncomfortable truth + +Teams are getting smaller because they can. The organizations that recognize this early gain compounding advantages—they attract engineers who want leverage, they ship faster, and they compound learnings about AI-native workflows. + +The question isn't whether this transition is happening. It's whether you're leading it or reacting to it. + +## Resources + +### Essential reading + +- [How human-agent teams will reshape your workforce](https://www.microsoft.com/en-us/worklab/ai-at-work-how-human-agent-teams-will-reshape-your-workforce) - Microsoft WorkLab on the "agent boss" concept +- [How AI Is Transforming Work at Anthropic](https://www.anthropic.com/research/how-ai-is-transforming-work-at-anthropic) - Internal research on AI productivity gains +- [Why Our Engineers Own a Number, Not Just a Codebase](https://blog.kilo.ai/p/our-engineers-own-a-number) - Kilo's product engineering model +- [The Cybernetic Teammate (Harvard/Wharton)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5188231) - P&G field study on AI team performance + +### Deep dives + +- [How AI is Reshaping Engineering Teams](https://galileo.ai/blog/ai-engineering-team-dynamics) - Charity Majors on engineering management in the AI era +- [AI means smaller teams](https://insideainews.com/2024/04/24/artificial-intelligence-means-smaller-teams-doing-more-with-less-makes-the-small-autonomous-teams-structure-even-more-important/) - Why small autonomous teams become more important with AI diff --git a/src/content/docs/ru/team-leads/adopting-agentic-tools.md b/src/content/docs/ru/team-leads/adopting-agentic-tools.md new file mode 100644 index 0000000..6a9ee2a --- /dev/null +++ b/src/content/docs/ru/team-leads/adopting-agentic-tools.md @@ -0,0 +1,137 @@ +--- +title: Adopting Agentic Tools +description: Introducing agents to your team and building competency +sidebar: + order: 1 +--- + +Adding agents to your team isn't just installing a tool—it's changing how work flows. Here's how to do it without disrupting what already works. + +## Start with Pain Points + +Don't introduce agents everywhere at once. Pick one friction point: + +- **Slow code reviews?** Agents can pre-review for style and obvious issues +- **Test coverage gaps?** Agents excel at generating test cases +- **Documentation rot?** Agents can help keep docs in sync +- **Onboarding struggles?** Agents help new devs understand unfamiliar codebases + +Solve that one problem. Then expand. + +## Run a Pilot + +Before rolling out broadly: + +**Choose 2-3 willing engineers.** Include enthusiasts and skeptics—you want diverse feedback. + +**Define bounded scope.** "Use agents for test generation on the payments service for two weeks." + +**Measure something.** Test coverage, time to complete tasks, developer satisfaction. + +**Gather feedback.** What worked? What surprised you? + +## Integration Patterns + +| Pattern | Pros | Cons | Best for | +| ----------------------- | --------------------------------- | --------------------------- | ----------------- | +| **Individual** | Low coordination, experimentation | Inconsistent practices | Early exploration | +| **Review-integrated** | Maintains quality gates | Potential review bottleneck | Most teams | +| **Pair programming** | High quality, skill building | Time intensive | Complex tasks | +| **Automation pipeline** | Consistent, no adoption effort | Needs careful guardrails | Mature teams | + +## Workflow Adjustments + +**Daily standup:** Include agent-assisted work in updates. Share prompts that worked. + +**Sprint planning:** Factor in 10-30% improvement for agent-friendly tasks—not 10x. Account for learning curves initially. + +**Retrospectives:** Include agent effectiveness as a topic. Capture learnings. + +## The Skill Distribution + +Expect three groups on your team: + +- **Early adopters (10-20%):** Already experimenting. Use them as resources and mentors. +- **Curious middle (50-60%):** Open but need guidance. This is your main training audience. +- **Skeptics (20-30%):** Range from cautious to resistant. Some have valid concerns. + +Each group needs a different approach. + +## Training Early Adopters + +They don't need convincing. Give them: + +- **Time and permission** to experiment +- **Hard problems** to push boundaries +- **Platform to share** what works +- **Guardrails** when enthusiasm outpaces judgment + +## Training the Curious Middle + +Don't lecture. Do. + +**Hands-on workshops (90 min, 70% hands-on):** + +1. First prompt to working code +2. Task decomposition practice +3. Validating and fixing agent output +4. Real project work with support + +**Pairing and shadowing:** Pair curious engineers with early adopters for real tasks, not demos. + +**Curated resources:** Create a team guide with recommended tools, prompt templates for your stack, examples from your codebase, and common pitfalls. + +## Training Skeptics + +Don't force it. Address concerns legitimately. + +| Concern | Response | +| ------------------------------ | ---------------------------------------------------------- | +| "Makes engineers less skilled" | Agents amplify skill—weak engineers struggle with them too | +| "Output quality is poor" | Quality comes from good prompts, not just tools | +| "It's a fad" | Major companies are standardizing on these tools | +| "Not worth the learning curve" | Start with high-ROI, low-risk: tests, docs, boilerplate | + +Give them space. Some need to watch peers succeed first. + +## Building a Curriculum + +**Beginner:** Agent concepts → First experience workshop → Daily copilot use → Supervised task-level work + +**Intermediate:** Task decomposition mastery → Failure mode case studies → Multi-file tasks → Code review for AI code + +**Advanced:** Custom prompts and workflows → Evaluating new tools → Teaching others → Shaping team practices + +## Common Mistakes + +- **Mandating usage** breeds resentment—let adoption grow organically +- **Expecting immediate ROI** ignores real learning curves +- **Ignoring resistance** dismisses valid concerns +- **One-size-fits-all** ignores different working styles + +## Measuring Training Effectiveness + +**Before:** Survey confidence, track adoption rates, note existing competencies. + +**After:** Survey again, track skill application, gather qualitative feedback. + +**Long-term:** Watch for adoption persistence, quality of agent use, and peer mentoring emergence. + +## Resources + +### Essential + +- [Your Team Is Already Using AI. Now What?](https://blog.kilo.ai/p/your-team-is-already-using-ai-now) - Practical guide for leading teams already using AI +- [Stop Peanut Buttering AI Onto Your Organization](https://blog.kilo.ai/p/stop-peanut-buttering-ai) - Why adding AI without restructuring fails +- [Leadership in AI Assisted Engineering – Justin Reock, DX](https://www.youtube.com/watch?v=PmZDupFP3UM) - Data-driven framework for top-down AI adoption +- [Early adoption is the key to AI coding success](https://blog.kilo.ai/p/early-adoption-ai-coding) - Why early-adopting teams compound their advantages + +### Videos + +- [Dispatch from the Future – Dan Shipper, Every](https://www.youtube.com/watch?v=MGzymaYBiss) - How 100% AI adoption changes organizational physics +- [Moving away from Agile – Martin Harrysson, McKinsey](https://www.youtube.com/watch?v=SZStlIhyTCY) - Why unchanged operating models limit AI value + +### Courses + +- [Prompt Engineering Specialization – Vanderbilt University](https://www.coursera.org/specializations/prompt-engineering) - Comprehensive team training resource +- [The Complete AI Coding Course (2025)](https://www.udemy.com/course/the-complete-ai-coding-course-2025-cursor-ai-v0-vercel/) - Hands-on Cursor and Claude Code training diff --git a/src/content/docs/ru/team-leads/measuring-impact.md b/src/content/docs/ru/team-leads/measuring-impact.md new file mode 100644 index 0000000..83d5aef --- /dev/null +++ b/src/content/docs/ru/team-leads/measuring-impact.md @@ -0,0 +1,149 @@ +--- +title: Measuring Impact +description: What to measure, what not to measure, and when to pull back +sidebar: + order: 3 +--- + +Everyone wants to measure agent impact. Most measurements are wrong. And sometimes agents slow you down. + +## The Measurement Trap + +When you measure wrong things, people optimize for metrics, not outcomes. + +| Bad metric | Gaming behavior | +| -------------------------- | --------------------------------------------- | +| Lines of code generated | Verbose, less clean code | +| Tasks completed per sprint | Task inflation, tiny pieces | +| Time using AI tools | Running agents on things faster done manually | + +## What to Actually Measure + +### Leading Indicators (early signals) + +- **Acceptance rate:** What % of suggestions accepted vs. rejected? Low rates suggest poor fit or skill gaps. +- **Iteration count:** How many prompt cycles before useful output? Decreasing = improving skills. +- **Task scope:** Are engineers tackling larger tasks with agent help? Growing confidence. +- **Review feedback:** Are reviewers catching fewer issues in agent-assisted PRs over time? + +### Lagging Indicators (outcomes) + +- **Velocity:** Look at trends, not absolutes. Compare to teams not using agents. (Careful—gameable.) +- **Bug rates:** Bugs per feature changing? Account for code attribution. +- **Time to production:** Feature start to deploy. Harder to game. +- **Developer satisfaction:** Survey your team. Happy devs are productive devs. + +### What Not to Measure + +- **Lines of code**—irrelevant and gameable +- **Tool usage time**—usage ≠ value +- **Cost of AI tools**—matters for ROI, not effectiveness +- **Prompt count**—more prompts might mean learning + +## The Attribution Problem + +Who gets credit for AI-generated code? Who takes blame? + +**Don't solve this.** Treat agent-assisted code like any other. The human who committed it owns it. + +This simplifies everything: no separate metrics, normal accountability, no need to track percentages. + +## Qualitative Signals + +Numbers don't tell the whole story. Watch for: + +- **Team sentiment:** Excitement or frustration? Positive talk about agents? +- **Adoption patterns:** Senior engineers using agents is a quality signal +- **Knowledge sharing:** Organic prompt sharing indicates value +- **Problem selection:** Engineers tackling harder problems is often the real win + +## Running an Experiment + +If you need rigorous measurement: + +1. **Control group:** Some work happens without agents +2. **Clear metrics:** Define before you start +3. **Time bound:** 4-6 weeks to account for learning curves +4. **Survey participants:** Qualitative data matters + +But most teams don't need academic proof—just signals that adoption is working. + +## The Real Question + +Don't ask "Are agents making us more productive?" + +Ask **"Are we building what we need, at the quality we need, without burning out?"** + +If yes, your approach is working. + +--- + +## When Agents Help + +### High-volume repetitive tasks + +Tests for multiple functions, docs across files, API boilerplate, migration scripts. Same thing, many times—agents thrive. + +### New territory exploration + +Unfamiliar framework? Agent scaffolds while you learn. New language? Get working examples. Unknown API? Generate integration code to understand patterns. + +### Clear spec, straightforward implementation + +CRUD with defined schemas, form validation with known rules, utilities with well-defined I/O. Low ambiguity, well-understood problem space. + +### Tedious but necessary + +Mocks and fixtures, logging and error handling, consistent formatting, config updates across many places. Takes time but not thought. + +## When Agents Slow You Down + +### High-context tasks + +If understanding requires reading complex business logic, historical decisions, or unwritten conventions—you'd have to explain it all anyway. Often faster to just do it. + +### Tasks faster done manually + +**Prompting + waiting + reviewing > manual coding?** Just code it. Especially true for single-line changes, familiar patterns, quick fixes. + +Build intuition for your personal break-even point. + +### Novel algorithms + +Agents pattern-match training data. New algorithmic approaches, domain-specific optimization, unusual data structures—solve it yourself, let agents help with boring parts around it. + +### Highly coupled changes + +Changes touching many tightly-interdependent parts are hard for agents. They may not understand connections, errors compound, validation requires whole-system understanding. Break these apart or do manually. + +### Ambiguous requirements + +"Make it better" or "improve performance" without specifics wastes cycles. Agents need clear success criteria, defined constraints, specific scope. If you can't articulate these, you're not ready to delegate. + +## Team-Level Patterns + +**Task assignment:** Don't assign agent-hostile tasks expecting agents will help. + +**Sprint planning:** Don't assume agent help for all tasks. Call out which are agent-friendly. Account for validation overhead. + +**Retrospectives:** Review where agents helped and hindered. What task types worked? Where did you waste time prompting? + +## Building Team Judgment + +- **Share examples:** "This task would have been faster manually—here's why." +- **Celebrate good choices:** Acknowledge when someone correctly decides _not_ to use an agent. +- **Create a reference:** Maintain a guide of task types and recommended approaches. +- **Review periodically:** As tools improve, patterns change. + +## Resources + +### Essential + +- [Does AI Actually Boost Developer Productivity? – Yegor Denisov-Blanch, Stanford](https://www.youtube.com/watch?v=tbDDYKRFjhk) - 100k developer study: ~20% average boost, significant variance +- [Stop Looking for AI Coding Spending Caps](https://blog.kilo.ai/p/stop-looking-for-ai-coding-spending) - Why caps cost more than they save +- [ML-Enhanced Code Completion – Google Research](https://research.google/blog/ml-enhanced-code-completion-improves-developer-productivity/) - Google's productivity impact research + +### Deep dives + +- [The reality of AI-Assisted software engineering productivity](https://addyo.substack.com/p/the-reality-of-ai-assisted-software) - Balanced take on productivity claims +- [Vibe coding is already dead](https://www.youtube.com/watch?v=tKPtZtsLgUA) - Critical perspective on when AI tools backfire diff --git a/src/content/docs/ru/team-leads/quality-assurance.md b/src/content/docs/ru/team-leads/quality-assurance.md new file mode 100644 index 0000000..e688c01 --- /dev/null +++ b/src/content/docs/ru/team-leads/quality-assurance.md @@ -0,0 +1,137 @@ +--- +title: Quality Assurance with Agents +description: Code review policies and testing strategies for agentic workflows +sidebar: + order: 2 +--- + +AI-generated code changes the code review and testing dynamic. Your policies need to adapt. + +## Code Review Policy Options + +Should AI-generated code be reviewed differently? Most teams land in the middle. + +| Policy | How it works | Best for | +| ---------------------- | ---------------------------------------------- | --------------------------------------------- | +| **No differentiation** | Same review for all code | Small, high-trust teams with rigorous reviews | +| **Disclosure only** | Authors flag significant AI code | Transparency without bureaucracy | +| **Tiered review** | Extra scrutiny on critical paths + AI | Risk-varying codebases | +| **AI-assisted review** | AI pre-reviews; humans focus on what AI misses | High PR volume teams | + +## If You Require Disclosure + +Make it easy: + +- **Clear trigger:** "Disclose when >20% of the PR was generated by AI tools" +- **Simple mechanism:** Checkbox in PR template or a tag/label +- **No stigma:** Disclosure is information, not judgment +- **Useful metadata:** Which tool? What prompts? Helps with learning + +## Review Checklist for AI Code + +Train reviewers to watch for AI-specific issues: + +- [ ] Hallucinated APIs or methods +- [ ] Plausible but incorrect logic +- [ ] Missing edge case handling +- [ ] Inconsistent with existing patterns +- [ ] Over-engineered for the task + +Plus standard checks: meets requirements, handles errors, security addressed, tests adequate, docs updated. + +## Building Reviewer Skills + +Some reviewers catch AI mistakes better than others. This is trainable. + +- Share examples of AI failures caught in review +- Pair junior reviewers with experienced ones +- Create a team knowledge base of AI pitfalls + +## What Not to Do + +- **Don't create a separate "AI code" branch**—integration nightmares +- **Don't require manager approval for AI usage**—kills adoption +- **Don't ignore the conversation**—pretending AI isn't changing things helps no one + +## Shift Testing Left + +Traditional: Write code → Test → Review → Deploy + +Agentic: **Write spec → Generate tests → Generate code → Verify tests pass → Review → Deploy** + +Tests come _before_ implementation. + +### Why This Works + +- Tests define success criteria for the agent +- Agents can run tests to self-validate +- Fewer iterations when the goal is clear +- Tests document intent + +### How to Implement + +**Write tests as part of task definition.** Before asking an agent to implement a feature, write (or generate) the tests it should pass. + +**Use TDD prompting.** "Here are the tests. Write code that makes them pass." + +**Treat test failures as agent feedback.** The test suite catches bugs, not you. + +## Using Agents for Test Generation + +Agents excel at writing tests. Use this. + +**Unit tests:** Give agent a function, get test cases back. Review for coverage gaps. + +**Edge cases:** Agents are good at imagining cases you might miss. + +**Integration tests:** More complex, but agents can generate scaffolding. + +### The Workflow + +1. Point agent at a module +2. Request tests covering happy path, edges, and errors +3. Review for gaps and hallucinated behavior +4. Refine until coverage is meaningful + +### Watch For + +- Tests that pass for wrong reasons +- Mocked dependencies hiding real issues +- Tests that don't actually test the requirement +- Copy-paste tests that don't add coverage + +## Test Coverage as Guardrail + +High test coverage makes agentic development safer. + +- **Minimum coverage gates:** Don't let agent-generated code reduce coverage +- **Critical path requirements:** Some paths need 100% coverage with meaningful tests +- **Coverage trends:** Track whether agent adoption correlates with coverage changes + +## Testing Agent Output + +Not just testing code—testing agent behavior itself. + +**Acceptance criteria:** Define what code should do, shouldn't do, edge cases, and verification method. + +**Canary testing (for automated workflows):** + +- Run agent changes through extended test suites before merge +- Stage behind feature flags +- Monitor for anomalies after deployment + +**Regression tracking:** Notice patterns—do certain task types introduce more bugs? Are there problematic codepaths? + +## The Test Pyramid for Agents + +- **Unit tests (foundation):** Fast, focused, run constantly. Agent-generated with human review. +- **Integration tests (middle):** Verify components work together. Human-guided generation. +- **E2E tests (top):** Verify full user flows. Fewer but critical. Often still human-written. +- **Contract tests (boundaries):** Verify API contracts. Especially important when agents modify interfaces. + +## Resources + +### Essential + +- [Your job is to deliver code you have proven to work](https://simonwillison.net/2025/Dec/18/code-proven-to-work/) - Standards for reviewing AI-assisted code +- [Agent Readiness – Eno Reyes, Factory AI](https://www.youtube.com/watch?v=ShuJ_CN6zr4) - How testing infrastructure affects agent reliability diff --git a/src/content/docs/ru/use-cases/deployment-operations.md b/src/content/docs/ru/use-cases/deployment-operations.md new file mode 100644 index 0000000..e16745f --- /dev/null +++ b/src/content/docs/ru/use-cases/deployment-operations.md @@ -0,0 +1,137 @@ +--- +title: Deployment & Operations +description: CI/CD, monitoring, and maintenance with agent assistance +sidebar: + order: 4 +--- + +CI/CD pipelines are configuration-heavy and well-suited for agents. Monitoring and maintenance are ongoing concerns where agents help with setup, incident response, and routine tasks. + +## CI/CD & Deployment + +### Where agents help + +**Pipeline configuration:** GitHub Actions, GitLab CI, Jenkins, CircleCI. Agents know common patterns and adapt to your stack. + +**Infrastructure as Code:** Terraform, CloudFormation, Pulumi—generate resources, modify existing infrastructure, create reusable modules. + +**Deployment automation:** Dockerfiles, Kubernetes manifests, Helm charts, deploy scripts, rollback procedures. + +**Environment configuration:** Environment variables, secret management, configuration files. + +### What to watch for + +**Security** — CI/CD is security-critical. Agent-generated pipelines may expose secrets in logs, use overly permissive permissions, or skip security scanning. Always security-review CI/CD changes. + +**Vendor quirks** — Each CI system has differences. Test generated pipelines thoroughly. + +**Stateful resources** — Infrastructure changes can cause deletion, downtime, cost surprises, or data loss. Use plan/apply patterns. + +### Prompt patterns + +**Pipeline generation:** + +``` +Create a GitHub Actions workflow for a [language/framework] project. + +Requirements: +- Run tests on PR +- Deploy to [environment] on merge to main +- Use [specific services/tools] + +Follow security best practices. +``` + +**Infrastructure:** + +``` +Generate Terraform for [resource type] with: +- [Specific requirements] +- [Constraints] + +Follow the patterns in [existing file/module]. +``` + +**Dockerfile:** + +``` +Create a Dockerfile for [application type]. + +Requirements: +- Multi-stage build +- Minimal final image +- Run as non-root +- [Other requirements] +``` + +## Monitoring & Maintenance + +### Monitoring setup + +**Alert configuration:** Prometheus rules, CloudWatch alarms, Datadog monitors. Agents understand common patterns for what to monitor. + +**Dashboard creation:** Grafana dashboards, Kibana visualizations. Describe what you want to see; get a starting configuration. + +**Log aggregation:** Parsing rules, search queries, anomaly detection. + +### Incident response + +**Root cause analysis:** "Here's the error and recent changes. What could cause this? What should I check?" + +**Debugging assistance:** Analyze logs, interpret stack traces, trace request flows, identify error patterns. + +**Post-mortem drafting:** "Help me write a post-mortem for [incident]. Include: summary, timeline, root cause, impact, remediation, lessons learned." + +### Maintenance tasks + +- **Dependency updates** — Analyze versions, identify breaking changes, generate update PRs +- **Technical debt cleanup** — Identify improvement patterns, generate refactoring plans +- **Performance optimization** — Analyze issues, suggest approaches, generate benchmarks +- **Security maintenance** — Vulnerability remediation, patch application, configuration hardening + +### What to watch for + +- **Alert fatigue** — Generated alerts may be too sensitive or poorly calibrated. Tune based on real experience. +- **Dashboard overload** — More dashboards isn't better. Ask: What decision does each panel inform? +- **Maintenance scope creep** — Bound tasks to the actual problem being solved. + +### Prompt patterns + +**Alert rules:** + +``` +Create Prometheus alerting rules for a [service type]. + +Monitor: +- Error rate exceeding [threshold] +- Latency above [threshold] +- Resource utilization above [threshold] + +Include appropriate severity levels and annotations. +``` + +**Incident investigation:** + +``` +I'm seeing [error/symptom] in production. + +Relevant context: +- [Recent changes] +- [Error logs] +- [Metrics] + +What could cause this? What should I check first? +``` + +**Runbook:** + +``` +Create a runbook for handling [type of incident]. + +Include: +- Detection (how we know it's happening) +- Triage (how to assess severity) +- Mitigation (immediate actions) +- Resolution (full fix) +- Follow-up (post-incident) +``` diff --git a/src/content/docs/ru/use-cases/implementation.md b/src/content/docs/ru/use-cases/implementation.md new file mode 100644 index 0000000..f2178b5 --- /dev/null +++ b/src/content/docs/ru/use-cases/implementation.md @@ -0,0 +1,81 @@ +--- +title: Implementation +description: Writing code with agents—the core use case +sidebar: + order: 2 +--- + +Implementation is where most engineers first encounter agents. Success depends on approach, not just prompting. + +## High-value tasks + +**Boilerplate generation** — CRUD operations, API scaffolding, form components, DTOs, configs. Agents handle these quickly and reliably. This is where "10x" claims are almost true. + +**Feature implementation** — Best when requirements are clear, patterns exist in your codebase to follow, and scope is bounded (single PR, few files). + +**Bug fixes** — Clear bugs are excellent agent tasks. "User login fails with null pointer when email contains '+'" beats "fix the login flow." + +**Refactoring** — Mechanical refactoring is ideal: rename across codebase, extract function/class, convert patterns. Complex restructuring is harder. + +**Data transformations** — Migration scripts, format conversions, ETL logic. Well-defined inputs and outputs make these agent-friendly. + +## The workflow + +1. **Plan** — Know what files will change, the desired end state, and what should NOT change. + +2. **Set context** — Provide relevant code, existing patterns to follow, and constraints. + +3. **Generate** — For complex tasks, ask for the plan first: "Describe how you would implement [feature]. Don't write code yet." + +4. **Validate** — Does it work? Handle edges? Follow conventions? Have security issues? + +5. **Refine** — "This doesn't handle the case where..." or "Follow the pattern in [file] instead." + +## What slows you down + +- **Overcomplicated prompts** — Start simple, add detail as needed +- **Under-constrained asks** — "Build the feature" leaves too many decisions to the agent +- **Fighting the agent** — After 3+ reprompts without progress, re-think or do it yourself +- **Insufficient context** — Missing context leads to invalid output +- **Wrong tool** — Some code is faster to write manually + +## Prompt patterns + +**Feature implementation:** + +``` +Implement [feature] in [file/module]. + +Requirements: +- [Specific requirement 1] +- [Specific requirement 2] + +Follow the pattern used in [existing example]. +Don't modify [things to preserve]. +``` + +**Bug fix:** + +``` +Bug: [description] +Reproduction: [steps or code] +Expected: [behavior] +Actual: [behavior] + +Fix this in [file]. The root cause is [if known]. +``` + +**Refactor:** + +``` +Refactor [module/function] to [desired change]. + +Keep the public API unchanged. +Maintain all existing functionality. +[Additional constraints] +``` + +## Resources + +- [Embracing the parallel coding agent lifestyle](https://simonwillison.net/2025/Oct/5/parallel-coding-agents/) - Running multiple agents simultaneously +- [Code research projects with async coding agents](https://simonwillison.net/2025/Nov/6/async-code-research/) - Async research task patterns diff --git a/src/content/docs/ru/use-cases/planning-design.md b/src/content/docs/ru/use-cases/planning-design.md new file mode 100644 index 0000000..66adaf0 --- /dev/null +++ b/src/content/docs/ru/use-cases/planning-design.md @@ -0,0 +1,85 @@ +--- +title: Planning & Design +description: Using agents for requirements, architecture, and system design +sidebar: + order: 1 +--- + +Agents accelerate planning by exploring options, surfacing patterns, and drafting specifications—without replacing stakeholder judgment. + +## Requirements & Planning + +### Where agents help + +**Breaking down ambiguity** + +- "What questions should we answer before implementing [feature]?" +- "What edge cases should we consider for [requirement]?" +- "Break down [epic] into implementable user stories" + +**Research and exploration** + +- "What approaches exist for [problem]? Summarize pros and cons." +- "What are common pitfalls when implementing [feature type]?" + +Treat this as research assistance, not authoritative answers. + +**Specification drafting:** API contracts, data models, interface definitions, acceptance criteria. These drafts need human refinement, but they accelerate the starting point. + +**Estimation support:** "Based on this spec, what are the major implementation tasks?" Agents decompose work; estimation remains human judgment. + +### Where agents struggle + +- **Stakeholder intent** — They can't replace stakeholder conversations +- **Organizational context** — Team ownership, historical decisions, constraints +- **Prioritization** — They enumerate options, but can't tell you what matters most + +### Prompt patterns + +**User story refinement:** +"Given this requirement: [paste requirement]. Generate user stories in standard format (As a... I want... So that...). Include acceptance criteria for each." + +**Risk identification:** +"We're planning to implement [feature]. What technical risks should we consider? What could go wrong?" + +## Architecture & Design + +### What agents offer + +**Broad pattern knowledge:** Common approaches for your problem type, pattern variations and tradeoffs, anti-patterns to avoid. Doesn't replace experience, but accelerates exploration. + +**Articulation:** Generate diagrams from descriptions, document decisions, create viewpoints for different audiences. + +**Challenge and critique:** "What could go wrong with this design?" "What am I not considering?" They surface considerations you might miss. + +### What agents can't do + +- **Make decisions** — They lack context about your team, constraints, and what you're optimizing for +- **Understand evolution** — They see a snapshot, not trajectory (why things are the way they are) +- **Navigate tradeoffs** — They enumerate options, not which tradeoff fits your situation + +### Prompt patterns + +**Design exploration:** +"I need to design [type of system]. What architectural patterns are commonly used? For each, what are the key tradeoffs?" + +**Design critique:** +"Here's my proposed architecture for [system]: [description]. What potential issues should I consider? What am I missing?" + +**ADR drafting:** +"Help me write an ADR for deciding to use [approach] instead of [alternative]. Context: [provide context]." + +**Diagram generation:** +"Create a [type] diagram showing [components and relationships]. Use [format, e.g., Mermaid syntax]." + +## Resources + +### Specifications & Planning + +- [Spec-Driven Development – Al Harris, Amazon Kiro](https://www.youtube.com/watch?v=HY_JyxAZsiE) - How specs enable reproducible AI delivery +- [The New Code – Sean Grove, OpenAI](https://www.youtube.com/watch?v=8rABwKRsec4) - Why specifications are becoming the fundamental unit of programming +- [Spec Kit](https://github.com/github/spec-kit) - GitHub's spec-driven development framework + +### Case studies + +- [AI in Product Development: Netflix, BMW, PepsiCo](https://www.virtasant.com/ai-today/ai-in-product-development-netflix-bmw) - Case studies of AI in product planning diff --git a/src/content/docs/ru/use-cases/quality-documentation.md b/src/content/docs/ru/use-cases/quality-documentation.md new file mode 100644 index 0000000..dac6be2 --- /dev/null +++ b/src/content/docs/ru/use-cases/quality-documentation.md @@ -0,0 +1,127 @@ +--- +title: Quality & Documentation +description: Testing, QA, and documentation with agent assistance +sidebar: + order: 3 +--- + +Testing and documentation are high-value agent use cases. Tests are self-validating—you immediately know if they work. Documentation is perpetually under-maintained—agents reduce the friction dramatically. + +## Testing + +### Where agents excel + +**Unit test generation** — Given a function, agents generate comprehensive tests: happy path, edge cases (null, empty, boundaries), error conditions. This is probably the single highest-ROI application for most teams. + +**Test case discovery** — "What test cases should I consider for this function? Focus on edge cases and error conditions." You'll often find cases you hadn't considered. + +**Mock and fixture generation** — Test data structures, mock implementations, factory functions. Tedious setup is perfect for agents. + +**Regression tests** — "Create a test that would have caught this bug: [describe bug]" + +### What to watch for + +- **Tests that pass for wrong reasons** — Tests that mock away the thing being tested, or have assertions that always pass +- **Hallucinated assertions** — Agents may assert behavior that doesn't match reality +- **Copy-paste tests** — Similar tests that don't add meaningful coverage + +Always verify tests can fail when they should. + +### Test-first workflow + +1. **Write or generate tests first:** "Given this requirement [describe], write tests that would verify correct implementation." +2. **Review and refine:** Ensure tests capture what you actually want. +3. **Generate implementation:** "Here are the tests. Write code that makes them pass." +4. **Verify everything:** Run tests, review implementation, check for gaps. + +This produces better results than implementation-first because tests define the contract. + +### Prompt patterns + +**Unit tests:** + +``` +Write unit tests for this function: +[paste function] + +Cover: +- Normal operation +- Edge cases (empty input, null, boundaries) +- Error conditions + +Use [test framework]. Follow conventions in [example file]. +``` + +**Regression test:** + +``` +Bug fixed: [description] +Root cause: [explanation] +Fix: [summary] + +Write a test that would catch this bug if it returns. +``` + +## Documentation + +### Types and approaches + +**Code documentation:** Inline comments (explain the _why_), function/method docs, class/module docs. Agents excel here because they read code and infer what needs documenting. + +**API documentation:** Endpoints, SDKs, integration guides. Generate from code, OpenAPI specs, or examples. + +**Architecture documentation:** System overviews, decision records, diagrams. More human guidance needed, but agents help with generation. + +### What to watch for + +- **Hallucinated features** — APIs that don't exist, parameters that don't work. Verify all claims against actual code. +- **Missing context** — Why decisions were made, gotchas, performance considerations. Add these manually—they're often most valuable. +- **Staleness risk** — Easy to generate ≠ easy to maintain. Build update processes, not just generation. + +### Prompt patterns + +**README bootstrap:** + +``` +Create a README for this project. + +Project: [describe project] +Tech stack: [list technologies] +Target audience: [who will use this] + +Include: installation, quick start, basic usage, contributing. +``` + +**API documentation:** + +``` +Generate API documentation for this endpoint: + +[paste endpoint code or OpenAPI spec] + +Include: description, parameters, request/response examples, error codes. +Format as Markdown. +``` + +**ADR:** + +``` +Help me write an ADR for choosing [option]. + +Context: [describe situation] +Decision: [what we decided] +Consequences: [what this means] + +Include alternatives considered. +``` + +## Resources + +### Testing + +- [The 3 Pillars of Autonomy – Michele Catasta, Replit](https://www.youtube.com/watch?v=MLhAA9yguwM) - Automatic testing as foundation for agent autonomy + +### Documentation + +- [AGENTS.md](https://agents.md/) - The emerging standard for agent-readable project documentation +- [The New Code – Sean Grove, OpenAI](https://www.youtube.com/watch?v=8rABwKRsec4) - Specs as source of truth compiling to documentation diff --git a/src/content/i18n/ru.json b/src/content/i18n/ru.json new file mode 100644 index 0000000..7f28c63 --- /dev/null +++ b/src/content/i18n/ru.json @@ -0,0 +1,30 @@ +{ + "skipLink.label": "Перейти к содержимому", + "search.label": "Поиск", + "search.ctrlKey": "Ctrl", + "search.cancelLabel": "Отмена", + "search.devWarning": "Поиск доступен только в production сборках. Попробуйте собрать и просмотреть сайт локально.", + "themeSelect.accessibleLabel": "Выбрать тему", + "themeSelect.dark": "Тёмная", + "themeSelect.light": "Светлая", + "themeSelect.auto": "Авто", + "languageSelect.accessibleLabel": "Выбрать язык", + "menuButton.accessibleLabel": "Меню", + "sidebarNav.accessibleLabel": "Главная", + "tableOfContents.onThisPage": "На этой странице", + "tableOfContents.overview": "Обзор", + "i18n.untranslatedContent": "Это содержимое пока недоступно на вашем языке.", + "page.editLink": "Редактировать страницу", + "page.lastUpdated": "Последнее обновление:", + "page.previousLink": "Предыдущая", + "page.nextLink": "Следующая", + "page.draft": "Это черновик и не будет включено в production сборку.", + "404.text": "Страница не найдена. Проверьте URL или попробуйте воспользоваться поиском.", + "aside.note": "Примечание", + "aside.tip": "Подсказка", + "aside.caution": "Внимание", + "aside.danger": "Опасность", + "fileTree.directory": "Директория", + "builtWithStarlight.label": "Создано с Starlight", + "heading.anchorLabel": "Раздел «{{title}}»" +} From d83a07c159fbeb78ae77f3e74aff7fbc8aa183da Mon Sep 17 00:00:00 2001 From: "Shadow (gastown)" Date: Sat, 16 May 2026 20:16:12 +0000 Subject: [PATCH 4/8] Add Russian homepage with translated content (src/content/docs/ru/index.md) --- src/content/docs/ru/index.md | 100 +++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 src/content/docs/ru/index.md diff --git a/src/content/docs/ru/index.md b/src/content/docs/ru/index.md new file mode 100644 index 0000000..e4fbf32 --- /dev/null +++ b/src/content/docs/ru/index.md @@ -0,0 +1,100 @@ +--- +title: Агентная инженерия для людей +description: Реальные руководства и ресурсы для изучения того, как работает программная инженерия и лидерство в пост-ИИ мире. +template: splash +hero: + tagline: Реальные руководства и ресурсы для изучения того, как работает программная инженерия и лидерство в пост-ИИ мире. + image: + file: ../../assets/human-ai.png + actions: + - text: Начать обучение + link: /introduction/what-is-agentic-engineering/ + icon: right-arrow + - text: Присоединиться к сообществу + link: /community/ + icon: discord + variant: minimal +--- + +Автономные агенты создают całe приложения от одного запроса, [вносят вклад в проекты с открытым исходным кодом](https://github.com/matplotlib/matplotlib/pull/31132), и даже [делают бронирования в ресторанах](https://youtu.be/0iTb3a6eqKg) от имени людей. +Это прекрасно для хобби-проектов и scrappy стартапов, но для многих инженерных команд интеграция этих инструментов в реальную производственную среду кажется недостижимой. + +Если вы чувствуете, что отстаёте или что обещания «агентной инженерии» unrealistic для сложных, высокорисковых legacy систем, этот ресурс для вас. +Агентная инженерия для людей — это начало прагматичной, свободной от хайпа карты для управления этим переходом — сообщество, где реальные инженеры могут делиться тем, что сработало для них. + +[Выберите свой путь](/#choose-your-path), чтобы начать reclaiming ваше время от утомительных задач и сосредоточиться на высокозначимых проблемах, или [внесите вклад](/community/contributing/), чтобы помочь сделать этот документ живым отражением того, что действительно происходит в этой области. + +## Выберите свой путь + +Выберите трек, соответствующий вашей роли. Каждый трек разработан для того, где вы находитесь сегодня. + +### Для инженеров +Эффективное формулирование запросов, декомпозиция задач, валидация вывода агента и создание AI-совместимых кодовых баз. + +[Начать здесь →](/engineers/getting-started/) + +### Для тимлидов +Интеграция агентов в рабочие процессы, политики код-ревью, сдвиг тестирования влево и управление пробелами в навыках. + +[Начать здесь →](/team-leads/adopting-agentic-tools/) + +### Для руководителей +Стратегическое видение, рамки ROI, преграды при внедрении и подготовка к автономным агентам. + +[Начать здесь →](/executives/strategic-vision/) + +--- + +## Что внутри + +### Основы + +- [Что такое агентная инженерия?](/introduction/what-is-agentic-engineering/) +- [Как работают агенты](/introduction/how-agents-work/) +- [Работа с агентами](/introduction/working-with-agents/) +- [Тенденции и закономерности](/introduction/trends-patterns/) + +### Индивидуальная практика + +- [Начало работы](/engineers/getting-started/) +- [Декомпозиция задач](/engineers/task-decomposition/) +- [Лучшие практики](/engineers/best-practices/) + +### Интеграция в команду + +- [Внедрение агентных инструментов](/team-leads/adopting-agentic-tools/) +- [Измерение влияния](/team-leads/measuring-impact/) +- [Обеспечение качества](/team-leads/quality-assurance/) + +### Стратегия + +- [Стратегическое видение](/executives/strategic-vision/) +- [Фреймворки ROI](/executives/roi-frameworks/) +- [Плейбук внедрения](/executives/adoption-playbook/) +- [Безопасность и соблюдение норм](/executives/security-compliance/) + +### По этапам + +- [Планирование и дизайн](/use-cases/planning-design/) +- [Реализация](/use-cases/implementation/) +- [Развертывание и эксплуатация](/use-cases/deployment-operations/) +- [Качество и документация](/use-cases/quality-documentation/) + +### Управление и риски + +- [Проверка безопасности](/governance/security-review/) +- [Ответственность](/governance/accountability/) +- [Контроль качества](/governance/quality-gates/) + +### Приложения + +- [Глоссарий](/appendices/glossary/) +- [Рекомендуемая литература](/appendices/reading-list/) +- [Шаблоны запросов](/appendices/prompt-templates/) + +### Сообщество + +Эта инструкция с открытым исходным кодом и управляется сообществом. Мы все вместе разбираемся в агентной инженерии — ваш опыт важен. + +[Присоединиться к дискуссии](https://kilo.love/discord) +[Как внести вклад](/community/contributing/) \ No newline at end of file From 96d948f7e534507360e27b7e1013a00ef5dada16 Mon Sep 17 00:00:00 2001 From: "kilo-code-bot[bot]" <240665456+kilo-code-bot[bot]@users.noreply.github.com> Date: Sat, 16 May 2026 20:20:19 +0000 Subject: [PATCH 5/8] Add Russian translations for README.md and CONTRIBUTING.md (#4) Co-authored-by: Birch (gastown) --- CONTRIBUTING.ru.md | 168 +++++++++++++++++++++++++++++++++++++++++++++ README.ru.md | 89 ++++++++++++++++++++++++ 2 files changed, 257 insertions(+) create mode 100644 CONTRIBUTING.ru.md create mode 100644 README.ru.md diff --git a/CONTRIBUTING.ru.md b/CONTRIBUTING.ru.md new file mode 100644 index 0000000..842718f --- /dev/null +++ b/CONTRIBUTING.ru.md @@ -0,0 +1,168 @@ +# Вклад в проект «Агентная инженерия для людей» + +Прежде всего — спасибо, что вы здесь. Это руководство существует благодаря людям, которые делятся своим опытом. Каждый вклад делает этот ресурс лучше для следующего человека, который пытается разобраться в работе с ИИ-агентами. + +## Коротко о главном + +1. **Мелкие исправления** (опечатки, сломанные ссылки, уточнения) — Просто отправьте PR +2. **Новый контент или крупные изменения** — Сначала откройте Issue, чтобы обсудить +3. **Не уверены?** — Спросите в [Discord](https://kilo.love/discord) или создайте обсуждение + +## Что мы ищем + +### Ценные вклады + +- **Опыт из практики** — Что реально сработало (или нет), когда вы это пробовали +- **Практические примеры** — Фрагменты кода, промпты, рабочие процессы, которые можно использовать +- **Обновлённая информация** — Область развивается быстро; помогите не отставать +- **Новые перспективы** — Разные инструменты, языки, размеры команд, отрасли +- **Более ясные объяснения** — Если вас смутило что-то, это, вероятно, смущает и других + +### Контент, который мы, скорее всего, не примем + +- **Маркетинговые материалы** — Никаких рекламных постов под видом руководств +- **Непроверенные утверждения** — «Продуктивность выросла в 10 раз» нуждаются в подтверждении +- **Сгенерированный ИИ контент** — Иронично, да, но мы ценим человеческое видение +- **Дублирующий контент** — Убедитесь, что мы уже не освещаем это где-то + +## Как внести вклад + +### Изменения в документации + +1. Сделайте форк репозитория +2. Создайте ветку (`git checkout -b fix/opечатка-в-начале-работы`) +3. Внесите изменения +4. Запустите `bun dev` для локального предпросмотра +5. Зафиксируйте с понятным сообщением +6. Отправьте PR + +### Новые страницы или разделы + +1. **Сначала откройте Issue** — Опишите, что вы хотите добавить и почему +2. Дождитесь обратной связи (обычно в течение нескольких дней) +3. После утверждения следуйте шагам выше + +### Стиль написания + +Соблюдайте существующий тон: + +- **Прямолинейный и практичный** — Переходите к делу +- **Обращение на «ты»** — «Ты», а не «разработчик» +- **Короткие абзацы** — Максимум 3–5 предложений +- **Реальные примеры** — Показывайте, а не просто рассказывайте +- **Без лишнего** — Каждое предложение должно быть на своём месте + +Смотрите существующие страницы как примеры. При сомнениях читайте [Начало работы](/engineers/getting-started/) — это тот стиль, который мы используем. + +### Структура файлов + +``` +src/content/docs/ +├── introduction/ # Основные концепции +├── engineers/ # Контент для индивидуальных участников +├── team-leads/ # Контент по управлению командой +├── executives/ # Стратегический контент +├── use-cases/ # Пошаговые руководства +├── governance/ # Риски и соответствие требованиям +├── appendices/ # Справочные материалы +└── community/ # Участие, информация о сообществе +``` + +### Фронтматтер + +Каждая страница должна содержать фронтматтер: + +```yaml +--- +title: Заголовок страницы +description: Описание в одном предложении для SEO и превью +sidebar: + order: 1 # Позиция в боковой панели (необязательно) +--- +``` + +## Трекинг задач + +Мы используем [GitHub Issues](https://github.com/Kilo-Org/agentic-path/issues) для отслеживания работы. Прежде чем начать: + +1. **Проверьте существующие Issues** — Возможно, кто-то уже работает над этим +2. **Откройте Issue для крупных изменений** — Давайте обсудим, прежде чем вы потратите время +3. **Закомментируйте Issue, если вы берёте его в работу** — Чтобы другие знали + +Смотрите [открытые Issues](https://github.com/Kilo-Org/agentic-path/issues) — можно найти что-то интересное, или создайте новое, если заметили пробел. + +## Процесс отправки Pull Request + +1. **Ограничьтесь одним логическим изменением в одном PR** +2. **Напишите понятное описание** — Что изменилось и почему +3. **Ссылайтесь на связанные Issues** — Используйте «Fixes #123» или «Relates to #456» +4. **Будьте терпеливы** — Мы рецензируем в течение недели, обычно быстрее + +### Что мы проверяем + +- Соответствует ли ваш вариант стилю и тону? +- Информация точная? +- Добавляет ли ценность для читателей? +- Проходит ли сборка? + +## Локальная разработка + +```bash +# Клонируйте свой форк +git clone https://github.com/YOUR-USERNAME/agentic-path.git +cd agentic-path + +# Установите зависимости +bun install + +# Запустите сервер для разработки +bun dev + +# Соберите, чтобы проверить на ошибки +bun build +``` + +Сайт по умолчанию запускается на `http://localhost:4321`. + +## Принципы взаимодействия в сообществе + +### Уважайте друг друга + +- Предполагайте добрые намерения +- Конструктивное несогласие приветствуется +- Личные нападки недопустимы +- Помогайте новичкам чувствовать себя уютно + +### При рецензировании работы других + +- Будьте конструктивными, а не критикующими +- Предлагайте улучшения, а не просто указывайте на проблемы +- Помните, что с другой стороны тоже человек + +### Получая обратную связь + +- Не воспринимайте всерьёз +- Задавайте уточняющие вопросы при необходимости +- Не соглашаться — нормально, можно обсудить + +## Признание участников + +Участники признаются несколькими способами: + +- История Git (ваши коммиты остаются навсегда) +- Страница контрибьюторов на GitHub +- Упоминания в заметках о релизе за значительный вклад + +## Вопросы? + +- **Быстрые вопросы** — [Discord](https://kilo.love/discord) +- **Более развёрнутые обсуждения** — [GitHub Discussions](https://github.com/Kilo-Org/agentic-path/discussions) +- **Отчёты о багах** — [GitHub Issues](https://github.com/Kilo-Org/agentic-path/issues) + +## Лицензия + +Внося вклад в проект, вы соглашаетесь, что ваш материал распространяется под лицензией MIT. + +--- + +Спасибо снова за участие. Каждое улучшение помогает кому-то работать с ИИ-агентами эффективнее. Это очень круто. diff --git a/README.ru.md b/README.ru.md new file mode 100644 index 0000000..b9b2a66 --- /dev/null +++ b/README.ru.md @@ -0,0 +1,89 @@ +# Агентная инженерия для людей + +Практические руководства и ресурсы для понимания того, как работает программная инженерия и управление командой в пост-ИИ мире. + +🌐 **Онлайн-версия:** [path.kilo.ai](https://path.kilo.ai) + +## Что это такое? + +Это исчерпывающее руководство по агентной инженерии — практике эффективной работы с ИИ-агентами по программированию. Независимо от того, являетесь ли вы инженером, который осваивает эффективное взаимодействие с ИИ, тимлидом, внедряющим агентов в рабочие процессы, или руководителем, строящим стратегию внедрения — здесь найдётся подходящий путь для вас. + +**Это общественный проект.** Мы создаём его вместе, потому что область развивается быстро, и ни один взгляд не может охватить всё. Ваш опыт важен — независимо от того, пользуетесь ли вы ИИ-инструментами много лет или только начали на прошлой неделе. + +## Содержание + +- **Введение** — Что такое агентная инженерия, как работают агенты и возникающие тенденции +- **Для инженеров** — Начало работы, декомпозиция задач и лучшие практики +- **Для тимлидов** — Внедрение инструментов, измерение эффекта и обеспечение качества +- **Для руководителей** — Стратегическое видение, фреймворки ROI и соответствие требованиям безопасности +- **Прецеденты использования** — Планирование, реализация, развёртывание и документирование +- **Управление и риски** — Проверка безопасности, ответственность и контроль качества +- **Приложения** — Глоссарий, рекомендуемая литература и шаблоны запросов + +## Технологический стек + +Создано на [Astro](https://astro.build) и [Starlight](https://starlight.astro.build), стилизация — [Catppuccin](https://github.com/catppuccin/starlight). + +## Разработка + +```bash +# Установка зависимостей +bun install + +# Запуск локального сервера +bun dev + +# Сборка для продакшна +bun build + +# Предпросмотр продакшен-сборки +bun preview +``` + +## Как внести вклад + +Мы с радостью примем вашу помощь по улучшению этого ресурса. Есть много способов внести вклад: + +### Быстрые вклады + +- **Нашли опечатку или сломанную ссылку?** Отправьте PR напрямую — отдельный запрос не нужен +- **Есть ресурс, который стоит поделиться?** Добавьте его в соответствующий раздел «Ресурсы» +- **Заметили устаревшую информацию?** Сообщите нам или исправьте сами + +### Более крупные вклады + +- **Новый контент** — Знаете область, которую мы не затронули? Мы хотим это видеть +- **Практические примеры** — Кейсы, истории реального опыта и выводы бесценны +- **Переводы** — Помогите сделать этот ресурс доступным для большего числа людей +- **Улучшение инструментов** — Лучший поиск, навигация или доступность + +### Как внести вклад + +1. **Проверьте открытые Issues** — Возможно, кто-то уже работает над этим +2. **Сначала создайте Issue** для крупных изменений — давайте обсудим, прежде чем вы потратите время +3. **Сделайте форк и отправьте PR** — Стандартный GitHub-поток +4. **Делайте акцент на практичность** — Мы ценим реальный опыт выше теории + +Детальные рекомендации смотрите в [CONTRIBUTING.md](CONTRIBUTING.birch.ru.md). + +## Сообщество + +Это не просто документация — это разговор. Присоединяйтесь: + +- **[Discord](https://kilo.love/discord)** — Задавайте вопросы, делитесь успехами, обсуждайте рабочие решения +- **[GitHub Discussions](https://github.com/Kilo-Org/agentic-path/discussions)** — Более развернутые обсуждения и предложения +- **[GitHub Issues](https://github.com/Kilo-Org/agentic-path/issues)** — Отчёты о багах и запросы функционала + +### Кодекс поведения + +Уважайте друг друга. Мы все вместе осваиваем новую область. Конструктивное несогласие приветствуется; личные нападки — нет. + +## Лицензия + +[Apache 2.0](LICENSE) — Используйте, расширяйте, делитесь. + +## Ссылки + +- [Discord](https://kilo.love/discord) +- [GitHub](https://github.com/Kilo-Org/agentic-path) +- [Kilo Code](https://kilo.ai) — Команда за этим руководством From f138a12b02257546bbd421ad98cc818dbb97bbc2 Mon Sep 17 00:00:00 2001 From: "Shadow (gastown)" Date: Sat, 16 May 2026 20:24:43 +0000 Subject: [PATCH 6/8] WIP: container eviction save From 85eba7263fc37ba93ccfbb75a923c56ae0a73963 Mon Sep 17 00:00:00 2001 From: "Maple (gastown)" Date: Sat, 16 May 2026 21:09:48 +0000 Subject: [PATCH 7/8] Translate UI components to Russian using i18n: Footer, ContributeBanner, ShareButtons --- astro.config.mjs | 54 ++++++++++++++++++--------- src/components/ContributeBanner.astro | 16 ++++---- src/components/Footer.astro | 14 +++---- src/components/ShareButtons.astro | 18 ++++----- 4 files changed, 60 insertions(+), 42 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index d1f225a..f2cd933 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -272,24 +272,42 @@ export default defineConfig({ light: { flavor: "latte", accent: "peach" }, }), ], - locales: { - en: { - label: "English", - title: "Agentic Engineering", - editLink: { - baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/", - }, - sidebar: enSidebar, - }, - ru: { - label: "Русский", - title: "Агентная инженерия", - editLink: { - baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/ru/", - }, - sidebar: ruSidebar, - }, - }, + locales: { + en: { + label: "English", + title: "Agentic Engineering", + editLink: { + baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/", + }, + sidebar: enSidebar, + }, + ru: { + label: "Русский", + title: "Агентная инженерия", + editLink: { + baseUrl: "https://github.com/Kilo-Org/agentic-path/edit/main/ru/", + }, + sidebar: ruSidebar, + // Translations for UI components + translations: { + footer: { + communityDriven: "Это руководство создано сообществом.", + contribute: "Внести вклад", + joinConversation: "присоединиться к дискуссии" + }, + contributeBanner: { + helpUsGrow: "Помогите нам расти!", + foundResource: "Нашли отличный ресурс? Поделитесь им с сообществом.", + contributeOnGitHub: "Внести вклад на GitHub →", + dismissBanner: "Закрыть баннер" + }, + shareButtons: { + shareThisPage: "Поделитесь этой страницей", + description: "Узнайте об агентной инженерии" + } + } + }, + }, }), sitemap(), ], diff --git a/src/components/ContributeBanner.astro b/src/components/ContributeBanner.astro index 41431af..038b20f 100644 --- a/src/components/ContributeBanner.astro +++ b/src/components/ContributeBanner.astro @@ -4,14 +4,14 @@ ---
- - + +