DEV Community: Anton B

AI Assistants — The Wiki-First Approach

Anton B — Wed, 15 Apr 2026 08:00:29 +0000

In modern projects, the codebase grows exponentially, and AI assistants have become an integral part of the development workflow. However, without a single source of truth, every developer (and every AI agent) is forced to learn the project from scratch, wasting context window limits, time, and resources. The wiki-first approach solves this problem by turning documentation into a living, automatically maintained knowledge center that dictates how both humans and AI operate.

📌 Note: All structural examples, file names (QWEN.md, .qwen/skills/), and workflows in this article are provided for the QWEN ecosystem. The methodology itself is universal and can easily be adapted to any AI agent capable of working with Markdown instructions.

🔍 What is Wiki-First?

Wiki-first is a methodology where, before any work with the code (writing features, reviewing, refactoring, making architectural decisions), the developer or AI agent must first study the project's wiki documentation (docs/wiki/).

Key principle:

Wiki = overview, Code = details

The wiki stores condensed, structured knowledge: system architecture, accepted patterns, service dependencies, naming conventions, and DI rules. Specific method signatures, SQL queries, or test assertions are looked up directly in the code if the wiki does not cover the task.

🚀 Benefits of the Approach

Aspect	Without Wiki-First	With Wiki-First
Project Onboarding	Everyone learns the code from scratch	Ready-made overview in 5 minutes
Knowledge Storage	Knowledge stays in developers' heads	Knowledge is centralized in the wiki, accessible to all
Onboarding	Newcomers spend days deciphering the code	Newcomers read the wiki → hours instead of days
AI Agent Workflow	Wastes context scanning thousands of lines	Reads concise wiki pages, saving tokens and time
Documentation Freshness	Wiki falls behind the code, quickly becomes outdated	Wiki is automatically updated after every change
Standard Compliance	Developers violate patterns out of ignorance	AI and humans follow unified rules from the wiki

🛠 How to Set Up Wiki-First in Your Project

For quick and correct setup, use the WIKI_FIRST_TEMPLATE.en.md template. It is designed for execution by an AI agent, which will automatically create the entire knowledge infrastructure and skills.

Step 1. Prepare Parameters

Copy WIKI_FIRST_TEMPLATE.en.md to the root of your repository.
Open the file and fill the INPUT DATA table with real values:

Parameter	Example
`project_name`	`WebArchiveBackend`
`project_description`	`Backend API for storing and indexing web pages`
`tech_stack`	`C#, .NET 8, gRPC, PostgreSQL, Dapper`
`docs_path`	`docs/`
`wiki_path`	`docs/wiki/`
`skills_path`	`.qwen/skills/`
`source_dirs`	`src/, tests/`

Step 2. Launch the AI Agent

Pass the filled file to your AI assistant with the following prompt:

"Execute the instructions from WIKI_FIRST_TEMPLATE.en.md strictly step-by-step. Create the wiki structure, AI skills, and the main rules file. Do not modify the existing project code. After creating the structure, perform the Initial Ingest (Step 6)."

The agent will automatically:

Create the docs/wiki/ directory and three base files:
- index.md — catalog of all wiki pages
- log.md — change log (append-only)
- Wiki Format.md — guide to page formatting
Generate three specialized AI skills in .qwen/skills/:
- wiki-workflow — knowledge management (ingest, query, lint, post-change lint)
- code-contributor — writing and modifying code according to standards
- code-architecture — architectural review (SOLID, DI, layered architecture)
Create QWEN.md in the project root with a strict wiki-first rule and source hierarchy: docs/wiki/ > Project code.

Step 3. Initial Project Analysis (Initial Ingest)

After creating the structure, the agent will execute Step 6 from the template:

Scans the source code directories (source_dirs).
Generates initial wiki pages: Architecture.md, Components.md, Database.md, Code Patterns.md, Testing.md.
Updates index.md, adding new pages to the catalog.
Adds an entry to log.md about the initial knowledge load.
⚠️ Important: The wiki contains only overviews and relative links to files. Copying code from .cs, .proto, or .sql files is prohibited.

Step 4. Verify Installation

After the agent finishes, verify the result using the checklist:

[ ] QWEN.md contains the wiki-first rule and source priority
[ ] docs/wiki/ contains index.md, log.md, Wiki Format.md
[ ] .qwen/skills/ contains 3 SKILL.md files
[ ] All skills explicitly state: wiki > code
[ ] Base wiki pages for architecture, components, and patterns are generated
[ ] index.md contains links to all created pages
[ ] log.md contains an entry about the first ingest with date and description

