engineering-transparency
Skill0 starsChanged 3 days agoMITView on GitHub
Engineering transparency standard. Requires all development work to have clear file responsibilities, function responsibilities, data flow, module relationships, and inspectable implementation descriptions.
In this repository17 other files it gives its agents.
- .cursor/rules/engineering-context.mdcCursor rule
- change-report-deliverySkill
- code-asset-inventorySkill
- data-audit-reproducibilitySkill
- data-first-executionSkill
- documentation-structureSkill
- engineering-context-completenessSkill
- explicit-instruction-fidelitySkill
- interface-contractSkill
- language-expressionSkill
- production-loggingSkill
- repository-publication-hygieneSkill
- task-execution-governanceSkill
- technical-documentationSkill
- testing-verificationSkill
- unfinished-work-trackingSkill
- user-intent-prioritySkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 9 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
Before starting development, the engineering related to the task must be inspected:
- Distinctive: line 35
Call relationships among related modules.
- Distinctive: line 47
When adding, modifying, or deleting files, the following must be stated:
- Distinctive: line 61
Only the files involved in this change and their necessary context need to be described.
- Distinctive: line 90
When data processing is involved, the following must be stated:
- Distinctive: line 121
When multiple modules are involved, use a flow diagram consistent with the actual code.
- Distinctive: line 141
After significant engineering changes, update as appropriate:
- Distinctive: line 152
When the project already has equivalent documentation, maintain the existing documentation preferentially.
- Distinctive: line 168
When something cannot be confirmed, explicitly state:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Engineering Transparency Standard
I. Core Principle
Code is not the only deliverable.
A feature is truly complete only when a developer can understand:
- What it does.
- Which files it consists of.
- What each file is responsible for.
- What each important function is responsible for.
- Where the data comes from.
- What processing the data goes through.
- What the final result is.
- How modules connect to each other.
- How actual behavior is verified.
An implementation that cannot be understood, cannot be traced, and cannot be verified must not be treated as a complete delivery.
II. Before Development: Understand the Existing Engineering
Before starting development, the engineering related to the task must be inspected:
- Relevant directory structure.
- Existing file responsibilities.
- Existing modules and public functions.
- The actual implementation of related functions.
- Call relationships among related modules.
- Where the real data is stored.
- The actual structure of the data.
- Upstream and downstream modules.
- Existing tests and documentation.
Responsibilities must not be inferred from file names alone.
New implementations must not be created without first checking existing capabilities.
III. File Transparency
When adding, modifying, or deleting files, the following must be stated:
| Item | Content |
| File path | Complete relative path |
| File type | Python, JSON, Markdown, etc. |
| File responsibility | What it is actually responsible for |
| Input | What it receives |
| Output | What it produces |
| Upstream | Who calls or generates it |
| Downstream | Who uses it |
| Dependencies | Which modules or external libraries it uses |
| Reason for change | Why it was added, modified, or deleted |
Only the files involved in this change and their necessary context need to be described.
Large projects may provide a relevant directory tree; there is no need to print the entire project pointlessly.
IV. Function Transparency
Important functions that are added, modified, or deleted must have the following stated:
- Function name.
- Containing file.
- Function responsibility.
- Parameter names.
- Parameter types.
- Parameter meanings.
- Required parameters and default values.
- Return value type.
- Return value structure.
- Main processing steps.
- Other functions called.
- File read/write behavior.
- Exception handling.
- Which modules call it.
Providing only the function name is not acceptable.
The description must be based on the actual code; functionality must not be inferred from function naming.
V. Data Transparency
When data processing is involved, the following must be stated:
- Data source.
- Data storage location.
- Actual data structure.
- Field types.
- Field meanings.
- Input count.
- Processing rules.
- Data transformation.
- Filtering conditions.
- Excluded count.
- Final output.
- Output storage location.
Raw data preservation and processing audit follow data-audit-reproducibility.
Execution records follow production-logging.
VI. Call Relationship Transparency
Must state:
- Who calls whom.
- Where the input comes from.
- Which functions the data passes through.
- Which modules modify the data.
- Who generates the output.
- Who consumes it downstream.
- How failures propagate.
When multiple modules are involved, use a flow diagram consistent with the actual code.
Example:
Data collection module ↓ Raw data file ↓ Parsing module ↓ Normalization module ↓ Analysis module ↓ Result output module
The above is only a structural illustration; the actual flow must follow the project implementation.
VII. Engineering Documentation Synchronization
After significant engineering changes, update as appropriate:
- PROJECT_STRUCTURE.md
- MODULES.md
- FUNCTIONS.md
- DATA_DICTIONARY.md
- DATA_FLOW.md
- CHANGELOG.md
These are recommended documentation responsibilities; every project is not required to mechanically create six files.
When the project already has equivalent documentation, maintain the existing documentation preferentially.
VIII. False Transparency Is Forbidden
Forbidden:
- Fabricating real data samples.
- Fabricating function call relationships.
- Guessing functionality from file names.
- Giving only file names without explaining responsibilities.
- Giving only function names without explaining logic.
- Describing planned implementations as already implemented.
- Describing unverified functionality as verified.
- Introducing only the final output without explaining data sources.
- Using abstract terminology to conceal the actual implementation.
When something cannot be confirmed, explicitly state:
- Not checked.
- Not confirmed.
- Not implemented.
- Not verified.
IX. Final Acceptance
Without opening the source code, a developer should be able to understand from the engineering documentation and related data records:
- The actual effect of the feature.
- The file organization.
- Function responsibilities.
- Input and output structures.
- The data processing steps.
- Module call relationships.
- Dependency relationships.
- How to test.
- The actual changes made.
For low-level details that can only be confirmed by reading source code, accurate code locations should be provided; do not pretend the documentation already covers everything.
X. Final Principle
Engineering transparency is not about making the Agent write more text.
It is about giving the engineering itself a clear structure, explicit responsibilities, inspectable data, and real execution records.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

