Guidance-Driven File Processing
Tell me your sorrows.
— Clifford D. Simak, "Crying Jag"
Introduction
When a developer encounters repetitive tasks, they write code to automate them. However, some tasks are not so easily programmed, so instructions for such work are usually described in natural language on relevant resources and executed manually. And this can bring sadness.
Now, there is an opportunity to shift these worries onto what is commonly called artificial intelligence. It is indeed a powerful tool, but with all due respect, let us lower our expectations and not expect it to do everything for us. Let's be realists, or perhaps even a little pessimistic. Currently, AI is merely a highly capable automatic formatter of your thoughts, featuring a powerful enhancement function based on popular information found on the internet. It excels at enriching your text with well-known facts, explaining what you have done, providing various examples, adding links, and clarifying the logic of your written code. This is exactly the kind of routine for which there is never enough time when you are trying to build something new, and when you simply cannot afford to waste energy on things everyone already knows. However, when it comes to what is truly new—things the model doesn't know about yet—you will have to describe them yourself; otherwise, it won't work.
In this process, one can see a software translator just like many others. Only in this case, human language is being translated. And this is, of course, cool—provided the result meets expectations.
File processing based on embedded instructions is like making notes in the margins of pages with directions regarding their content, which need to be implemented later. This can be done manually or with the help of AI, leaving only the verification of the result to you. This approach resembles the work of a "ghostwriter" (a literary assistant): they are quite skilled and knowledgeable, but they remain an assistant, not the author.
Embedded Instructions
Unlike interactive tools (chats), this is purely about executing specific file processing tasks described in natural language. It can be anything: writing in-code documentation, creating page content for a project website, or covering code with unit tests.
In such a paradigm, your instructions written in plain language become the "source code" that the system interprets and executes. This makes it possible to automate and optimize work with files, offering broad capabilities for adjusting actions.
Since we use these instructions as code, it is important to treat them with the same care as traditional source code. Instructions should be stored within the project in a structured and maintain more maintainable manner, ensuring their versioning, testing, and easy access for future updates or collaborative work. This approach helps maintain consistency, traceability, and quality in your workflows.
These instructions are placed in comments and do not directly affect the program's behavior at runtime. The execution of instructions occurs as needed, for example, after code modifications. And AI is intended to be used for this purpose. If desired, you can skip the AI processing step and use the saved instructions as guidelines for manual work. However, the process becomes significantly more efficient if you use specialized tools and focus on testing the results of their work.
These instructions are marked with the @guidance tag and placed in comment blocks to eliminate their impact on the source code or data; therefore, they can only be used in files that support comments. For example, plain text files like *.txt cannot contain such tags. An exception is the @guidance.txt file, which is processed entirely as a @guidance tag for the folder in which it is located. The presence of @guidance tags does not affect the project in any way, introduces no dependencies, and can be added to any project.
Below are examples of using the tag for different file types.
Markdown, HTML, and XML Files
Example:
File: README.md
<!-- @guidance:
**Important:** If any section or content already exists, update it with the latest and most accurate information instead of duplicating or skipping it.
1. **Project Title and Overview:**
- Provide the project name and a brief description based on `src/site/markdown/index.md` content summary.
- Add `` before the title.
- Add `[](https://central.sonatype.com/artifact/org.machanism.machai/machai)` after the title as a new paragraph.
...
-->
Java and TypeScript Files
For Java and TypeScript source files, use the @guidance annotation within a multi-line comment block (but not inside Javadoc or TSDoc comments).
Example for Java:
File: AIFileProcessor.java
/*@guidance:
* Create or update javadoc of AIFileProcessor class.
* Class javadoc description should describe supported functionality and provide examples to use it.
* If the method used as Javadoc documentation is not public or protected, the method name should not be specified.
*/
Example for TypeScript:
/*
* @guidance:
* - Document all exported classes, interfaces, functions, and constants using TSDoc.
* - Provide clear descriptions, parameter details, and usage examples.
* - Keep documentation up to date with code changes.
* - Do not use `@guidance` within TSDoc comments.
*/
Python Files
For Python files, use a multi-line comment (triple quotes) at the beginning of the file or in the appropriate section:
'''
@guidance:
- Follow PEP 257 for docstrings.
- Document all public classes, methods, and functions.
- Keep comments up to date and clear.
'''
Folder-Level Guidance
File: @guidance.txt
In the project's root directory, ensure that the following files are present and correctly created:
**LICENSE.txt**
- Include the full text of the project's license.
- If the license file is missing, create it using the license type defined in the pom.xml file.
- Ensure the license terms are accurate and up to date.
- Use `Copyright 2026 Machanism.org`
Java Package Guidance
For Java packages, the @guidance tag can be used at the package level in the package-info.java file.
Example:
File: package-info.java
package org.machanism.machai.bindex;
/*-
* @guidance:
* **IMPORTANT: ADD JAVADOC TO ALL CLASSES IN THE PACKAGE AND THIS `package-info.java`!**
* - Use Clear and Concise Descriptions:
* - Write meaningful summaries that explain the purpose, behavior, and usage of each element.
* - Avoid vague statements; be specific about functionality and intent.
* - Update `package-info.java`:
* - Analyze the source code within this package.
* - Generate comprehensive package-level Javadoc that clearly describes the package’s overall purpose and usage.
* - Do not include a "Guidance and Best Practices" section in the `package-info.java` file.
* - Ensure the package-level Javadoc is placed immediately before the `package` declaration.
* - Include Usage Examples Where Helpful:
* - Provide code snippets or examples in Javadoc comments for complex classes or methods.
* - Maintain Consistency and Formatting:
* - Follow a consistent style and structure for all Javadoc comments.
* - Use proper Markdown or HTML formatting for readability.
* - Add Javadoc:
* - Review the Java class source code and include comprehensive Javadoc comments for all classes,
* methods, and fields, adhering to established best practices.
* - Ensure that each Javadoc comment provides clear explanations of the purpose, parameters, return values,
* and any exceptions thrown.
* - Escape `<` and `>` as `<` and `>` in `<pre>` content for Javadoc.
*/
Which Files Are Processed
To run the application, you need to specify the project directory and the scan path. The project directory must point to the location of the project (or multiple projects) requiring processing. The scan path defines exactly which files in the project should be analyzed for the presence of @guidance tags to perform subsequent actions on them.
The scan path is specified as a relative or absolute path to a file or folder; you can also use regular expressions (regex) or glob patterns.
The scan directory defines the specific folder from which file scanning and analysis begin. This parameter allows you to focus processing on only a specific part of your project, providing flexibility and control over which files and subdirectories are involved in the process.
The search for files requiring processing is performed by the application without using AI.
Only files containing @guidance tags are taken for processing. For each of them, a separate processing session is created with its own context, so the context window is formed only for the current file being processed. The responsibility for identifying files to process lies with the application, and AI is typically not involved in this.
The application also recognizes the project structure and applies file processing based on the module they belong to. Thanks to this, you can scan complex multi-module projects.
File Processing Order
All project files matching the scan path are sorted based on the depth of their location (path length). Scanning begins with the files located in the deepest subdirectories.
The sequence of file processing should be taken into account if files located closer to the project root rely on information from files located deeper in the structure.
If the project has child modules, they are processed before the main project files: either sequentially (in the order of their declaration in the project) or in parallel (if multithreading is enabled).
Additionally, the application can be run under the control of third-party build systems, such as Maven in per-module mode. In this case, the sequence of module processing will be determined by the dependencies in the project.
After all modules are processed, the application proceeds to process the project-level files.
Using GenAI Services
The model used for file processing based on embedded instructions is specified separately, and its choice determines how high-quality and cost-effective the process will be.
Tools
To enable our "ghostwriter" to perform actions on files, a set of built-in functional tools is used. It is through them that GenAI interacts with the file system, builds the project, runs tests, and even accesses the internet. The following are used for file processing needs:
- Project and file inspection (structure navigation and search).
- File modification (writing, editing, and find-and-replace).
- Command execution and log analysis (building the project, running tests, and analyzing results).
- Project context and metadata (understanding the structure and relationships between modules).
Important security note: Tools that modify files, execute system commands, or make external network requests are used exclusively when directly required by your task. All these actions are strictly controlled by your settings.
You also have the ability to create and add any custom tools to effectively solve specific tasks, or limit their usage by specifying only allowed ones.
Use Cases
The @guidance tags perfectly satisfy the need for automatic synchronization of related data—be it in-code documentation, project documentation, or writing unit tests.
A primary example of using Machai Ghostwriter is the Machai project by Machanism. Here, @guidance tags are used across many files to automatically generate and update code documentation and configurations. Machai is an open-source project whose development focuses on implementing the code that provides the required functionality.
Writing documentation is a secondary process, but at the same time extremely important, as it is necessary for a third-party user to work with the project. However, this is not just about human users. Within this project, specialized library descriptions (bindex) are also created to establish context when using AI for automatic code generation. In this case, the automatic intelligent generation of in-code documentation becomes a critical step, where the @guidance tags define the information that will be used for code generation.
Machai Ghostwriter
Let's look at an application that supports the principles described above: Machai Ghostwriter. It is a lightweight Java application that requires JVM Java 8 to run, although Java 17 or newer is highly recommended for optimal performance.
Machai Ghostwriter is designed for use in CI/CD pipelines, but it can also be run as a CLI tool.
The Machai project also includes a Maven plugin to run Ghostwriter, making it extremely convenient for Maven projects.
The JAR file distribution with all necessary libraries can be downloaded at SourceForge - Machai Ghostwriter or integrated as a Maven Ghostwriter plugin via the dependency: org.machanism.machai:gw-maven-plugin. You can also clone the Machai project if you plan to contribute to its improvement.
Launching
To start file processing, you only need to specify the project path and the scan path—no other parameters are required. All the directives that need to be executed are already contained within the files.
Running via CLI:
java -jar gw.jar
or via Maven:
mvn gw:gw
If you need to narrow down the list of processed files, you should add the scan path:
java -Dgw.model=CodeMie:gpt-5.6-terra-2026-07-09 -jar gw.jar "glob:**/*.md"
or:
mvn gw:gw -Dgw.path=glob:**/*.md -Dgw.model=CodeMie:gpt-5.6-terra-2026-07-09
(or the corresponding configuration is specified directly in the plugin).
The specific AI provider and model are set via the gw.model parameter, which applies to all files. If you need to use different models for different paths, you should run the processing for each of them separately.