🔄 How to Work with Wiki-First After Setup

Role	Rule
Developer	Before a task → open `docs/wiki/index.md`. After committing → update wiki + add an entry to `log.md`.
AI Agent	Any request → wiki first. After code changes → post-change lint. Missing details → read code.
Code Review	If a PR didn't update the wiki → request changes. Wiki must not diverge from the code.

Typical AI agent workflow:

Wiki-first → reads index.md → finds relevant pages
Query/Ingest → clarifies details in code if needed
Code → writes feature/fix according to wiki patterns
Post-Change Lint → updates wiki and log.md
Verify → checks links, frontmatter, code alignment

🔄 Wiki Lifecycle: Maintenance, Consistency, and Skill Evolution

Setting up wiki-first is not a one-time configuration, but the launch of a living process. Documentation left unattended quickly becomes a "knowledge graveyard." To ensure the approach delivers long-term value, the wiki must be continuously updated, and the AI agent must act as the primary guarantor of its consistency and completeness.

🤖 Agent as the Guardian of Integrity

After the initial setup, responsibility for wiki freshness falls on the AI agent. With every code change, the agent must automatically run a post-change lint: check if existing pages contradict the new implementation, update descriptions of affected components, and log changes in log.md.

Require explicit synchronization confirmation from the agent. If a commit affects architecture, configuration, or adds new modules, the agent must not only fix the code but also update the wiki. This turns documentation from an "extra burden" into an integral part of the development cycle. Without this step, the wiki will quickly drift from the code, and the wiki > code rule will lose its meaning.

📖 Documenting Complex Scenarios

The true power of wiki-first emerges when not only static descriptions but also project-specific workflows are added to the knowledge base.

For example, adding a new configuration parameter in your project might require changes in five different places: from appsettings.json to DI container objects, DTO models, and DB migrations. Instead of explaining this to the agent from scratch every time, document this scenario once as a separate wiki page or a section in Code Patterns.md.

Once a complex scenario is documented in the wiki, the agent begins executing it confidently, without hallucinations or missed steps. When asked "Add parameter X", the agent:

Finds the instruction in the wiki via index.md.
Strictly follows the described sequence of changes.
Automatically updates the wiki if the scenario needs adaptation to new realities.

The more "routine" and "easily forgotten" scenarios you formalize in the wiki, the less time is spent micromanaging the agent, and the higher the stability of the results.

🧠 Model-Specific Nature of Wiki

Different LLM models structure thoughts, choose priorities, and formulate instructions differently. This is not a bug, but a feature. When an agent itself generates the wiki during initial analysis (Initial Ingest) or subsequent updates, the documentation naturally "adapts" to its internal logic, tokenization, and attention patterns.

A model will follow a wiki it generated or curated itself much more accurately and confidently than documentation written by another model or a human "for themselves." Therefore, do not strive for perfect "human" stylistics in the early stages. The main thing is that the structure is unambiguous, links work, and the update logic is maintained. Over time, you will notice that the wiki becomes the "native language" of your agent: it finds context faster, hallucinates less, and executes complex tasks more precisely.

🛠 Evolution of Skills and Rules

The skills created during setup are not set in stone. As the project grows and experience with the agent accumulates, they must be adapted:

If the agent frequently misses a certain type of check, add the corresponding rule to code-architecture or wiki-workflow.
If new tech stacks or patterns emerge, expand code-contributor with examples and conventions.
If the wiki structure becomes too bulky, refactor index.md, introduce tags, or split monolithic pages into thematic blocks.

The QWEN.md and SKILL.md files themselves are part of the wiki ecosystem. They can and should be refactored to keep instructions precise, minimize context consumption, and match the current maturity stage of the project.

💡 Core Principle: Wiki is a Living Organism

The key idea of the approach is this: you cannot just create a wiki, you must continuously develop it.

Maintain freshness: every code change → wiki change + entry in log.md.
Enrich context: turn verbal agreements, bug trackers, and complex manual procedures into formalized wiki instructions.
Evolve the agent: adapt skills, clarify priorities, and refine prompts for real project tasks.

When the wiki becomes the single source of truth, and the agent acts as its active curator, the team gets a scalable knowledge system. It doesn't "wither" over time but gains strength: the more you invest in it, the faster, more accurate, and more confident the AI works, reducing time spent on onboarding, code reviews, and bug fixing.

💡 Conclusion

The wiki-first approach transforms documentation from an "artifact that gets forgotten" into an active development tool. AI agents operating under these rules save context, strictly adhere to architectural standards, and accelerate feature delivery.

Set up wiki-first once using WIKI_FIRST_TEMPLATE.en.md, integrate it into your CI/CD and onboarding processes, and you will get a scalable knowledge system that grows with your project rather than turning into legacy.

Shadow Logging via Events - Complete Decoupling of Business Logic and Logging in DI Environment

Anton B — Sun, 08 Feb 2026 09:51:27 +0000

Hello, colleagues!

I want to share an approach to logging that radically simplifies architecture and strengthens SOLID principles.

I've created a code example on GitHub to demonstrate how shadow decoupled logging works through C# events.

What is Decoupled Logging?

Decoupled logging is an architectural approach where business classes do not contain direct logger calls (like ILogger.LogInformation). Instead:

Business classes generate events.
Specialized logger classes handle the events.
Business classes know nothing about loggers.
Logging is configured centrally at the application level, without polluting domain logic.

Pros and Cons of Decoupled Logging

There are opinions both "for" and "against" decoupled logging.

Typical arguments "for":

SRP purity: The class focuses on business logic; logging is an external concern.
Testability: No ILogger mocks needed; classes work standalone.
Flexibility and scalability: One event can be handled in all required ways: logs, metrics, audit. Easy to change event handling logic and logging libraries.
Decoupling for libraries: Consumers of business logic classes decide themselves whether to log events and which ones. No hard dependencies.
Performance: Business class does not format data for logs. When implementing event handlers, use smart fast caching of incoming events with subsequent post-processing - it doesn't block business logic.

Critics' objections boil down to a simple thesis: don't complicate things if not really needed - "inject ILogger and don't worry." This opinion sounds reasonable; I agree with such criticism - if you have a simple application, don't complicate it.

Extracting Logging from the Class

The simplest way to separate business logic and logging is to write a Wrapper for the business class.

Decorator/wrapper for logging is convenient but imposes usage rules:

Client code must work through the wrapper.
Refactoring becomes more complex.
Duplication and inheritance issues arise.

This approach makes logging not "shadow" - consumers indirectly know about it.

Complete Separation

Complete separation of business logic and logging is possible only using two independent objects: business class and log handler.

Simple example:

class OrderServiceLogger
{
    public OrderServiceLogger(FileLogger logger, OrderService orderService)
    {
        orderService.OrderCreated += (s, e) => logger.LogInformation($"Order {e.OrderId} created.");
    }
}

var orderService = new OrderService();
var fileLogger = new FileLogger();
var orderServiceLogger = new OrderServiceLogger(fileLogger, orderService);
orderService.CreateOrder(...);

This approach is straightforward, but if the application uses a DI container, it requires adaptation.

Shadowing Logging

DI containers perform 2 important tasks:

Object factory
Object lifetime management

Object creation is simple: the DI container will return 2 ready objects, with the log handler receiving the business class instance and logger instance upon creation.

var services = new ServiceCollection();
services.AddScoped<FileLogger>();
services.AddScoped<OrderServiceLogger>();
services.AddScoped<OrderService>();
var serviceProvider = services.BuildServiceProvider();

var orderService = serviceProvider.GetRequiredService<OrderService>();
var orderServiceLogger = serviceProvider.GetRequiredService<OrderServiceLogger>();

The problem is managing the lifetime of the log handler OrderServiceLogger, i.e., explicitly storing a reference to the created object and synchronizing its lifetime with the business class OrderService instance.

If we do nothing else, we'll have to explicitly create a new OrderServiceLogger instance wherever we create an OrderService instance and ensure their lifetimes match - that's not the behavior we want.

What we need:

Use only business logic object instances in business logic, in our example OrderService.
Business logic should know nothing about objects performing other tasks in the application, in our example logging via OrderServiceLogger.
When creating a business logic object, the application must guarantee all implemented service functions for it - if OrderServiceLogger is implemented for OrderService, it must be created in time and handle events.
Correct service function operation includes optimal application resource management - the OrderServiceLogger instance must be removed from memory after the associated OrderService object is destroyed.

These requirements are easy to implement, even within a DI container. We've sorted object creation; now we need to implement lifetime synchronization using weak references.

We need to ensure the created OrderServiceLogger object lives no less than the OrderService instance and is removed when no longer needed.

For this, we need an application-level object that:

Stores references to both dependent objects.
Monitors their lifetimes.
Removes OrderServiceLogger as soon as OrderService is removed.

We can implement such a class ourselves, where there is a key object and dependent objects. The architecture of such a class is simple:

Key object(s) are stored as weak references, which do not prevent the object from being garbage collected.
Dependent objects are stored as strong references, which prevent the garbage collector from destroying them.
The state of key objects is periodically checked - if they are removed, dependent objects are also removed.

For the simple case, we can use the ConditionalWeakTable class from the System.Runtime.CompilerServices namespace, which already implements this logic.

Writing DI Logic

Let's implement an extension method for ServiceCollection and examine how it works.

public static class ServiceCollectionExtensions
{
    public static ServiceCollection AddScopedWithLogger<TService, TServiceInstance, TServiceLogger>(
        this ServiceCollection services)
        where TService : class
        where TServiceInstance : class, TService
        where TServiceLogger : class
    {
        // Register TServiceInstance.
        services.AddScoped<TServiceInstance>();
        // Register TServiceLogger.
        services.AddScoped<TServiceLogger>();
        // Register TService.
        services.AddScoped<TService>(sp =>
        {
            var instance = sp.GetRequiredService<TServiceInstance>();
            var logger = sp.GetRequiredService<TServiceLogger>();
            var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
            // Put instance and logger into ConditionalWeakTable.
            conditionalWeakTable.Add(instance, logger);

            return instance;
        });

        return services;
    }
}

The AddScopedWithLogger method does all the necessary work:

Registers all types in DI.
Implements the logic for creating and linking the business class and its event handler class.

Important - in the DI container, it is necessary to separate the logic for creating the business class object itself from the logic for creating the instance with all its shadow objects. For this, it is best to use business class contracts (interfaces).

public class OrderEventArgs : EventArgs
{
    public int OrderId { get; set; }
}

public interface IOrderService
{
    event EventHandler<OrderEventArgs> OrderCreated;
    void CreateOrder(int id, string customer);
}

Thus, the DI container will pass the OrderService instance to the OrderServiceLogger constructor.

In business logic, only contracts must be used, which is a recommended approach.

class OrderManager : IOrderManager
{
    public OrderManager(IOrderService orderService)
    {
        ...
    }
}

Correctly register all types in the container:

var services = new ServiceCollection();
services.AddScopedWithLogger<IOrderService, OrderService, OrderServiceLogger>();

Now, creating an object for its contract IOrderService will trigger the following code from the extension method:

// Register TService.
services.AddScoped<TService>(sp =>
{
    var instance = sp.GetRequiredService<TServiceInstance>();
    var logger = sp.GetRequiredService<TServiceLogger>();
    var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
    // Put instance and logger into ConditionalWeakTable.
    conditionalWeakTable.Add(instance, logger);

    return instance;
});

Here's the breakdown for the parameter combination IOrderService, OrderService, OrderServiceLogger:

services.AddScoped<IOrderService>(sp =>
{
    var instance = sp.GetRequiredService<OrderService>();
    var logger = sp.GetRequiredService<OrderServiceLogger>();
    var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
    // Put instance and logger into ConditionalWeakTable.
    conditionalWeakTable.Add(instance, logger);

    return instance;
});

As you can see, it's simple. OrderService and OrderServiceLogger objects are created with all dependencies, then both objects are saved in the ConditionalWeakTable<object, object>.

var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
// Put instance and logger into ConditionalWeakTable.
conditionalWeakTable.Add(instance, logger);

The ConditionalWeakTable<object, object> object itself must be registered in the DI container with a lifetime equal to or greater than OrderService and OrderServiceLogger.

I recommend using Scoped if the registered objects live no longer. Singleton is not necessary.

And the last piece of the puzzle - at the application level, create a ConditionalWeakTable<object, object> instance that lives no less than the objects stored in it.

Simplest example:

class Program
{
    private static void Main()
    {
        var services = new ServiceCollection();
        services.AddScoped<ConditionalWeakTable<object, object>>();

        // Registration of all types and other application service code
        ...
        ...

        // Instance of ConditionalWeakTable that holds references to shadow objects.
        var conditionalWeakTable = serviceProvider.GetRequiredService<ConditionalWeakTable<object, object>>();
        // Start application work.
        Run(...);
    }
}

Conclusion

Advantages of the approach as I see them:

Logger is automatically bound to a specific class instance.
Weak references guarantee operation without memory leaks.
Centralized subscription in the DI container.
Ability to flexibly extend the number of shadow services and manage them.
Strong SOLID with minimal compromises.

I recommend using it for serious projects where quality architecture provides a tangible advantage.